Saltar al contenido principal

Flujo de Autenticación

Esta página describe cómo las aplicaciones cliente se autentican en la API REST del plano de control de VaultPAM.

Descripción General​

VaultPAM admite dos tipos de credenciales:

Tipo de credencialCaso de usoTiempo de vida
Token de sesiónAutomatización interactiva o de corta duraciónControlado por el campo expires_in en la respuesta
Token de Acceso Personal (PAT)Integraciones de larga duración, canalizaciones CI/CDHasta PAT_ABSOLUTE_MAX_TTL_DAYS (180 días)

Ambos tipos son tokens de portador transportados en el encabezado Authorization en cada solicitud.

Adquisición de Token de Sesión​

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

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

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

Respuesta correcta (200):

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

El campo expires_in es el tiempo de vida del token autorizado en segundos. Trate este valor como la fuente de verdad para su lógica de caducidad de tokens — no dependa de ninguna constante codificada.

Respuesta de error: Todos los fallos de autenticación devuelven un error uniforme AUTH_FAILED independientemente de la razón real del fallo (contraseña incorrecta, correo electrónico desconocido, cuenta bloqueada). Esto es intencional — VaultPAM no expone qué parte de la credencial era inválida.

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

Paso 2 — Identificar la organización activa​

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

Respuesta:

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

Utilice active_org_id como valor para el encabezado X-Active-Org-Id en solicitudes posteriores.

Realización de Solicitudes Autenticadas​

Incluya ambos encabezados en cada llamada a API:

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

Ejemplo:

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

Caducidad del Token de Sesión​

Los tokens de sesión no son actualizables. No hay endpoint de actualización — una solicitud a /api/v1/auth/refresh devuelve 404. Cuando su token caduque, vuelva a autenticarse llamando a POST /api/v1/auth/login de nuevo.

Su cliente debe:

  1. Almacenar el valor expires_in de la respuesta de inicio de sesión.
  2. Volver a autenticarse antes de que el token caduque (recomendado: restar 60 segundos como búfer).
  3. Reintentar la solicitud original con el nuevo token.
Sin actualización automática

VaultPAM no admite tokens de actualización de estilo OAuth. Se requiere reinicio de sesión al caducar.

Cierre de Sesión​

Invalide un token de sesión inmediatamente:

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

Respuesta: 204 No Content

Tokens de Acceso Personal (PATs)​

Los PATs son tokens de larga duración para automatización e integraciones. Llevan el prefijo pat_AIC_.

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

El valor del token se devuelve una sola vez en el momento de la creación y no se puede recuperar nuevamente.

Revocar un PAT​

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

Respuesta: 204 No Content

Cumplimiento de alcance

El cumplimiento de alcance se está implementando por familia de endpoints. Las llamadas con un PAT con alcance a un endpoint fuera de los alcances declarados del token pueden devolver 403. Utilice los alcances mínimos necesarios para su caso de uso.

Almacenamiento de Tokens​

Almacene tokens de forma segura

Los tokens proporcionan acceso completo a la API dentro de sus alcances otorgados. Los tokens mal manejados pueden llevar a acceso no autorizado.

Prácticas requeridas:

  1. Nunca confirme tokens en el control de código fuente. Incluso en repositorios privados, los tokens en código confirmado son un riesgo de seguridad persistente. Utilice variables de entorno o un gestor de secretos.
  2. Utilice un llavero del SO o gestor de secretos en producción. Ejemplos: AWS Secrets Manager, HashiCorp Vault, macOS Keychain, Linux kernel keyring.
  3. Nunca registre valores de tokens. Revise su configuración de registro para asegurar que los tokens en encabezados o cuerpos de solicitud estén enmascarados.
  4. Revoque tokens cuando ya no sean necesarios. Utilice DELETE /api/v1/auth/api-tokens/{token_id} para PATs. Los tokens de sesión caducan automáticamente pero deben tratarse como revocables.
  5. Configure herramientas de escaneo de secretos para detectar el prefijo pat_AIC_. Este prefijo está presente en todos los PATs de VaultPAM y permite que herramientas como GitHub Advanced Security marquen exposiciones accidentales.

Próximos pasos​

Última actualización el
Report an issue with this page