Skip to content

Obtener un token de acceso para una aplicación

Obtén el token de acceso que una aplicación presenta en cada llamada criptográfica, comprueba si un token sigue activo y finalízalo antes de que venza.

Quién puede hacerlo

  • La propia aplicación obtiene su token. Se autentica como un actor criptográfico de tu tenant con la credencial de ese actor; no interviene ningún rol.
  • Cualquier titular de un token puede revocarlo, y solo un token emitido a sí mismo. Aquí se rechaza el token de una carga de trabajo administrativa.
  • Comprobar si un token está activo (introspección) requiere el permiso para leer tokens. Los roles integrados de administrador del tenant, administrador de acceso, gestor de claves, auditor y lector lo tienen para su propio tenant. Los roles de la plataforma alcanzan todos los tenants solo en un despliegue de nube privada o local; en SaaS no hacen la introspección de nada.

Antes de empezar

  • La aplicación tiene un actor criptográfico con una credencial: un secreto compartido, que la consola muestra una sola vez cuando se emite, o un par de claves registrado cuya clave privada queda en la aplicación. Un administrador del tenant la emite en la pestaña Credenciales del actor, en Actores Criptográficos.
  • El actor tiene al menos un rol. Un actor sin una forma de autenticarse y sin un rol no puede operar.
  • Conoces la dirección del despliegue de ANKASecure.

Pasos

  1. Entrega a la aplicación su credencial sin escribir el secreto en una línea de comandos:
    • SDK de Java: establece anka.auth.clientId y anka.auth.clientSecret en las propiedades que pasas a AnkaSecureSdk, o las variables de entorno ANKASECURE_CLIENT_ID y ANKASECURE_CLIENT_SECRET. Para un par de claves registrado, establece en su lugar anka.auth.actorKeyFile y anka.auth.expectedAudience.
    • CLI criptográfica: ejecuta AnkaSecureCLI init --url <deployment-url> --client-id <actor-id> --client-secret. La opción --client-secret no lleva valor: la CLI pide el secreto, o lee ANKASECURE_CLIENT_SECRET con --silent. Un par de claves se declara con --actor-key-file y --expected-audience.
  2. Autentícate:
    • SDK de Java: new AnkaSecureSdk(properties).authenticate() resuelve la credencial configurada y devuelve un AuthenticatedSdk. authenticateApplication(clientId, clientSecret) y authenticateApplicationWithKeyPair(clientId, signer, expectedAudience) reciben la credencial directamente.
    • CLI criptográfica: cada comando se autentica con la credencial guardada. AnkaSecureCLI view-session muestra el despliegue y la credencial configurados.
    • API: POST /api/v3/auth/token con un cuerpo application/x-www-form-urlencoded grant_type=client_credentials&client_id=<actor-id>&client_secret=<secret>. Para un par de claves registrado, envía client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer y un client_assertion recién firmado en lugar del secreto, nunca ambos. Envía el secreto en el cuerpo, nunca en la cadena de consulta.
  3. Si el actor trabaja dentro de un contexto de intercambio, agrega exchange_context=<context-id> a la solicitud del token. El token queda vinculado a ese contexto.
  4. Envía el token como Authorization: Bearer <access_token> en cada llamada. El SDK lo hace por ti y obtiene un token nuevo cuando al actual le faltan 60 segundos o menos para vencer.
  5. Para comprobar un token, llama a POST /api/v3/auth/token/introspect con el cuerpo de formulario token=<token>, autenticado como una persona o una carga de trabajo que tenga el permiso para leer tokens.
  6. Para finalizar un token antes de que venza, llama a POST /api/v3/auth/token/revoke con el cuerpo de formulario token=<token>, autenticado con un token del mismo titular. En el SDK, close() sobre el AuthenticatedSdk descarta de la memoria el token y la copia guardada de la credencial.

Qué ves cuando funcionó

La solicitud del token responde 200 con access_token, token_type Bearer y expires_in, la vigencia en segundos. A una aplicación no se le emite ningún token de actualización: solicita un token nuevo con su credencial.

La introspección responde {"active": true, ...} con las declaraciones del token, para un token activo de un tenant que puedes leer. La revocación responde 200 con un cuerpo vacío, y el token revocado aparece en Gestión de Tokens como una entrada revocada hasta el momento en que habría vencido.

Si falla

Qué ves Causa Qué hacer
401 con error invalid_client Se rechazó la credencial: un actor desconocido, una credencial incorrecta, revocada o vencida, o un actor deshabilitado. Todas las causas reciben la misma respuesta Revisa el actor y su credencial en Actores criptográficos; emite o rota una credencial si es necesario
400 invalid_request que nombra un parámetro que no se acepta en la URI de la solicitud El secreto u otra credencial se envió en la cadena de consulta Envíalo en el cuerpo de formulario
400 invalid_request en una solicitud con exchange_context El actor no tiene ninguna concesión de capacidad vigente vinculada a ese contexto en su tenant, o el contexto está cerrado Usa un contexto en el que el actor tenga una concesión, u omite el parámetro
429 con Retry-After Demasiadas solicitudes de token desde un mismo origen en un minuto Espera el tiempo indicado, y reutiliza un token hasta que se acerque a su vencimiento
503 (temporarily_unavailable, token-signing-unavailable o dependency-not-ready) El servicio no puede emitir un token en este momento; no se decidió nada sobre la credencial Vuelve a intentarlo después de Retry-After
502 o 504 No se pudo contactar el servicio que verifica las credenciales, o no respondió a tiempo; no se decidió nada sobre la credencial Vuelve a intentarlo más tarde
Una llamada responde 401 aunque el token no venció El token se revocó, o se invalidaron todos los tokens de su titular Autentícate de nuevo; el SDK lanza TokenRevokedException
La introspección responde {"active": false} El token venció, se revocó, pertenece a otro tenant o nunca existió. La respuesta no dice cuál Obtén un token nuevo
La introspección responde 403 Quien llama no tiene el permiso para leer tokens Haz la introspección como una persona o una carga de trabajo que lo tenga

Sin la consola

La consola usa el endpoint de tokens para iniciar la sesión de las personas y la operación de cierre de sesión para finalizarla; una aplicación no usa ninguna de las dos pantallas. Cada paso anterior es una llamada del SDK, la CLI o la API.

Superficie Cómo
SDK de Java AnkaSecureSdk.authenticate(), authenticateApplication(...), authenticateApplicationWithKeyPair(...); AuthenticatedSdk.close()
CLI criptográfica AnkaSecureCLI init, AnkaSecureCLI view-session
API POST /api/v3/auth/token (operación createToken), POST /api/v3/auth/token/introspect (introspectToken), POST /api/v3/auth/token/revoke (revokeToken)

Relacionado

Estas páginas están en inglés: