Tokens explicados

Auris utiliza tres categorías de tokens: access tokens, refresh tokens e ID tokens. Entender para qué sirve cada token, qué contiene y cómo debe manejarse es esencial para crear integraciones seguras.

Access Token

El access token es la credencial que usa tu aplicación para llamar a APIs protegidas. Por diseño es de corta duración — la expiración predeterminada es de 15 minutos.

Qué es

Un access token es un JWT firmado (JSON Web Token). Es autocontenido: el resource server puede verificar su autenticidad comprobando la firma sin realizar una llamada de red a Auris, usando las claves públicas del endpoint JWKS.

Qué contiene

Un payload de access token de Auris decodificado tiene este aspecto:

{
  "sub": "usr_abc123",
  "iss": "https://api.altovar.net",
  "aud": "your-client-id",
  "iat": 1739880000,
  "exp": 1739880900,
  "jti": "tok_xyz789",
  "type": "user",
  "email": "[email protected]",
  "roles": ["editor", "viewer"],
  "scope": "openid profile email",
  "plan": "enterprise"
}

Cómo usarlo

Envía el access token en el encabezado Authorization en cada solicitud a una API protegida:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImtleS1pZC0xIn0...

Cuándo expira

Los access tokens expiran tras 15 minutos por defecto. Cuando una API devuelve 401 Unauthorized con el código de error TOKEN_EXPIRED, usa el refresh token para obtener un nuevo access token. Los SDK de Auris gestionan esto automáticamente cuando autoRefresh: true está configurado.

Refresh Token

El refresh token permite que tu aplicación obtenga nuevos access tokens sin requerir que el usuario vuelva a iniciar sesión.

Qué es

Un refresh token es una cadena opaca — no contiene claims y no puede decodificarse. Es un valor aleatorio que Auris almacena y valida internamente. Su opacidad es intencional: debe enviarse de vuelta a Auris para obtener algo útil.

Un refresh token tiene este aspecto:

rt_7fKp2mXa9qN3vB8yR4tL1wC6jD5sE0uH

Vida útil predeterminada

Rotación de refresh tokens

Auris implementa la rotación de refresh tokens. Cada uso del refresh token invalida el token actual y emite uno nuevo. Presentar un refresh token ya usado desencadena la revocación de familia de tokens: toda la sesión se termina y todos los tokens de esa familia quedan invalidados.

ID Token

El ID token es un JWT firmado que contiene la identidad del usuario. Solo es emitido cuando el scope openid está incluido en la solicitud.

Qué contiene

{
  "sub": "usr_abc123",
  "iss": "https://api.altovar.net",
  "aud": "your-client-id",
  "iat": 1739880000,
  "exp": 1739883600,
  "nonce": "abc123xyz",
  "email": "[email protected]",
  "email_verified": true,
  "name": "Alice Smith",
  "given_name": "Alice",
  "family_name": "Smith",
  "picture": "https://example.com/alice.jpg",
  "amr": ["pwd", "otp"],
  "acr": "urn:auris:loa:2"
}

Para qué sirve el ID token

El ID token es para tu aplicación — te dice quién es el usuario. No debe enviarse a APIs como credencial de autenticación; para eso está el access token.

Usa el ID token para:

• Mostrar el nombre e imagen del usuario en tu UI
• Saber qué métodos de autenticación se utilizaron (amr)
• Determinar el nivel de autenticación (acr)

Verificación JWT

Auris firma los access tokens e ID tokens con RS256 (RSA Signature con SHA-256). Las claves públicas están disponibles en el endpoint JWKS:

https://api.altovar.net/.well-known/jwks.json

Pasos de verificación

1. Decodifica el encabezado JWT para obtener el kid (key ID)
2. Recupera la clave pública correspondiente del endpoint JWKS
3. Verifica la firma usando la clave pública
4. Valida los claims: iss, aud, exp, iat

Los SDK de Auris realizan esta verificación automáticamente. Para la verificación manual del lado del servidor usa una biblioteca JWT de confianza (por ejemplo, jose en Node.js, firebase/php-jwt en PHP).

Almacenamiento de tokens