# Tokens

Para qué sirve cada token de ID, de acceso y de refresco, quién valida cuál, cuánto viven, y cómo funcionan la rotación y el almacenamiento seguro.

Un único inicio de sesión puede producir tres tokens distintos, y la mayoría de los problemas de integración vienen de confundir para qué sirve cada uno. Esta página es la tabla de consulta: propósito, audience, tiempo de vida y reglas de manejo por tipo de token.

## Los tres tokens [#the-three-tokens]

| Token | Dirigido a | Para qué sirve | Validado por |
|---|---|---|---|
| **ID token** | La aplicación (su client ID es la audience) | Demuestra *quién ha iniciado sesión* y transporta claims de perfil (`sub`, `name`, `email`, ...). | La aplicación, normalmente a través de su biblioteca OIDC. |
| **Access token** | Una API (su identificador es la audience) | Autoriza *las llamadas a esa API* y transporta los scopes concedidos. | La API, en cada solicitud; consulte [Proteger una API](https://dts-identity.com/es/docs/quickstarts/protect-an-api.md). |
| **Refresh token** | La propia plataforma | Permite a la aplicación renovar más tarde su access token sin devolver al usuario a la página de inicio de sesión. | La plataforma, en el endpoint de token. |

El error más frecuente es enviar el **ID token a una API**. Un ID token autentica al usuario *ante la aplicación* y su audience es el client ID de la aplicación, así que una API bien implementada lo rechaza. Envíe el **access token** a las APIs y trátelo como opaco dentro del cliente: su contenido es un contrato entre la plataforma y la API, no con la aplicación.

## Formatos de access token [#access-token-formats]

- **Para una API registrada** (el cliente ha pasado el identificador de la API como resource indicator): un **JWT firmado** con el identificador de la API en `aud`, los scopes concedidos en `scope` y el llamante en `sub`. La API lo valida sin conexión frente a las claves publicadas por la plataforma. Con [RBAC](https://dts-identity.com/es/docs/integrations/apis.md#role-based-access-control) activado, transporta además los claims `permissions` / `roles`.
- **Sin API de destino**: un token **opaco**, utilizable únicamente en el endpoint UserInfo de la plataforma. Los tokens opacos (y los refresh tokens) pueden comprobarse en el endpoint estándar de token introspection y anularse en el endpoint de revocación; ambos figuran en el documento de discovery. Un cliente puede hacer introspection de sus propios tokens; los tokens de otros clientes solo puede hacerlo una aplicación creada en la Admin Console con un client secret o una clave (un resource server), no una registrada dinámicamente.

## Tiempos de vida [#lifetimes]

| Token / artefacto | Tiempo de vida | Dónde se configura |
|---|---|---|
| Authorization code | 1 minuto, de un solo uso | Fijo |
| Access token para una API | 1 día de forma predeterminada (2 horas en flujos implicit) | Por API, en su pestaña de ajustes; consulte [APIs](https://dts-identity.com/es/docs/integrations/apis.md) |
| Access token sin API de destino (UserInfo) | 1 hora | Fijo |
| Token machine-to-machine sin API de destino | 10 minutos | Fijo |
| ID token | 1 hora de forma predeterminada | Por aplicación; consulte [Aplicaciones](https://dts-identity.com/es/docs/integrations/applications.md#token-lifetimes-and-logout) |
| Refresh token | 14 días, ampliables por rotación hasta 1 año en total | Fijo; véase más abajo |
| Device code | 10 minutos | Fijo |
| Sesión de single sign-on | Tiempos de espera por inactividad y absoluto | Para toda la instancia en **Configuración → Inicio de sesión**, con posibilidad de anularlos por directorio; consulte [Configuración de inicio de sesión](https://dts-identity.com/es/docs/settings/login.md) |

## Refresh tokens [#refresh-tokens]

**Cuándo se emite uno.** La aplicación debe tener activado el grant type **refresh token**. Las aplicaciones de primera parte (sin pantalla de consentimiento) reciben entonces uno automáticamente; las aplicaciones con **Requerir el consentimiento del usuario** activado solo reciben uno si el usuario ha concedido el scope `offline_access`.

**Rotación.** Los refresh tokens rotan en lugar de vivir para siempre:

- Un cliente **public** (aplicación de página única o nativa, sin client secret) recibe un refresh token de sustitución en **cada uso**. En los clientes basados en navegador, el sustituto conserva el tiempo de vida restante, de modo que la rotación no lo prolonga.
- Un cliente **confidential** conserva su refresh token hasta que ha transcurrido aproximadamente el 70% de su tiempo de vida; el siguiente uso emite entonces un token nuevo de 14 días.
- Rote como rote, una cadena de refresh tokens termina como muy tarde **un año** después del inicio de sesión original; a partir de ahí, el usuario debe volver a iniciar sesión.

Un refresh token ya rotado (usado) deja de ser válido; si su cliente persiste tokens, guarde siempre el más reciente de cada respuesta.

**Revocación.** Una aplicación puede anular de forma proactiva un refresh token en el endpoint de revocación (que figura en el documento de discovery), lo que es una buena práctica durante su propio cierre de sesión. Los usuarios pueden finalizar sus sesiones desde su portal de cuenta («cerrar sesión en todas partes»), y los tokens ligados a la sesión terminan con ellas; consulte la sección siguiente.

## Tokens y cierre de sesión [#tokens-and-sign-out]

El cierre de sesión finaliza la sesión SSO de la plataforma, pero los tokens siguen sus propias reglas:

- Los tokens emitidos **sin** `offline_access` están ligados a la sesión. Los tokens opacos dejan de funcionar en cuanto la sesión termina.
- Un **JWT access token no puede retirarse**: las APIs lo validan sin conexión, así que sigue siendo técnicamente utilizable hasta su caducidad incluso después del cierre de sesión. Si esa ventana importa para una API, acorte el tiempo de vida de su access token en lugar de confiar en el cierre de sesión.
- **Los refresh tokens obtenidos con `offline_access` sobreviven al cierre de sesión** de forma intencionada (eso es precisamente el acceso sin conexión). Terminan cuando caducan, alcanzan el límite de un año o se revocan.
- A las aplicaciones se les puede *informar* del cierre de sesión mediante **back-channel logout**; consulte [Duración de los tokens y cierre de sesión](https://dts-identity.com/es/docs/integrations/applications.md#token-lifetimes-and-logout). Cómo se relacionan la sesión de plataforma, las sesiones de las aplicaciones y la sesión de un proveedor de identidad superior se explica en [Ciclo de vida del usuario: Sesiones](https://dts-identity.com/es/docs/directories/user-lifecycle.md#sessions).

## Almacenar tokens [#storing-tokens]

- **Frente a los scripts que se ejecutan en la página** (cross-site scripting): un token en `localStorage` o en `sessionStorage` es legible por cualquier script inyectado. Las aplicaciones de navegador guardan los tokens solo en memoria y salvan el corto tiempo de vida del access token con la rotación de refresh tokens.
- **Frente a otro software del dispositivo**: un token en un archivo plano o en un almacén de preferencias está a una lectura de archivo de distancia. Las aplicaciones nativas utilizan el almacén protegido del sistema operativo (Keychain, Keystore, credential locker).
- **Frente al navegador en su conjunto**: una aplicación de servidor nunca necesita que el navegador guarde un token. Mantenga los tokens en el servidor, ligados a su propia cookie de sesión.
- **Frente a fugas en el transporte y en los registros**: envíe los tokens solo sobre TLS en la cabecera `Authorization`, nunca en URLs (acaban en los registros de proxy y de servidor), y no los escriba nunca usted mismo en los registros.

## Temas relacionados

- [Proteger una API](https://dts-identity.com/es/docs/quickstarts/protect-an-api.md): validar access tokens en su propia API.
- [APIs](https://dts-identity.com/es/docs/integrations/apis.md): scopes, audiences y ajustes de token por API.
- [Aplicaciones](https://dts-identity.com/es/docs/integrations/applications.md): ajustes de token y de cierre de sesión por aplicación.
- [Configuración de inicio de sesión](https://dts-identity.com/es/docs/settings/login.md): los tiempos de espera de la sesión SSO.
