Naar hoofdinhoud gaan

Verificatiestroom

Deze pagina beschrijft hoe clienttoepassingen zich verifiëren bij de VaultPAM control-plane REST API.

Overzicht​

VaultPAM ondersteunt twee referentietypen:

ReferentietypeGebruiksscenarioLevensduur
SessietokenInteractieve of kortstondig geautomatiseerde toepassingenBepaald door het veld expires_in in de respons
Personal Access Token (PAT)Langdurige integraties, CI/CD-pijplijnenTot PAT_ABSOLUTE_MAX_TTL_DAYS (180 dagen)

Beide typen zijn Bearer-tokens die in de header Authorization in elk verzoek worden opgenomen.

Verkrijging van sessietoken​

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

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

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

Geslaagde respons (200):

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

Het veld expires_in is de gezaghebbende levensduur van het token in seconden. Beschouw deze waarde als de bron van waarheid voor uw tokenvervallogica — vertrouw niet op hardgecodeerde constanten.

Foutrespons: Alle verificatiefouten retourneren een uniforme AUTH_FAILED-fout, ongeacht de werkelijke failurereden (verkeerd wachtwoord, onbekend e-mailadres, vergrendeld account). Dit is opzettelijk — VaultPAM geeft niet aan welk deel van de referentie ongeldig was.

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

Stap 2 — Identificeer de actieve organisatie​

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

Respons:

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

Gebruik active_org_id als de waarde voor de header X-Active-Org-Id in volgende verzoeken.

Het doen van geverifieerde verzoeken​

Neem beide headers op in elke API-aanroep:

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

Voorbeeld:

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

Vervallen van sessietoken​

Sessietokens kunnen niet worden vernieuwd. Er is geen vernieuwingseindpunt — een verzoek aan /api/v1/auth/refresh retourneert 404. Wanneer uw token verloopt, voer u opnieuw verificatie uit door POST /api/v1/auth/login opnieuw aan te roepen.

Uw client moet:

  1. De waarde expires_in uit de inlogreactie opslaan.
  2. Opnieuw verifiëren voordat het token verloopt (aanbevolen: trek 60 seconden af als buffer).
  3. Het oorspronkelijke verzoek opnieuw indienen met het nieuwe token.
Geen automatische vernieuwing

VaultPAM ondersteunt geen OAuth-achtige vernieuwingstokens. Opnieuw inloggen is vereist bij vervaldatum.

Afmelden​

Een sessietoken onmiddellijk ongeldig maken:

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

Respons: 204 No Content

Personal Access Tokens (PATs)​

PATs zijn langdurige tokens voor automatisering en integraties. Ze hebben het voorvoegsel pat_AIC_.

Een PAT maken​

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
}

De tokenwaarde wordt eenmaal op het moment van maken geretourneerd en kan daarna niet meer worden opgehaald.

Een PAT intrekken​

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

Respons: 204 No Content

Handhavin van bereik

Handhaving van bereik wordt per eindpuntfamilie uitgerold. Aanroepen met een bereikgestelde PAT naar een eindpunt buiten de gedeclareerde bereiken van het token kunnen 403 retourneren. Gebruik de minimale bereiken die nodig zijn voor uw gebruiksscenario.

Tokenopslag​

Tokens veilig opslaan

Tokens bieden volledige API-toegang binnen hun toegekende bereiken. Slecht omgegane tokens kunnen tot onbevoegde toegang leiden.

Vereiste praktijken:

  1. Zet tokens nooit vast in versiebeheer. Zelfs in privé-repositories is code in tokens een blijvend veiligheidsrisico. Gebruik omgevingsvariabelen of een geheimenbeheer.
  2. Gebruik een OS-sleutelhanger of geheimenbeheer in productie. Voorbeelden: AWS Secrets Manager, HashiCorp Vault, macOS Keychain, Linux kernel keyring.
  3. Log nooit tokenwaarden. Controleer uw logboekingsconfiguratie om ervoor te zorgen dat tokens in headers of aanvraaglichamen worden gemaskeerd.
  4. Trek tokens in wanneer ze niet meer nodig zijn. Gebruik DELETE /api/v1/auth/api-tokens/{token_id} voor PATs. Sessietokens verlopen automatisch, maar moeten als intrekbaar worden behandeld.
  5. Configureer gereedschappen voor het scannen van geheimen om het voorvoegsel pat_AIC_ op te sporen. Dit voorvoegsel is aanwezig op alle VaultPAM PATs en stelt gereedschappen zoals GitHub Advanced Security in staat om onopzettelijke blootstelling te markeren.

Volgende stappen​

Laatst bijgewerkt op
Report an issue with this page