Service-Accounts und API-Tokens

Warum Sie keinen persönlichen Account verwenden sollten

Die Verwendung eines persönlichen Benutzeraccounts für CI/CD oder Automatisierung schafft mehrere Probleme:

• Der Token ist an einen Mitarbeiter gebunden — wenn dieser das Unternehmen verlässt, brechen alle Integrationen ab
• Die Berechtigungen eines persönlichen Accounts sind oft umfangreicher, als das Skript benötigt
• Aktionen erscheinen im Audit-Log unter dem Namen der Person, nicht dem der Pipeline
• Der Entzug des Zugriffs erfordert das Löschen oder Ändern des persönlichen Accounts

Ein dedizierter Service-Account trennt die Automatisierung von menschlichen Identitäten, folgt dem Prinzip der minimalen Berechtigungen und macht den Audit-Trail eindeutig.

---

Schritt 1 — Eine Service-Account-Rolle erstellen

Erstellen Sie vor dem Anlegen des Accounts eine Rolle, die nur das gewährt, was die Automatisierung benötigt.

1. Gehen Sie zu Settings → User management → Roles.
2. Klicken Sie auf Create role und benennen Sie sie (z. B. CI/CD service account oder Rotation bot).
3. Aktivieren Sie nur die folgenden Berechtigungen:
   • Use API (erforderlich für die Token-Generierung)
   • Kein Zugriff auf Benutzerverwaltung, Systemeinstellungen, LDAP, SSO oder die Verwaltung von Tresortypen
4. Klicken Sie auf Create.

Der Verzeichniszugriff (welche Tresore und Ordner der Service-Account lesen oder schreiben darf) wird separat konfiguriert, wenn der Service-Account erstellt wird

Eine Rolle pro Pipeline-Typ

Wenn Sie mehrere Automatisierungs-Anwendungsfälle haben (Deploy-Bot, Rotationsskript, Audit-Exporter), erstellen Sie separate Rollen mit unterschiedlichen Berechtigungssätzen. Dies begrenzt den Schadensumfang, falls ein Token kompromittiert wird.

---

Schritt 2 — Den Service-Account erstellen

1. Gehen Sie zu Settings → User management → Users.
2. Klicken Sie auf Create user.
3. Verwenden Sie ein klar identifizierbares Login, z. B. svc-cicd-production oder svc-rotation-bot.
4. Weisen Sie die in Schritt 1 erstellte Rolle sowie ggf. Gruppen zu.
5. Klicken Sie auf Create.

Wenn Sie LDAP verwenden, erstellen Sie einen dedizierten LDAP-Service-Account in Ihrem Verzeichnis und ordnen Sie ihn Passwork zu. Verwenden Sie keinen AD-Service-Account erneut, der über andere Systemrechte verfügt.

---

Schritt 3 — Tresorzugriff gewähren

Der Service-Account muss den Tresoren und Ordnern, auf die er zugreifen muss, explizit hinzugefügt werden.

1. Öffnen Sie das Profil des Service-Accounts.
2. Legen Sie auf dem Tab Access rights die notwendigen Zugangslevel für die entsprechenden aufgelisteten Tresore fest.

Anwendungsfall	Minimales Zugangslevel
CI/CD-Pipeline (Secrets für die Bereitstellung lesen)	Nur Lesen
Rotationsskript (Secret-Werte aktualisieren)	Lesen und Bearbeiten
Audit-/Reporting-Skript	Nur Lesen
Migration / Massenimport	Vollständiger Zugang auf den Ziel-Tresor

Verwenden Sie den Zugriff auf Ordnerebene, wenn der Service-Account nur eine Teilmenge des Tresors benötigt.

---

Schritt 4 — Das Token-Paar generieren

1. Öffnen Sie das Profil des Service-Accounts
2. Öffnen Sie das Menü API tokens im rechten Bereich und klicken Sie auf Create API token.
3. Kopieren Sie beide — den accessToken und den refreshToken — sofort; sie werden nur einmal angezeigt.

Tokens sicher aufbewahren

Speichern Sie Tokens niemals im Quellcode, in .env-Dateien, die in Repositorys committet werden, oder in CI/CD-Job-Logs. Verwenden Sie den verschlüsselten Secret-Speicher Ihrer CI/CD-Plattform (GitHub Secrets, GitLab CI/CD mit maskierten Variablen, HashiCorp Vault, AWS Secrets Manager usw.).

---

Lebenszyklus des Token-Paars

Die Passwork-API verwendet zwei Tokens mit unterschiedlichen Lebensdauern:

Token	Typische Lebensdauer	Zweck
accessToken	Minuten bis Stunden	Wird jedem API-Request als Authorization: Bearer hinzugefügt
refreshToken	Tage bis Wochen	Wird verwendet, um ein neues Token-Paar zu erhalten, wenn der Access-Token abläuft

Wenn accessToken abläuft, gibt die API HTTP 401 mit dem Code accessTokenExpired zurück. Die Integration ruft dann den Refresh-Endpunkt auf und aktualisiert beide Tokens.

Der Python-Connector erledigt dies automatisch. Für Shell-Skripte, die passwork-cli verwenden, verarbeitet die CLI die Token-Erneuerung ebenfalls transparent, wenn PASSWORK_REFRESH_TOKEN bereitgestellt wird.

---

Strategie zur Token-Rotation

Die regelmäßige Rotation des Token-Paars des Service-Accounts reduziert das Risiko durch das Leaken von Tokens.

Empfohlene Token-Lebensdauern nach Anwendungsfall:

Anwendungsfall	accessToken-Lebensdauer	refreshToken-Lebensdauer
CI/CD-Job (ephemer)	15–60 Minuten	1 Tag
Dauerhaft laufender Dienst (Monitoring, Rotation-Bot)	1–4 Stunden	30 Tage
Manuelles/geplantes Skript	1 Stunde	7 Tage

Tokens über die API rotieren:

Drei Endpunkte stehen zur Verfügung (die vollständige Referenz finden Sie unter API-Token-Rotation):

Vollständiges Paar rotieren

curl -s --request POST \
  --url "https://passwork.example.com/api/v1/sessions/refresh" \
  --header 'Content-Type: application/json' \
  --header 'X-Response-Format: raw' \
  --header "Authorization: Bearer $PASSWORK_TOKEN" \
  --data "{\"refreshToken\": \"$PASSWORK_REFRESH_TOKEN\"}" | jq .

Nur Access-Token rotieren

curl -s --request POST \
  --url "https://passwork.example.com/api/v1/sessions/refresh-access-token" \
  --header 'Content-Type: application/json' \
  --header 'X-Response-Format: raw' \
  --data "{\"accessToken\": \"$PASSWORK_TOKEN\"}" | jq .

---

Das Paradox der Token-Speicherung

Passwork ist der Secret Store — aber Sie benötigen ein Anmeldedatum, um darauf zuzugreifen. Wo speichern Sie den Passwork-Token?

Empfohlene Ansätze:

Umgebung	Wo Passwork-Tokens gespeichert werden
CI/CD (GitHub Actions, GitLab)	Verschlüsselter Secret-Speicher der Plattform (maskierte Variablen)
Kubernetes-Workloads	Kubernetes Secret, idealerweise befüllt durch einen externen Secret-Operator
Dauerhaft laufende Dienste	Umgebungsvariable, beim Start über einen Secret Store höherer Vertrauensstufe oder ein Konfigurationsmanagement injiziert
Entwickler-Workstations	.env-Datei, die nicht in das VCS committet wird, oder OS-Schlüsselbund

Das zentrale Prinzip: Passwork-Tokens sind Bootstrap-Anmeldedaten. Sie liegen eine Ebene über den Secrets, die sie schützen. Sie benötigen einen starken Schutz — nicht so stark wie der Root-Schlüssel eines Cloud-Anbieters, aber stärker als ein Datenbankpasswort einer Anwendung.

LLM version