Service-Accounts

Ein Service-Account ist die Identität einer Maschine, nicht einer Person: einer Integration, einer Auswertung, eines KI-Support-Agenten. Er hat eigene Rollen und funktioniert weiter, wenn Kolleg:innen das Team verlassen. Er lässt sich auf Nur lesen begrenzen, egal welche Tokens für ihn erstellt werden.

Gründe gegen ein persönliches API-Token

Ein persönliches API-Token handelt als die Kolleg:in, die es erstellt hat. Zum Ausprobieren genügt das, für etwas, das dauerhaft läuft, nicht:

• Verlässt die Kolleg:in das Team oder verliert sie eine Rolle, funktioniert die Integration nicht mehr. Wird sie befördert, erhält die Integration unbemerkt mehr Zugriff.
• Alles, was die Integration tut, wird als Arbeit der Kolleg:in protokolliert.
• Sie können der Integration nicht weniger Rechte geben, als die Kolleg:in hat.

Ein Service-Account löst alle drei Probleme. Er hat genau die Rollen, die Sie ihm geben. Nichts, was er tut, wird einer Kolleg:in zugeschrieben. Seine Zugriffsstufe legt ein für alle Mal fest, ob eines seiner Tokens schreiben darf.

Ein Service-Account meldet sich nur mit API-Tokens an. Er hat kein Passwort und kann das Admin-Panel nicht öffnen.

Einen Service-Account anlegen

Service-Accounts verwalten Super-Admins:

1. Öffnen Sie im Admin-Panel Einstellungen → Integrationen → API und wählen Sie Service-Accounts verwalten.
2. Wählen Sie Neuer Service-Account und füllen Sie aus:
   • Name: woran Admins ihn erkennen, zum Beispiel „Support-Agent“. Der Name erscheint in Protokollen und bei Kommentaren, die der Account schreibt.
   • Beschreibung: wofür der Account da ist und wer dafür verantwortlich ist.
   • Zugriff: Nur lesen oder Lesen und schreiben. Siehe Zugriffsstufe.
   • Rollen: welche Bereiche des Admin-Panels der Account sehen kann. Siehe Rollen.
3. Erstellen Sie auf der Seite des Accounts unter Tokens ein Token. Geben Sie ihm eine Bezeichnung, wählen Sie seinen Zugriff und legen Sie ein Ablaufdatum fest. Lesen und schreiben steht nur zur Wahl, wenn die Zugriffsstufe des Accounts Schreiben erlaubt. Ein deaktivierter Account erhält keine neuen Tokens.
4. Kopieren Sie das Token. Es beginnt mit svc- und wird nur dieses eine Mal angezeigt.

Rollen

Ein Service-Account erhält dieselben Rollen wie eine Kolleg:in. Sie legen fest, welche Endpunkte er verwenden kann (siehe Berechtigungen):

Ein neuer Service-Account erhält die Rolle Admin und die Zugriffsstufe Nur lesen. Fügen Sie Teilnehmer:innen oder Zahlungen nur hinzu, wenn seine Aufgabe Teilnehmer:innen oder Zahlungen braucht: Jede Rolle öffnet seinen Tokens mehr personenbezogene Daten. Beide zählen nur zusammen mit Admin oder Super-Admin. Das Admin-Panel speichert sie nicht ohne eine der beiden.

Ein Service-Account gehört immer zu genau einem Mandanten. Die Rolle der globalen Admins von Installationen mit mehreren Mandanten kann er nicht erhalten.

Zugriffsstufe

Die Zugriffsstufe ist die Obergrenze für jedes Token des Accounts:

• read (Nur lesen): Jedes Token des Accounts kann nur lesen, auch eines, das mit Schreibzugriff erstellt wurde, bevor der Account eingeschränkt wurde. Ein Service-Account mit Nur lesen kann nichts ändern, liest aber alles, was seine Rollen erlauben.
• write (Lesen und schreiben): Tokens können lesen und, wenn sie mit Schreibzugriff erstellt wurden, auch schreiben.

Eine geänderte Zugriffsstufe gilt ab der nächsten Anfrage jedes Tokens.

Auf der Kommandozeile anlegen

Auf dem Server legt ferienpass:api:service-account einen Service-Account und sein erstes Token in einem Schritt an. Damit richten Sie eine Integration ohne Browser ein, oder einen neuen Mandanten, in dem sich noch kein Super-Admin angemeldet hat.

bin/console ferienpass:api:service-account "Auswertung" --tenant=elmsbrueck \
  --role=ROLE_ADMIN --valid-until="+90 days" \
  --description="Monthly report on attendances"

bin/console ferienpass:api:service-account "Statistik" --tenant=elmsbrueck \
  --role=admin --role=participants_admin

• Name

  name

  Typ

  argument

  Beschreibung

  Ein Name, an dem Admins den Account erkennen. Pflicht.

• Name

  --tenant

  Typ

  string

  Beschreibung

  Der Mandant (sein Slug). Pflicht bei Installationen mit mehreren Mandanten; ferienpass:tenant:list zeigt sie an.

• Name

  --access

  Typ

  string

  Beschreibung

  read (Standard) oder write.

• Name

  --role

  Typ

  string

  Beschreibung

  Eine Rolle, die vergeben wird; mehrfach angebbar. Akzeptiert ROLE_ADMIN oder nur admin. Der Standard ist ROLE_ADMIN. participants_admin und payments_admin brauchen admin daneben; sonst weist der Befehl sie ab.

• Name

  --description

  Typ

  string

  Beschreibung

  Wofür der Account da ist.

• Name

  --token-name

  Typ

  string

  Beschreibung

  Eine Bezeichnung für das erste Token.

• Name

  --valid-until

  Typ

  string

  Beschreibung

  Ablauf des ersten Tokens, als Datum (2027-01-01) oder relativ (+90 days). Ohne Angabe läuft das Token nicht ab.

• Name

  --no-token

  Typ

  flag

  Beschreibung

  Nur den Account anlegen und Tokens später im Admin-Panel erstellen.

Der Befehl gibt das Token nur einmal aus. Bewahren Sie es auf wie ein Passwort.

Tokens verwalten

Ein Service-Account kann mehrere Tokens halten, zum Beispiel eines je Umgebung. Auf der Seite des Accounts sehen Sie, wann jedes Token zuletzt verwendet wurde (auf fünf Minuten genau). Dort können Sie:

• Ein Token widerrufen. Es funktioniert sofort nicht mehr. Tun Sie das, wenn Sie ein Token nicht mehr brauchen oder es offengelegt worden sein könnte, und um ein Token zu erneuern: Erstellen Sie das neue, stellen Sie die Integration um und widerrufen Sie dann das alte.
• Den Account deaktivieren. Die API weist alle seine Tokens mit 401 (Service account disabled) ab, bis Sie ihn wieder aktivieren. Damit pausieren Sie eine Integration, ohne ihre Einrichtung zu verlieren.
• Den Account löschen. Löscht ihn samt allen seinen Tokens.

Was ein Service-Account hinterlässt

fepli nennt den Service-Account dort, wo ein Datensatz einen Namen als Text speichert. Datensätze, die auf das Konto einer Person verweisen, nennen ihn nicht:

• Kommentare, die er schreibt, zeigen seinen Namen als authorName.
• Einwilligungen, die er widerruft, zeigen seinen Namen als revokedBy.
• Veranstalter-Einladungen, die er verschickt, nennen ihn in der E-Mail. Ihr invitedBy ist null. Verlangt eine Saison von Veranstalter:innen eine Vertraulichkeitserklärung, kann er für diese Saison niemanden einladen, ein neues Veranstalter-Profil zu registrieren (409): Ein Service-Account kann sie nicht unterzeichnen.
• Belege, die er erfasst, haben kein recordedBy, weil dieses Feld auf das Konto einer Person verweist. Ihr recordedByName lautet {name} (Service-Account).
• Änderungen, die er an Anmeldungen vornimmt, erscheinen im Verlauf der Anmeldung im Admin-Panel als {name} (Service-Account). Anmeldungen, die er anlegt, gelten als vom Team eingegeben (createdByAdmin).
• Übergänge des Workflows, die er auf Angebote anwendet (veröffentlichen, absagen, …), erscheinen im Verlauf des Angebots im Admin-Panel als {name} (Service-Account).
• Jeder dieser Einträge behält den Namen, den der Service-Account zu diesem Zeitpunkt hatte.
• Die E-Mails zur Teilnahmeliste der Angebote, die er anlegt, erhält niemand. Wer sie erhält, wählen Sie im Admin-Panel unter Listen-Empfänger:innen. Wie jedes neue Angebot übernehmen diese Angebote ihre Kontaktperson aus dem Veranstalter-Profil der ersten Veranstalter:in, es sei denn, Sie senden contact (Ein Angebot anlegen).