Saltar al contenido principal
Puede usar Custom Token Exchange para resolver escenarios avanzados de integración en los que no se pueden aplicar las estrategias habituales de inicio de sesión federado basadas en redirigir al usuario final debido a limitaciones técnicas o de experiencia de usuario. El código proporcionado para los casos de uso está incompleto y solo pretende mostrar los pasos lógicos que puede seguir con su código para abordar el caso de uso. Consulte los ejemplos de código para ver ejemplos de código más detallados.
Auth0 recomienda usar, siempre que sea posible, el inicio de sesión federado habitual y listo para usar. Al permitirle establecer el usuario para la transacción, Custom Token Exchange le ofrece más flexibilidad, a cambio de asumir la responsabilidad adicional de validar y gestionar la transacción de forma segura.

​
Casos de uso

En esta sección se describen casos de uso de ejemplo y fragmentos de código específicos, junto con recomendaciones para implementar su escenario. Para ilustrar estos casos de uso, utilizaremos GearUp, una empresa ficticia de alquiler de coches.

​
Caso de uso: Migración sin fricciones a Auth0

GearUp tiene una app móvil que usan millones de personas y necesita modernizar su solución de identidad, por lo que ha decidido pasarse a Auth0. Sin embargo, quiere evitar obligar a los usuarios a volver a autenticarse mientras migra desde su Proveedor de identidad (IdP) heredado, ya que eso añade fricción a la experiencia de usuario. Para resolverlo y limitar los riesgos, GearUp está migrando de forma incremental. Para cada usuario, quiere intercambiar el Token de actualización de su IdP heredado por un token de acceso, un Token de actualización y un de Auth0. Esto permite que su app empiece a usar Auth0 sin interrupciones como IdP para ese usuario, además de consumir las API de GearUp con tokens emitidos por Auth0. Una vez que el intercambio se haya completado para todos los usuarios, la app habrá migrado por completo y el IdP anterior podrá desconectarse, todo ello sin afectar a los usuarios finales ni al negocio de GearUp.
Como requisito previo, GearUp ha realizado una importación masiva de usuarios en su inquilino de Auth0 y la app móvil dispone de un Token de actualización heredado válido para cada usuario que se va a migrar.
  1. La app móvil realiza una solicitud a Auth0 para intercambiar el Token de actualización heredado y lo establece como token de sujeto.
  2. Se ejecuta la Action correspondiente del perfil de intercambio de tokens personalizado. Valida el Token de actualización con el IdP heredado y obtiene el ID de usuario externo del perfil del usuario. Después aplica la directiva de autorización requerida y, por último, asigna el usuario.
  3. Auth0 responde con un token de acceso, un ID token y un Token de actualización de Auth0.
  4. La app móvil ya puede usar las API del cliente con tokens de Auth0 sin que el usuario tenga que volver a autenticarse.
La siguiente muestra de código muestra cómo implementar esto en la Action de intercambio de tokens personalizado. En este caso, como los perfiles de usuario ya se importaron en una conexión de base de datos de Auth0:
  • No queremos crear el usuario.
  • No queremos actualizar el perfil del usuario.
Usamos el ID de usuario del IdP externo para asignar el usuario a la conexión correspondiente.

​
Caso de uso: Reutilizar un proveedor de autenticación externo

Otro caso de uso consiste en que GearUp se asocie con Air0, un proveedor líder del sector de viajes, para ofrecer sus servicios de alquiler de autos directamente dentro de la aplicación de página única de Air0. GearUp ofrece una biblioteca de JavaScript que encapsula el uso de sus API. De esta manera, las API de GearUp pueden ser consumidas fácilmente por el sitio web de Air0, donde se ofrecen servicios de alquiler de autos. Una vez más, la solución debe ser transparente para los usuarios finales, evitando que tengan que volver a autenticarse en GearUp. Para resolver este problema, la biblioteca de JavaScript de GearUp puede realizar un intercambio de tokens usando el token de ID externo de Air0 como entrada. Esto da como resultado un token de acceso de Auth0 que se genera y se asocia con el usuario correspondiente de GearUp en función de su correo electrónico. Una vez que la biblioteca de GearUp obtiene el token de acceso, puede empezar a usar las API de GearUp para ofrecer servicios de alquiler de autos directamente dentro del sitio web de Air0.
Como requisito previo, GearUp ha configurado el IdP de Air0 como una conexión empresarial o social federada, para que el usuario pueda autenticarse mediante inicio de sesión federado o, alternativamente, mediante Custom Token Exchange de la siguiente manera:
  1. La aplicación de página única obtiene el token de ID del IdP externo una vez que el usuario se autentica.
  2. Luego solicita el intercambio del token de ID y lo establece como token de sujeto.
  3. Se ejecuta la Action del perfil de Custom Token Exchange correspondiente. Valida el token de ID y obtiene de él el id del usuario y otros atributos del perfil. Luego aplica la política de autorización requerida y, por último, establece el usuario.
  4. Auth0 responde con un token de acceso de Auth0, un token de ID y un token de actualización.
  5. El código JavaScript que se ejecuta en la SPA ahora puede usar las API del cliente con tokens de Auth0 sin que el usuario tenga que volver a autenticarse.
El siguiente código muestra cómo implementar esto en la Action de Custom Token Exchange. En este caso:
  • Usamos el id de usuario del IdP externo para establecer el usuario en la conexión correspondiente.
  • Queremos crear el usuario si todavía no existe.
  • No queremos reemplazar el perfil del usuario si se obtiene un conjunto más completo de atributos mediante inicio de sesión federado, en caso de que el usuario ya exista.
  • No queremos verificar el correo electrónico cuando se crean usuarios.
Consulte los ejemplos de código para ver un ejemplo más detallado de cómo validar de forma segura .

​
Caso de uso: Obtener tokens de Auth0 para otra audiencia

GearUp quiere mejorar cómo autoriza las llamadas entre sus microservicios internos para atender solicitudes de API. Quiere una política centralizada que controle los recursos que cada servicio puede consumir. Esto también puede resolverse mediante Token Exchange. Cuando la solicitud de API llega por primera vez al servicio A, este intercambia el token de acceso recibido por uno nuevo que le permite consumir el servicio B con una nueva audiencia. Si la política de autorización que rige el intercambio de tokens lo permite, el servicio A recibe el nuevo token y ya puede consumir el servicio B. El ID del usuario se mantiene sin cambios en el nuevo token, por lo que se conserva el contexto de usuario adecuado durante todo el proceso.
La aplicación GearUp obtuvo inicialmente un token de acceso para consumir la API A en nombre de un usuario:
  1. La aplicación envía la solicitud con el token de acceso inicial a la API A.
  2. El backend de la API A valida el token de acceso y solicita el intercambio estableciéndolo como token de sujeto para un nuevo token de acceso destinado a consumir la API B como audiencia.
  3. Se ejecuta la Action del perfil de Custom Token Exchange correspondiente. Valida el token de acceso y obtiene del token el ID del usuario de Auth0. Luego aplica la política de autorización requerida y, por último, establece el usuario.
  4. Auth0 responde con un token de acceso de Auth0 para consumir la audiencia de la API B.
  5. El backend de la API A llama a la API B con el nuevo token de acceso, que sigue asociado al mismo usuario.
El siguiente código muestra cómo implementar esto en la Action de Custom Token Exchange. En este caso:
  • Usamos el ID del usuario de Auth0 para establecer el usuario, por lo que no es necesario hacerlo en el scope de ninguna conexión.
  • No queremos crear ni actualizar el usuario.
Consulta Validate JWTs signed with asymmetric keys para ver ejemplos de código más completos sobre este caso de uso.
Consulte los ejemplos de código para ver un ejemplo más detallado de cómo validar JWT de forma segura.

​
Caso de uso: Realizar MFA durante Custom Token Exchange

A partir del Caso de uso: Reutilizar un proveedor de autenticación externo, GearUp ahora quiere verificar la presencia del usuario cuando se usa un token del proveedor de autenticación externo. Esto es necesario para mitigar riesgos de seguridad, como el robo de tokens o situaciones en las que el autenticador externo no admite MFA. GearUp tiene dos opciones para lograrlo: implementar una política de MFA para toda la organización o activar MFA mediante programación con una Action de Post Login. En el siguiente ejemplo se usa una Action de Post Login para activar la autenticación MFA durante la transacción de Custom Token Exchange. Para obtener más información sobre el uso del grant de MFA en API integradas, consulte la documentación sobre el uso de ROPG con MFA, ya que Custom Token Exchange sigue el mismo modelo. Primero, defina la Action con api.multifactor.enable() para activar una solicitud de MFA. Esta función se describe en la documentación de la API de Post Login.
Esto genera un error mfa_required que devuelve un token de MFA:
Con el mfa_token devuelto, la aplicación puede llamar a la API de MFA para plantear un desafío y verificar un factor: Primero, devuelve una lista de autenticadores:
En segundo lugar, use el id del autenticador para iniciar un desafío:
El desafío genera la siguiente respuesta:
Use mfa_token y oob_code (si se devuelven) para completar el proceso de verificación mediante el endpoint de token y recibir los tokens:
Consulte los ejemplos de código para ver un ejemplo más detallado de cómo validar un Token de actualización opaco con un IdP heredado.

​
Caso de uso: Agente de soporte que actúa en nombre de un usuario final

Los agentes de soporte de GearUp necesitan acceder a los datos del usuario final y realizar acciones mediante las API de backend de GearUp en nombre de ese usuario. La herramienta de soporte autentica al agente y luego usa Custom Token Exchange para obtener un token de acceso que represente al usuario final, con el agente registrado como actor.
En este caso, el token de ID de Auth0 del agente se envía como actor_token en la solicitud, y un JWT firmado que identifica al usuario final se envía como subject_token. Cuando actor_token_type se establece en urn:ietf:params:oauth:token-type:id_token, Auth0 valida automáticamente el token (firma, vencimiento y emisor) y completa event.transaction.actor_token_user con el perfil del agente. Esto elimina la necesidad de usar código de validación personalizado para el token del actor.
No es obligatorio usar un token de ID de Auth0 como actor_token. Cuando actor_token_type es un valor personalizado, la Action debe validar el token del actor mediante código personalizado, de forma similar a como se validan los tokens de sujeto. El llenado automático de event.transaction.actor_token_user solo se aplica a los tokens de ID de Auth0.
  1. La herramienta de soporte autentica al agente con Auth0 y obtiene el token de ID del agente.
  2. La herramienta de soporte llama al endpoint /oauth/token de Auth0 mediante una solicitud de Custom Token Exchange, que incluye un JWT firmado con el identificador del usuario final como subject_token y el token de ID del agente como actor_token.
  3. La Action de Custom Token Exchange valida el token de sujeto, verifica que el actor tenga permiso para actuar en nombre del usuario final y llama a api.authentication.setActor().
  4. Auth0 emite tokens con el claim act que identifica al agente de soporte.
  5. El agente de soporte llama a la API en nombre del usuario final. Las API pueden inspeccionar el claim act para aplicar políticas de autorización específicas del acceso delegado, como restringir operaciones de escritura o registrar la actividad con fines de auditoría.
La Action de Custom Token Exchange decide qué incluir en el objeto del actor, incluidas las propiedades personalizadas y los niveles de anidación. Consulta la documentación del objeto de API de Custom Token Exchange para conocer las restricciones.
El token de acceso emitido incluirá el claim act:

​
Consideraciones importantes para la autorización delegada

Al implementar la autorización delegada con Custom Token Exchange, siga estas pautas:
  • Implemente la lógica de autorización dentro de su Action de Custom Token Exchange para verificar que el actor esté autorizado a acceder a la cuenta de usuario específica. Por ejemplo, puede implementar decisiones de autorización para permitir que solo determinados actores realicen acceso delegado, o comprobar que el usuario de destino tenga un ticket de soporte activo para protegerse frente al acceso arbitrario a cuentas de usuario.
  • Valide los alcances solicitados para garantizar que solo se emita el conjunto mínimo de alcances necesarios para la autorización delegada. También puede asegurarse de que determinadas operaciones sensibles nunca puedan realizarse en el contexto de la autorización delegada.
  • Asegúrese de que sus API utilicen el contexto de delegación en el claim act del token de acceso. Debe mantener registros de auditoría en sus API de las acciones realizadas por un actor delegado y asegurarse de poder auditar con claridad qué actor realizó operaciones en nombre del usuario.
  • Con fines de auditoría, puede usar los detalles del actor en los registros del inquilino de Auth0. Las transacciones correctas de Custom Token Exchange (eventos de registro secte) incluyen la propiedad actor con sub y cualquier información actor anidada.
Auth0 no notifica al usuario final cuando se emite un token de autorización delegada en su nombre. Si su caso de uso requiere notificar al usuario o contar con su consentimiento explícito antes de que se produzca el acceso delegado, considere usar Client Initiated Backchannel Authentication (CIBA) para enviar una solicitud de consentimiento al dispositivo del usuario final antes de realizar el intercambio de tokens. Para necesidades de notificación más simples, puede implementar la lógica de notificación dentro de su Action de Custom Token Exchange, una Action de Post-Login o en sus servicios posteriores.

​
Ejemplos de código

Los siguientes ejemplos de código muestran las prácticas recomendadas para escenarios habituales de validación segura y eficiente de los subject tokens entrantes. Use algoritmos y claves asimétricos siempre que sea posible, ya que no necesita compartir ningún secreto con Auth0. Esto también simplifica la rotación de claves, por ejemplo, al exponer un endpoint con una URI de JWKS para publicar las claves públicas aplicables.
Es su responsabilidad garantizar que los subject tokens estén protegidos con un algoritmo sólido y con claves o secretos con suficiente entropía.

​
Validación de JWT firmados con claves asimétricas

Tenga en cuenta las siguientes recomendaciones:
  • Use los métodos api.cache () de Actions para evitar tener que obtener las claves de firma en cada transacción.
  • Siga las prácticas recomendadas de RFC8725
  • Use algoritmos RS*, PS*, ES* o Ed25519
  • No use ni acepte el algoritmo none
  • Use RSA con una longitud mínima de 2048 bits.

​
Validar JWT firmados con claves simétricas

Tenga en cuenta las siguientes recomendaciones:
  • Utilice Actions Secrets para almacenar de forma segura sus secretos simétricos.
  • Siga las prácticas recomendadas de RFC8725.
  • Utilice algoritmos seguros como HS256, junto con secretos aleatorios de alta entropía (por ejemplo, de al menos 256 bits de longitud).

​
Validar un token opaco con un servicio externo

Utilice Secretos de Actions para almacenar de forma segura el de su IdP externo.