Mergeți la conținutul principal

Flux de Autentificare

Această pagină descrie modul în care aplicațiile client se autentifică la API-ul REST al planului de control VaultPAM.

Prezentare generală​

VaultPAM suportă două tipuri de credențiale:

Tip de credențialCaz de utilizareDurată de viață
Token de sesiuneAutomatizare interactivă sau cu durată scurtăControlată de câmpul expires_in din răspuns
Personal Access Token (PAT)Integrări cu durată lungă, conducte CI/CDPână la PAT_ABSOLUTE_MAX_TTL_DAYS (180 de zile)

Ambele tipuri sunt Bearer token-uri transmise în antetul Authorization pe fiecare cerere.

Achiziționarea Token-ului de Sesiune​

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

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

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

Răspuns reușit (200):

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

Câmpul expires_in este durata de viață autoritară a token-ului în secunde. Tratați această valoare ca sursă de adevăr pentru logica expirării token-ului — nu vă bazați pe nicio constantă hard-coded.

Răspuns de eroare: Toate eșecurile de autentificare returnează o eroare uniformă AUTH_FAILED, indiferent de motivul real al eșecului (parolă greșită, email necunoscut, cont blocat). Aceasta este intenționată — VaultPAM nu expune care parte a credențialei a fost invalidă.

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

Pasul 2 — Identificați organizația activă​

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

Răspuns:

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

Utilizați active_org_id ca valoare pentru antetul X-Active-Org-Id pe cererile ulterioare.

Realizarea Cererilor Autentificate​

Includeți ambii anteți pe fiecare apel API:

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

Exemplu:

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

Expirarea Token-ului de Sesiune​

Token-urile de sesiune nu sunt reînnouibile. Nu există niciun punct final de reînnoire — o cerere către /api/v1/auth/refresh returnează 404. Când token-ul dvs. expirează, re-autentificați-vă apelând din nou POST /api/v1/auth/login.

Clientul dvs. ar trebui să:

  1. Stocheze valoarea expires_in din răspunsul de conectare.
  2. Re-autentifice-se înainte ca token-ul să expire (recomandare: scădeți 60 de secunde ca buffer).
  3. Reîncercați cererea inițială cu noul token.
Fără reînnoire automată

VaultPAM nu suportă token-uri de reînnoire în stilul OAuth. Re-conectarea este necesară la expirare.

Deconectare​

Invalidați imediat un token de sesiune:

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

Răspuns: 204 No Content

Personal Access Token-uri (PAT-uri)​

PAT-urile sunt token-uri cu durată lungă pentru automatizare și integrări. Acestea poartă prefixul pat_AIC_.

Creați un PAT​

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
}

Valoarea token-ului este returnată o singură dată la momentul creării și nu poate fi recuperată din nou.

Revocați un PAT​

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

Răspuns: 204 No Content

Aplicarea domeniului de aplicare

Aplicarea domeniului de aplicare se derulează per familie de puncte finale. Apelurile cu un PAT cu domeniu de aplicare la un punct final în afara domeniilor declarate ale token-ului pot returna 403. Utilizați domeniile de aplicare minime necesare pentru cazul de utilizare al dvs.

Depozitarea Token-urilor​

Stochezi token-urile în siguranță

Token-urile oferă acces complet la API în cadrul domeniilor lor acordate. Token-urile gestionate defect pot duce la acces neautorizat.

Practici necesare:

  1. Nu comiteți token-uri la controlul sursei. Chiar și în depozitele private, token-urile în cod comis reprezintă un risc de securitate persistent. Utilizați variabile de mediu sau un manager de secrete.
  2. Utilizați un port-chei al sistemului de operare sau un manager de secrete în producție. Exemple: AWS Secrets Manager, HashiCorp Vault, macOS Keychain, Linux kernel keyring.
  3. Nu înregistrați niciodată valorile token-urilor. Revizuiți configurația jurnalului dvs. pentru a vă asigura că token-urile din anteturi sau corpuri de cereri sunt mascate.
  4. Revocați token-urile când nu mai sunt necesare. Utilizați DELETE /api/v1/auth/api-tokens/{token_id} pentru PAT-uri. Token-urile de sesiune expiră automat, dar ar trebui tratate ca revocabile.
  5. Configurați instrumente de scanare a secretelor pentru a detecta prefixul pat_AIC_. Acest prefix este prezent pe toate PAT-urile VaultPAM și permite instrumentelor precum GitHub Advanced Security să semnalizeze expunerea accidentală.

Pași următori​

Ultima actualizare la
Report an issue with this page