API-Service-Konten

Über Dienstkonten

Wenn ein Client über die externe API Anfragen stellt, werden diese Anfragen im Namen des Nutzerkontos gestellt, das dem Client über die Einstellung „Servicekonto“ zugewiesen ist.

• Alle API-Client-Anforderungsereignisse werden als zum Dienstkontobenutzer gehörend protokolliert.
• Zugriffskontrollprüfungen basieren auf dem Dienstkontonutzer. Das bedeutet, dass Sie Rollen und Berechtigungen verwenden können, um die Aktionen zu steuern, die ein bestimmter Client über seinen Dienstkontobenutzer ausführen darf.
• Mehrmandantenbeschränkungen werden auf Dienstkontonutzer angewendet, die zu einem bestimmten Mandanten gehören.

Nutzerbeschränkungen für Dienstkonten

Um API-Anfragen erfolgreich stellen zu können, muss der Nutzer des Dienstkontos gültig sein und über ein Mindestmaß an Zugriff verfügen. Für Mandanten-API-Clients muss der Nutzer des Dienstkontos zum selben Mandanten gehören wie der API-Client.

Die folgenden Prüfungen werden durchgeführt, um sicherzustellen, dass der Nutzer des Servicekontos diese Anforderungen erfüllt:

• Hat keinen Status von gelöscht oder ausgesetzt
• Ist kein Gastnutzer
• Ist kein Site-Administrator
• Der Mandant des Dienstkontobenutzers stimmt mit dem Mandanten des API-Clients überein (z. B. Nutzer auf Systemebene für Systemclients oder gehört zum gleichen Mandanten wie der Client für Mandanten-Clients)

Wenn eine oder mehrere dieser Prüfungen fehlschlagen, schlagen alle Anfragen an die API vom Client fehl und der Client wird als ungültig markiert. Sie müssen dann das Dienstkonto aktualisieren, um einen neuen gültigen Dienstkontobenutzer auszuwählen.

Rollen und Berechtigungen für Servicekonten

Der Zugriff, den ein bestimmter Kunde innerhalb des Systems haben wird von den Rollen gesteuert, die dem Servicekonto des Kunden zugewiesen sind. Bei der Konfiguration des Dienstkontos empfiehlt es sich, das Dienstkonto auf die Berechtigungen zu beschränken, die es benötigt. Das bedeutet, dass wenn die API-Client-Token abgefangen würden, würde dies einschränken, was mit ihnen gemacht werden könnte.

Es gibt eine API-Benutzerrolle, die Sie dem Dienstkonto zuweisen können, die eine breite Berechtigung zum Abschluss von Aufgaben gibt, für die es bereits Dienste gibt. Dies kann weiter eingegrenzt werden, indem dedizierte Rollen für bestimmte Aufgaben erstellt und diese Servicekonten im entsprechenden Kontext zugewiesen werden.

Für Clients auf Systemebene können Rollen im Systemkontext zugewiesen werden. Mandantenspezifische Kunden haben nur Servicekonten, die zu diesem Mandanten gehören. Daher müssen sie in einem niedrigeren Kontext zugewiesen werden – entweder dem Mandantenkontext (für Funktionen in Bezug auf Nutzer) oder dem Mandantenkategoriekontext (für Funktionen in Bezug auf Kurse oder andere Systemobjekte). Die API-Benutzerrolle kann in beiden Kontexten zugewiesen werden.

Empfohlene Konfiguration des Servicekontos

Wir empfehlen, für jeden von Ihnen erstellten Client einen dedizierten Dienstkontobenutzer zu erstellen. So können Sie eine detaillierte Zugriffskontrolle für den jeweiligen Client festlegen und sicherstellen, dass die API-Nutzung auf Client-Ebene geprüft werden kann.

Wir empfehlen Ihnen, die Nutzer Ihres Servicekontos wie folgt zu konfigurieren:

• Geben Sie einen Benutzernamen, Vornamen und Nachnamen an, der das Konto eindeutig als automatisiertes Konto identifiziert, und seinen Zweck. Sie könnten beispielsweise das Konto als „HR sync API user“ benennen. Dies kann verhindern, dass das Konto von einem anderen Site-Administrator entfernt wird.
• Stellen Sie die Authentifizierungsmethode auf Keine Anmeldung ein, um eine manuelle Anmeldung zu verhindern.
• Erwägen Sie, ein Profilbild festzulegen, das die automatisierte Art des Kontos verstärkt, z. B. Ihr Firmenlogo.
• Normalerweise möchten Sie nicht, dass der Nutzer des Dienstkontos E-Mails erhält. Sie können Benachrichtigungen für den Nutzer vollständig deaktivieren, indem Sie zu seinem Profil gehen und dann Einstellungen > für alteBenachrichtigungen . Hier können Sie das Kontrollkästchen Benachrichtigungen deaktivieren aktivieren.
• Antworten, die von der API empfangen werden, werden in der Zeitzone des Dienstkontonutzers angezeigt. Berücksichtigen Sie die beste Zeitzone und legen Sie die Zeitzone des Nutzers entsprechend in seinem Profil fest.
• Stellen Sie sicher, dass der Nutzer des Dienstkontos über die entsprechenden Berechtigungen für die Aufgabe verfügt, die er ausführen wird. Weitere Informationen finden Sie im Abschnitt Rollen und Berechtigungen des Servicekontos.