API-Service-Konten

Über Dienstkonten

Wenn ein Kunde über die externe API Anfragen stellt, werden diese Anfragen im Namen des Nutzerkontos gestellt, das dem Kunden ü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 Servicekontos 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 Dienstkontonutzers stimmt mit dem Mandanten des API-Clients überein (z. B. Nutzer auf Systemebene für Systemclients oder gehört zum selben 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 Client innerhalb des Systems haben wird von den Rollen gesteuert, die dem Servicekonto des Clients 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 das einschränken, was mit ihnen gemacht werden könnte.

Es gibt eine API-Benutzerrolle, die Sie dem Dienstkonto zuweisen können, die eine umfassende Berechtigung zum Abschluss von Aufgaben gibt, für die es bestehende 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. Auf diese Weise 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 Dienstkontos wie folgt zu konfigurieren:

• Geben Sie einen Benutzernamen, Vornamen und Nachnamen an, der das Konto eindeutig als automatisiertes Konto identifiziert und dessen Zweck angibt. Sie könnten beispielsweise das Konto als „HR sync API user“ bezeichnen. 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, dann Einstellungen > Veraltete Benachrichtigungseinstellungen. Hier können Sie das Kontrollkästchen Benachrichtigungen deaktivieren aktivieren.
• Antworten von der API werden in der Zeitzone des Nutzers des Dienstkontos 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.