Vai al contenuto principale

Flusso di autenticazione

Questa pagina descrive come le applicazioni client si autenticano all'API REST del control-plane di VaultPAM.

Panoramica​

VaultPAM supporta due tipi di credenziali:

Tipo di credenzialeCaso d'usoDurata
Token di sessioneAutomazione interattiva o di breve durataControllata dal campo expires_in nella risposta
Personal Access Token (PAT)Integrazioni di lunga durata, pipeline CI/CDFino a PAT_ABSOLUTE_MAX_TTL_DAYS (180 giorni)

Entrambi i tipi sono token Bearer trasportati nell'intestazione Authorization in ogni richiesta.

Acquisizione del token di sessione​

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

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

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

Risposta corretta (200):

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

Il campo expires_in è la durata autorizzativa del token in secondi. Trattare questo valore come la fonte di verità per la logica di scadenza del token — non fare affidamento su alcuna costante codificata in modo rigido.

Risposta di errore: Tutti i fallimenti di autenticazione restituiscono un errore uniforme AUTH_FAILED indipendentemente dal motivo effettivo del fallimento (password errata, email sconosciuta, account bloccato). Questo è intenzionale — VaultPAM non espone quale parte della credenziale era invalida.

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

Passaggio 2 — Identificare l'organizzazione attiva​

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

Risposta:

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

Utilizzare active_org_id come valore per l'intestazione X-Active-Org-Id nelle richieste successive.

Effettuazione di richieste autenticate​

Includere entrambe le intestazioni in ogni chiamata API:

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

Esempio:

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

Scadenza del token di sessione​

I token di sessione non sono aggiornabili. Non esiste alcun endpoint di aggiornamento — una richiesta a /api/v1/auth/refresh restituisce 404. Quando il token scade, ripetere l'autenticazione chiamando di nuovo POST /api/v1/auth/login.

Il client dovrebbe:

  1. Archiviare il valore expires_in dalla risposta di login.
  2. Ripetere l'autenticazione prima della scadenza del token (consigliato: sottrarre 60 secondi come buffer).
  3. Ripetere la richiesta originale con il nuovo token.
Nessun aggiornamento automatico

VaultPAM non supporta token di aggiornamento in stile OAuth. Il re-login è necessario alla scadenza.

Logout​

Invalidare immediatamente un token di sessione:

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

Risposta: 204 No Content

Personal Access Token (PAT)​

I PAT sono token di lunga durata per automazione e integrazioni. Portano il prefisso pat_AIC_.

Creare 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
}

Il valore del token è restituito una sola volta al momento della creazione e non può essere recuperato di nuovo.

Revocare un PAT​

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

Risposta: 204 No Content

Applicazione dell'ambito

L'applicazione dell'ambito è in fase di distribuzione per famiglia di endpoint. Le chiamate con un PAT con ambito a un endpoint al di fuori degli ambiti dichiarati del token potrebbero restituire 403. Utilizzare gli ambiti minimi necessari per il caso d'uso.

Archiviazione dei token​

Archiviare i token in modo sicuro

I token forniscono accesso completo all'API negli ambiti concessi. I token gestiti male possono portare a accessi non autorizzati.

Pratiche richieste:

  1. Non effettuare mai il commit dei token nel controllo sorgente. Anche nei repository privati, i token nel codice sottoposto a commit rappresentano un rischio di sicurezza persistente. Utilizzare variabili d'ambiente o un gestore di segreti.
  2. Utilizzare un portachiavi del sistema operativo o un gestore di segreti in produzione. Esempi: AWS Secrets Manager, HashiCorp Vault, macOS Keychain, Linux kernel keyring.
  3. Non registrare mai i valori dei token. Rivedere la configurazione della registrazione per assicurarsi che i token nelle intestazioni o nei corpi delle richieste siano mascherati.
  4. Revocare i token quando non sono più necessari. Utilizzare DELETE /api/v1/auth/api-tokens/{token_id} per i PAT. I token di sessione scadono automaticamente ma dovrebbero essere trattati come revocabili.
  5. Configurare strumenti di scansione dei segreti per rilevare il prefisso pat_AIC_. Questo prefisso è presente in tutti i PAT di VaultPAM e consente a strumenti come GitHub Advanced Security di segnalare l'esposizione accidentale.

Passaggi successivi​

Ultimo aggiornamento il
Report an issue with this page