Mit einem Dienstkonto kann dein eigener Agent, dein Skript oder deine Pipeline 50heads nutzen, ohne einer Person zu gehören. Es gehört deiner Organisation. So läuft es weiter, wenn die Person, die es eingerichtet hat, das Unternehmen verlässt, auch wenn dein Identitätsanbieter sie entfernt.

Jedes Dienstkonto hat seine eigene Client-ID und sein Geheimnis, arbeitet in einem deiner Teams, tut nur, was seine Berechtigungen erlauben, und gibt nur innerhalb seiner Limits aus. Seine Fragen gehören diesem Team und verbrauchen dessen Credits.

Wir führen Dienstkonten nach und nach für Organisationen ein. Wenn du unter Einstellungen, dann Organisation keine Dienstkonten siehst, sind sie für deine Organisation noch nicht eingeschaltet. Schreib uns, wenn du sie möchtest.

Wer sie erstellen und ändern kann

Inhaber und Admins eines Teams der Organisation, angemeldet auf der Website. Ein Dienstkonto erstellen, ändern, ausschalten und löschen braucht eine neue Bestätigung, dass du es bist. Wähle Bestätige, dass du es bist, wenn danach gefragt wird. Die Bestätigung gilt 10 Minuten.

Ein Dienstkonto kann sich selbst oder ein anderes nie erstellen, ändern oder erweitern. Ein API-Schlüssel oder eine verbundene App auch nicht.

Ein Dienstkonto erstellen

  1. Geh zu Einstellungen, dann Organisation, und wähle Dienstkonten verwalten.
  2. Gib ihm unter Neues Dienstkonto einen Namen, der sagt, wofür es ist, etwa „Nächtlicher Recherche-Agent“.
  3. Wähle das Team, in dem es arbeitet, wenn deine Organisation mehrere hat.
  4. Hake an, was es darf. Gib ihm nur, was es braucht.
  5. Lege ein Tageslimit fest und, wenn du willst, ein Limit pro Frage, in Credits.
  6. Wähle, wie es sich anmeldet: mit einem Client-Geheimnis oder einem privaten Schlüssel (siehe unten).
  7. Wähle Dienstkonto erstellen.

Das Client-Geheimnis wird einmal gezeigt, zusammen mit der Client-ID und der Token-Adresse. Kopiere sie sofort in die Einstellungen deines Agenten. Wir speichern nur einen Hash des Geheimnisses und können es nicht noch einmal zeigen. Geht es verloren, erstelle ein neues.

Was es darf

Ein Dienstkonto kann jede Berechtigung haben, die ein API-Schlüssel haben kann; die Liste steht unter API-Schlüssel. In seinem Team handelt es mit der Admin-Rolle, begrenzt durch diese Berechtigungen. Es ist nie Inhaber des Teams und steht nie in der Mitgliederliste.

Mit den Organisationsberechtigungen kann es die Organisation in Grenzen lesen und verwalten:

Berechtigung Was sie erlaubt
organization:read Die Organisation sehen, ihre Domains, Anmelderegeln, Single Sign-on, SCIM und Dienstkonten
organization:write Domains, Anmelderegeln und SCIM-Einstellungen ändern
members:read Sehen, wo ein Mitglied angemeldet ist
members:write Ein Mitglied überall abmelden
audit:read Das Audit-Protokoll lesen und exportieren

Manches braucht immer eine Person, die gerade bestätigt hat, dass sie es ist, egal welche Berechtigungen: die Single-Sign-on-Verbindung einrichten oder ändern und ein- oder ausschalten, Single Sign-on zur Pflicht machen, es testen, Notfall-Inhaber ändern, SCIM-Tokens erstellen oder ersetzen, ändern, wie lange Audit-Ereignisse aufbewahrt werden, Aufbewahrungspflichten festlegen oder aufheben, ein Team an einen neuen Inhaber übergeben und alles, was Dienstkonten selbst betrifft.

Ausgabelimits

Jedes Dienstkonto hat ein Tageslimit und kann ein Limit pro Frage haben, in Credits. Eine Frage, die eines davon überschreiten würde, wird abgelehnt, bevor etwas ausgegeben wird, genau wie bei einem API-Schlüssel. Jede Frage braucht einen Idempotency-Key; derselbe Schlüssel noch einmal liefert dieselbe Frage und rechnet nie doppelt ab.

Wie es sich anmeldet

Dein Agent fragt bei der Token-Adresse https://auth.50heads.com/token mit grant_type=client_credentials einen Zugriffstoken an. Der Token gilt eine Stunde; ist er abgelaufen, fragt der Agent erneut. Einen Refresh-Token gibt es nicht.

Mit einem Client-Geheimnis schickst du Client-ID und Geheimnis per HTTP-Basic-Authentifizierung:

curl -s https://auth.50heads.com/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials

Ruf dann die API mit Authorization: Bearer <access_token> auf, wie mit einem API-Schlüssel. Mit scope= kannst du weniger Berechtigungen anfordern, als es hat, nie mehr.

Mit einem privaten Schlüssel signiert dein Agent eine kurze Assertion (private_key_jwt, ES256 oder RS256), statt ein Geheimnis zu schicken. Gib 50heads nur die öffentlichen Schlüssel, als JSON Web Key Set mit höchstens 5 Schlüsseln. Füge nie einen privaten Schlüssel ein. Aussteller und Subjekt der Assertion sind die Client-ID, ihr Empfänger ist die Token-Adresse, sie ist höchstens fünf Minuten alt, und jede wird nur einmal verwendet.

Ein Geheimnis ersetzen

Wähle beim Dienstkonto Neues Geheimnis. Das alte Geheimnis funktioniert so lange weiter, wie du wählst (standardmäßig 24 Stunden, bis zu einer Woche oder gar nicht), damit du deinen Agenten umstellen kannst. Höchstens zwei Geheimnisse funktionieren gleichzeitig. Dieses Geheimnis beenden stoppt ein altes sofort.

Ausschalten oder löschen

  • Ausschalten stoppt seine Tokens ab der nächsten Anfrage, und es bekommt keine neuen. Einschalten holt es zurück.
  • Löschen beendet seine Tokens und Geheimnisse endgültig, ebenso die Webhook-Endpunkte, die es erstellt hat. Die Fragen, die es gestellt hat, bleiben beim Team, und es bleibt im Audit-Protokoll.

Eine Person zu entfernen, von Hand oder über deinen Identitätsanbieter, wirkt sich nie auf ein Dienstkonto aus.

Im Audit-Protokoll

Jede Änderung an einem Dienstkonto wird mit der Person festgehalten, die sie gemacht hat. Was ein Dienstkonto selbst tut, etwa eine Frage stellen, eine Domain hinzufügen oder das Audit-Protokoll exportieren, wird mit seinem Namen und dem Akteurstyp service_account festgehalten. Siehe Das Audit-Protokoll.

Siehe auch