Cierre de sesión desde tu aplicación
Cómo cerrar la sesión de una persona que entró con UTILIA: revoca sus tokens y, si quieres, pásala por el endpoint de cierre de sesión de OpenID Connect.
Actualizado el . 4 min de lectura
Cuando una persona cierra sesión en tu aplicación, lo importante es que los tokens de UTILIA OS que guardabas dejen de valer. Esta página explica cómo hacerlo y cómo funciona el endpoint de cierre de sesión de OpenID Connect (RP-Initiated Logout 1.0), que UTILIA OS anuncia como end_session_endpoint en /.well-known/openid-configuration.
Lo recomendado: revocar desde tu servidor
Al cerrar sesión, borra tu sesión local y revoca el refresh token con POST /api/oauth/revoke. Revocar cualquiera de los dos tokens de una emisión anula ambos, y el endpoint responde siempre 200.
curl -X POST https://os.utilia.ai/api/oauth/revoke \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'token=REFRESH_TOKEN_DE_LA_PERSONA' \
-d 'token_type_hint=refresh_token'Los SDK oficiales lo hacen con sdk.oauth.logout() en JavaScript y await sdk.oauth.logout() en Python. El detalle de la revocación está en Canje, revocación e introspección de tokens.
La sesión de la persona en UTILIA OS no se cierra: sigue abierta en su navegador, como ocurre con cualquier proveedor de inicio de sesión.
El endpoint de cierre de sesión
/api/oauth/logoutCierre de sesión iniciado por tu aplicación (OpenID Connect)
/api/oauth/logoutIgual que la variante GET, con los parámetros en el cuerpo
Admite hasta 30 peticiones por minuto.
- id_token_hintstring (JWT)
- Un id_token emitido para tu aplicación. Identifica a la persona (sub) y al cliente (aud). Se acepta aunque haya caducado.
- post_logout_redirect_uristring (URL)
- Adónde devolver a la persona. Tiene que estar registrada en el cliente.
- statestring
- Valor que vuelve sin cambios en la redirección, para relacionar la respuesta con tu petición.
Primero comprueba el id_token_hint: su firma RS256 con la clave pública de /api/oauth/jwks, que lleve sub, aud e iss, que iss sea https://os.utilia.ai y que el cliente de aud exista y esté activo. Se acepta aunque haya caducado. Después, lo que hace depende de la sesión y de la dirección de vuelta:
¿Qué hace /api/oauth/logout?
¿Envías un id_token_hint válido?
No lo envías:
Responde 200
{ logged_out: true }
No revoca nada ni redirige.No es válido:
Página de error de UTILIA OS
invalid_request
Con el motivo en error_description (firma, iss o cliente).Sí:
¿La petición lleva la sesión de UTILIA OS?
De otra persona:
Página de error de UTILIA OS
invalid_request
«id_token_hint no coincide con la sesión actual».De esa persona:
Revoca todos los tokens de esa persona para tu cliente.
¿Indicaste una post_logout_redirect_uri?
Sí, registrada:
Vuelve a tu aplicación
302
Con tu state, y los tokens ya revocados.No:
Responde 200
{ logged_out: true }
Con los tokens ya revocados.
Sin sesión:
No revoca nada.
¿Indicaste una post_logout_redirect_uri?
Sí, registrada:
Vuelve a tu aplicación
302
Con tu state, sin revocar ningún token.No:
Página de error de UTILIA OS
invalid_request
«post_logout_redirect_uri es obligatoria cuando no hay sesión activa».
Una dirección que no está en la lista del cliente lleva siempre a la página de error, con «post_logout_redirect_uri no está registrada para este cliente».
HTTP/1.1 302 Found
Location: https://mi-app.com/sesion-cerrada?state=corr-12345
Una redirección del navegador no revoca tokens
Cuando llevas a la persona a esta dirección con una redirección normal, el navegador no envía su sesión de UTILIA OS, así que se aplica la rama «Sin sesión»: el endpoint te devuelve a tu aplicación sin revocar nada. Para que tus tokens dejen de valer, revócalos desde tu servidor como se explica arriba.
Usa el id_token que recibiste al canjear el código; las renovaciones no traen uno nuevo, así que guárdalo.
const params = new URLSearchParams({
id_token_hint: idToken,
post_logout_redirect_uri: "https://mi-app.com/sesion-cerrada",
state: crypto.randomUUID(),
});
window.location.href = `https://os.utilia.ai/api/oauth/logout?${params}`;Registrar las direcciones de vuelta tras el cierre
Una post_logout_redirect_uri solo se acepta si está en post_logout_redirect_uris del cliente. Puedes declararlas en el registro dinámico:
curl -X POST https://os.utilia.ai/api/oauth/register \
-H 'Content-Type: application/json' \
-d '{
"client_name": "Mi app",
"redirect_uris": ["https://mi-app.com/callback"],
"post_logout_redirect_uris": ["https://mi-app.com/sesion-cerrada"]
}'- Hasta 10 direcciones, con
httpohttps. - No se admiten direcciones de redes privadas ni internas. Sí se admiten
localhost,127.0.0.1y::1, que necesitan los clientes nativos. - La comparación es exacta:
https://mi-app.com/yhttps://mi-app.comson distintas. - Si el cliente no tiene ninguna declarada, se acepta cualquiera de sus
redirect_uris. Es una solución provisional: declara las tuyas.
Errores
Si algo falla, la persona acaba en la página de error de UTILIA OS con error=invalid_request y uno de estos motivos en error_description:
error_description | Causa |
|---|---|
id_token_hint inválido | No es un JWT o su firma no se verifica con la clave pública de UTILIA OS |
id_token_hint incompleto | Le falta sub o aud |
iss del id_token_hint no coincide | Falta iss o lo emitió otro servidor |
Cliente del id_token_hint no activo | El cliente de aud no existe o está desactivado |
id_token_hint no coincide con la sesión actual | La sesión de la petición es de otra persona |
post_logout_redirect_uri es obligatoria cuando no hay sesión activa | Sin sesión hay que indicar adónde volver |
post_logout_redirect_uri no está registrada para este cliente | La dirección no está en la lista del cliente |
Qué usar en cada caso
| Quieres | Usa |
|---|---|
| Cerrar la sesión en tu aplicación y anular los tokens que guardabas | POST /api/oauth/revoke desde tu servidor |
| Pasar a la persona por el cierre de sesión estándar y devolverla a tu aplicación | GET /api/oauth/logout con post_logout_redirect_uri |
| Que la persona retire el acceso a tu aplicación | Lo hace ella en Perfil › Aplicaciones |