Zum Hauptinhalt springen

Authentifizierungsablauf

Diese Seite beschreibt, wie sich Client-Anwendungen bei der REST-API der VaultPAM-Control-Plane authentifizieren.

Überblick​

VaultPAM unterstützt zwei Arten von Anmeldeinformationen:

Art der AnmeldeinformationAnwendungsfallLebensdauer
SitzungstokenInteraktive oder kurzlebige AutomatisierungGesteuert durch das Feld expires_in in der Antwort
Personal Access Token (PAT)Langlebige Integrationen, CI/CD-PipelinesBis zu PAT_ABSOLUTE_MAX_TTL_DAYS (180 Tage)

Beide Arten sind Bearer-Token, die im Authorization-Header bei jeder Anfrage übermittelt werden.

Beschaffung eines Sitzungstokens​

Schritt 1 — POST /api/v1/auth/login​

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "operator@example.com",
  "password": "<password>"
}

Erfolgreiche Antwort (200):

{
  "access_token": "eyJ...",
  "expires_in": 3600
}

Das Feld expires_in gibt die maßgebliche Token-Lebensdauer in Sekunden an. Behandeln Sie diesen Wert als verbindliche Quelle für Ihre Logik zur Token-Gültigkeit — verlassen Sie sich nicht auf eine fest codierte Konstante.

Fehlerantwort: Alle Authentifizierungsfehler geben einen einheitlichen AUTH_FAILED-Fehler zurück, unabhängig vom tatsächlichen Fehlergrund (falsches Passwort, unbekannte E-Mail-Adresse, gesperrtes Konto). Dies ist beabsichtigt — VaultPAM gibt nicht preis, welcher Teil der Anmeldeinformation ungültig war.

{
  "error": "AUTH_FAILED",
  "message": "Authentication failed."
}

Schritt 2 — Aktive Organisation ermitteln​

GET /api/v1/org/memberships
Authorization: Bearer <access_token>

Antwort:

{
  "active_org_id": "org_01HXZ...",
  "memberships": [
    { "org_id": "org_01HXZ...", "role": "operator" }
  ]
}

Verwenden Sie active_org_id als Wert für den X-Active-Org-Id-Header bei nachfolgenden Anfragen.

Authentifizierte Anfragen stellen​

Fügen Sie bei jedem API-Aufruf beide Header ein:

Authorization: Bearer <access_token>
X-Active-Org-Id: <active_org_id>

Beispiel:

GET /api/v1/safes
Authorization: Bearer eyJ...
X-Active-Org-Id: org_01HXZ...

Ablauf des Sitzungstokens​

Sitzungstoken sind nicht erneuerbar. Es gibt keinen Refresh-Endpunkt — eine Anfrage an /api/v1/auth/refresh gibt 404 zurück. Wenn Ihr Token abläuft, authentifizieren Sie sich erneut, indem Sie erneut POST /api/v1/auth/login aufrufen.

Ihr Client sollte:

  1. Den Wert von expires_in aus der Login-Antwort speichern.
  2. Sich erneut authentifizieren, bevor das Token abläuft (empfohlen: 60 Sekunden als Puffer abziehen).
  3. Die ursprüngliche Anfrage mit dem neuen Token wiederholen.
Keine automatische Erneuerung

VaultPAM unterstützt keine OAuth-artigen Refresh-Token. Bei Ablauf ist eine erneute Anmeldung erforderlich.

Abmeldung​

Ein Sitzungstoken sofort ungültig machen:

POST /api/v1/auth/logout
Authorization: Bearer <access_token>
X-Active-Org-Id: <active_org_id>

Antwort: 204 No Content

Personal Access Tokens (PATs)​

PATs sind langlebige Token für Automatisierung und Integrationen. Sie tragen das Präfix pat_AIC_.

Ein PAT erstellen​

POST /api/v1/auth/api-tokens
Authorization: Bearer <access_token>
X-Active-Org-Id: <active_org_id>
Content-Type: application/json

{
  "name": "ci-pipeline-token",
  "scopes": ["safes.read"],
  "expires_in_days": 90
}

Der Token-Wert wird bei der Erstellung einmalig zurückgegeben und kann nicht erneut abgerufen werden.

Ein PAT widerrufen​

DELETE /api/v1/auth/api-tokens/{token_id}
Authorization: Bearer <access_token>
X-Active-Org-Id: <active_org_id>

Antwort: 204 No Content

Durchsetzung von Berechtigungsbereichen

Die Durchsetzung von Berechtigungsbereichen (Scopes) wird schrittweise pro Endpunktfamilie eingeführt. Aufrufe mit einem eingeschränkten PAT an einen Endpunkt außerhalb der deklarierten Scopes des Tokens können 403 zurückgeben. Verwenden Sie die minimal erforderlichen Scopes für Ihren Anwendungsfall.

Token-Speicherung​

Token sicher speichern

Token gewähren vollen API-Zugriff innerhalb ihrer erteilten Scopes. Falsch behandelte Token können zu unbefugtem Zugriff führen.

Erforderliche Vorgehensweisen:

  1. Übergeben Sie Token niemals an die Versionsverwaltung. Selbst in privaten Repositorys stellen Token in eingecheckten Code ein dauerhaftes Sicherheitsrisiko dar. Verwenden Sie Umgebungsvariablen oder einen Secrets Manager.
  2. Verwenden Sie in der Produktion einen Betriebssystem-Schlüsselbund oder einen Secrets Manager. Beispiele: AWS Secrets Manager, HashiCorp Vault, macOS Keychain, Linux Kernel Keyring.
  3. Protokollieren Sie niemals Token-Werte. Überprüfen Sie Ihre Protokollierungskonfiguration, um sicherzustellen, dass Token in Headern oder Anfragetexten maskiert werden.
  4. Widerrufen Sie Token, wenn sie nicht mehr benötigt werden. Verwenden Sie DELETE /api/v1/auth/api-tokens/{token_id} für PATs. Sitzungstoken laufen automatisch ab, sollten aber als widerrufbar behandelt werden.
  5. Konfigurieren Sie Secret-Scanning-Tools, um das Präfix pat_AIC_ zu erkennen. Dieses Präfix ist auf allen VaultPAM-PATs vorhanden und ermöglicht es Tools wie GitHub Advanced Security, versehentliche Offenlegungen zu kennzeichnen.

Nächste Schritte​

Zuletzt aktualisiert am
Report an issue with this page