Aller au contenu principal

Flux d'authentification

Cette page décrit comment les applications clientes s'authentifient auprès de l'API REST du control-plane de VaultPAM.

Vue d'ensemble​

VaultPAM prend en charge deux types d'identifiants :

Type d'identifiantCas d'usageDurée de vie
Jeton de sessionAutomatisation interactive ou de courte duréeContrôlée par le champ expires_in dans la réponse
Jeton d'accès personnel (PAT)Intégrations de longue durée, pipelines CI/CDJusqu'à PAT_ABSOLUTE_MAX_TTL_DAYS (180 jours)

Les deux types sont des jetons Bearer transportés dans l'en-tête Authorization à chaque requête.

Obtention d'un jeton de session​

Étape 1 — POST /api/v1/auth/login​

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

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

Réponse réussie (200) :

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

Le champ expires_in correspond à la durée de vie faisant autorité du jeton, exprimée en secondes. Considérez cette valeur comme la source de vérité pour votre logique d'expiration de jeton — ne vous appuyez sur aucune constante codée en dur.

Réponse d'erreur : tous les échecs d'authentification renvoient une erreur uniforme AUTH_FAILED, quelle que soit la raison réelle de l'échec (mot de passe incorrect, adresse e-mail inconnue, compte verrouillé). Ce comportement est intentionnel — VaultPAM ne révèle pas quelle partie de l'identifiant était invalide.

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

Étape 2 — Identifier l'organisation active​

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

Réponse :

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

Utilisez active_org_id comme valeur de l'en-tête X-Active-Org-Id pour les requêtes ultérieures.

Effectuer des requêtes authentifiées​

Incluez les deux en-têtes à chaque appel d'API :

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

Exemple :

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

Expiration du jeton de session​

Les jetons de session ne sont pas renouvelables. Il n'existe aucun point de terminaison de rafraîchissement — une requête vers /api/v1/auth/refresh renvoie 404. Lorsque votre jeton expire, ré-authentifiez-vous en appelant à nouveau POST /api/v1/auth/login.

Votre client doit :

  1. Stocker la valeur expires_in issue de la réponse de connexion.
  2. Se ré-authentifier avant l'expiration du jeton (recommandé : soustraire 60 secondes comme marge de sécurité).
  3. Réessayer la requête initiale avec le nouveau jeton.
Aucun rafraîchissement automatique

VaultPAM ne prend pas en charge les jetons de rafraîchissement de type OAuth. Une nouvelle connexion est requise à l'expiration.

Déconnexion​

Invalidez immédiatement un jeton de session :

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

Réponse : 204 No Content

Jetons d'accès personnels (PAT)​

Les PAT sont des jetons de longue durée destinés à l'automatisation et aux intégrations. Ils portent le préfixe pat_AIC_.

Créer 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
}

La valeur du jeton est renvoyée une seule fois au moment de la création et ne peut pas être récupérée ultérieurement.

Révoquer un PAT​

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

Réponse : 204 No Content

Application des portées

L'application des portées est déployée progressivement par famille de points de terminaison. Les appels effectués avec un PAT à portée restreinte vers un point de terminaison situé en dehors des portées déclarées du jeton peuvent renvoyer 403. Utilisez le minimum de portées nécessaires à votre cas d'usage.

Stockage des jetons​

Stockez les jetons de manière sécurisée

Les jetons donnent un accès complet à l'API dans la limite des portées accordées. Des jetons mal gérés peuvent entraîner un accès non autorisé.

Pratiques requises :

  1. Ne validez jamais de jetons dans le gestionnaire de code source. Même dans des dépôts privés, des jetons présents dans du code validé constituent un risque de sécurité persistant. Utilisez des variables d'environnement ou un gestionnaire de secrets.
  2. Utilisez un trousseau du système d'exploitation ou un gestionnaire de secrets en production. Exemples : AWS Secrets Manager, HashiCorp Vault, macOS Keychain, trousseau du noyau Linux.
  3. Ne journalisez jamais les valeurs de jeton. Vérifiez la configuration de votre journalisation pour vous assurer que les jetons présents dans les en-têtes ou les corps de requête sont masqués.
  4. Révoquez les jetons lorsqu'ils ne sont plus nécessaires. Utilisez DELETE /api/v1/auth/api-tokens/{token_id} pour les PAT. Les jetons de session expirent automatiquement, mais doivent être considérés comme révocables.
  5. Configurez des outils d'analyse de secrets pour détecter le préfixe pat_AIC_. Ce préfixe est présent sur tous les PAT de VaultPAM et permet à des outils tels que GitHub Advanced Security de signaler une exposition accidentelle.

Étapes suivantes​

Dernière mise à jour le
Report an issue with this page