Transformaciones de claims y tareas de claims

Cada método de autenticación y registro de aplicación de FoxIDs maneja claims y admite transformaciones de claims y tareas de claims. Esto significa que se pueden ejecutar varios conjuntos de transformaciones y tareas de claims para cada autenticación de usuario. Primero, las transformaciones y tareas de claims se ejecutan en el método de autenticación y luego en el registro de aplicación.

Se pueden ejecutar subconjuntos adicionales de transformaciones y tareas de claims si se crea un usuario o un usuario externo.

En los métodos de autenticación con una lista Forward claims, añada a esa lista los claims ordinarios creados por las transformaciones de primer nivel para que estén disponibles en pasos posteriores, o incluya * (predeterminado). Los métodos Login transmiten estos claims sin esa lista.

Los prefijos reservados _local:, _internal:, _session: y _impersonate: determinan cómo se usan los claims durante la autenticación. Consulte Claims locales, internos y de sesión para conocer sus diferentes tiempos de vida.

Para emitir un claim ordinario desde un registro de aplicación, añádalo o añada * a Issue claims. En OpenID Connect también puede añadirlo a los Voluntary claims de un scope y solicitar ese scope desde la aplicación. Los claims reservados no se emiten, ni siquiera con *.

Consulte los ejemplos de transformaciones de claims.

Habilite Log claim trace en la configuración de logs para ver las claims antes y después de la transformación en los logs.

Las transformaciones de claims se pueden configurar en un método de autenticación Login.

Y las tareas de claims.

Del mismo modo, las transformaciones y tareas de claims se pueden configurar como de primer nivel y segundo nivel en un método de autenticación OpenID Connect.

Las claims se representan por defecto como claims JWT. Si el método de autenticación es SAML 2.0, las claims de primer nivel se representan como claims SAML 2.0. Si el registro de aplicación es SAML 2.0, las claims se representan como claims SAML 2.0.

Una transformación de claims y una tarea de claims realizarán una de hasta siete acciones diferentes según el tipo de transformación o tarea.

Acciones de transformaciones y tareas de claims:

• Add claim - añadir una nueva claim
• Add claim, if not match - realizar la acción de añadir si la condición no coincide
• Replace claim - añadir una nueva claim y eliminar las claims existentes si hay una o más
• Replace claim, if not match - realizar la acción de reemplazar si la condición no coincide
• Remove claim - eliminar las claims si hay una o más
• If match - realizar la acción si la condición coincide
• If not match - realizar la acción si la condición no coincide

Las transformaciones y tareas de claims se ejecutan en orden, por lo que las acciones se ejecutan en orden. Esto significa que es posible crear una variable local agregando una claim y más adelante en la secuencia tomar decisiones basadas en la claim. Una claim es local en el conjunto de transformaciones y tareas de claims si comienza con _local:.

Cuando las transformaciones y tareas de claims se ejecutan en un flujo de login, FoxIDs añade automáticamente claims locales de la solicitud de login antes de ejecutar las transformaciones. Estas claims _local: están destinadas a decisiones dentro de la secuencia de transformaciones/tareas y se eliminan de la salida.

Claims locales generales añadidos desde la solicitud de inicio de sesión:

• _local:login_action - la acción de la solicitud de login, almacenada como camelCase
• _local:user_id - el ID de usuario de la solicitud de login (solo si se proporciona)
• _local:max_age - el max age de la solicitud de login (solo si se establece y es mayor que 0)
• _local:login_hint - la pista de la solicitud de login (solo si se proporciona)
• _local:acr - los valores ACR de la solicitud de login como una lista separada por espacios (solo si se proporciona)
• _local:params:{name} - un parámetro de solicitud de aplicación permitido, con el nombre del parámetro en minúsculas y un claim por valor (solo si se proporciona)

Cuando un método de autenticación se utiliza como elemento de Advanced MFA, sus propias transformaciones de claims reciben los siguientes claims locales del usuario ya autenticado por el método de autenticación Login:

Claim	Valor
_local:mfa:user_id	El ID de usuario técnico estable del usuario en FoxIDs.
_local:mfa:user_identifier	El identificador utilizado para la autenticación Login. Si no se proporcionó ninguno, FoxIDs utiliza el correo electrónico, el número de teléfono o el nombre de usuario.
_local:mfa:username	El nombre de usuario registrado del usuario.
_local:mfa:email	El correo electrónico registrado del usuario, o el valor de su claim email si el correo registrado está vacío.
_local:mfa:phone	El número de teléfono registrado del usuario, o el valor de su claim phone_number si el número registrado está vacío.

Solo se añaden claims con un valor no vacío. Estas transformaciones procesan los claims devueltos por el proveedor de identidad externo y pueden añadir el valor AMR requerido por el elemento MFA. El flujo MFA de Login utiliza la respuesta transformada para validar ese valor AMR. Los demás claims devueltos por el método de autenticación no se combinan con los del método de autenticación Login ni se pasan a sus transformaciones de claims generales.

Con la acción Add claim, if not match es posible añadir una claim (variable local) si otra claim o un valor de claim no existe.

Tipos de claim transform que admiten todas las acciones:

• Match claim - comprueba si existe el tipo de claim seleccionado. Para acciones add y replace, la claim saliente se escribe con el nuevo valor cuando la claim existe. Las acciones if not match se ejecutan cuando falta la claim. Una acción remove elimina la claim saliente seleccionada cuando la claim existe.
• Match claim and value - comprueba si existe el tipo de claim seleccionado con el valor configurado. Para acciones add y replace, la claim saliente se escribe con el nuevo valor cuando coinciden el tipo y el valor. Las acciones if not match se ejecutan cuando la claim existe pero el valor no coincide. Una acción remove elimina la claim saliente seleccionada cuando coinciden el tipo y el valor.
• Regex match - comprueba si existe el tipo de claim seleccionado y si el valor coincide con la expresión regular configurada. Para acciones add y replace, la claim saliente se escribe con el nuevo valor cuando la expresión regular coincide. Las acciones if not match se ejecutan cuando la claim existe pero el valor no coincide con la expresión regular. Una acción remove elimina la claim saliente seleccionada cuando la expresión regular coincide.

Tipos de claim transform que admiten acciones Add claim, Replace claim y Add claim, if new claim does not exist:

• Map - copia el valor de la claim seleccionada a la claim saliente. Con Add claim, if new claim does not exist, el valor solo se escribe si la claim saliente aún no existe.
• Regex map - extrae el grupo de expresión regular con nombre map del valor de la claim seleccionada y escribe el valor extraído en la claim saliente. Con Add claim, if new claim does not exist, el valor solo se escribe si la claim saliente aún no existe.

Tipos de claim transform que admiten acciones Add claim y Replace claim:

• Constant - escribe siempre el valor constante configurado en la claim saliente.
• Concatenate - crea la claim saliente a partir de valores de las claims seleccionadas. La cadena de formato usa marcadores como {0}, {1} y {2} para los valores seleccionados en orden.
• External claims API - envía las claims seleccionadas a una API externa. Las claims devueltas por la API se añaden o reemplazan claims salientes.
• Impersonation - prepara un target local seleccionado como usuario efectivo después de las transformaciones del método de autenticación. Consulte Suplantación de identidad.
• DK XML privilege to JSON - convierte una claim XML DK privilege en claims JSON, una claim por cada elemento XML PrivilegeGroup.

Tipos de claim task que admiten acciones Add claim y Replace claim:

• Query internal user - usa el valor de la claim de lookup para encontrar exactamente un usuario interno y después añade o reemplaza claims seleccionadas de ese usuario interno en el conjunto actual de claims.
• Query external user - usa el valor de la claim de lookup para encontrar exactamente un usuario externo y después añade o reemplaza claims seleccionadas de ese usuario externo en el conjunto actual de claims.
• Save claim on internal user - usa el valor de la claim de lookup para encontrar exactamente un usuario interno y después añade o reemplaza la claim seleccionada en ese usuario interno con valores de la claim de valor de actualización seleccionada en el conjunto actual de claims.
• Save claim on external user - usa el valor de la claim de lookup para encontrar exactamente un usuario externo y después añade o reemplaza la claim seleccionada en ese usuario externo con valores de la claim de valor de actualización seleccionada en el conjunto actual de claims.

Las cuatro tareas de usuario enumeradas anteriormente consideran que un usuario no está disponible cuando la cuenta está deshabilitada directamente o mediante una pertenencia activa a una estructura de acceso. El usuario se excluye antes de que FoxIDs determine si la búsqueda encontró exactamente un usuario, por lo que las tareas query no añaden claims y las tareas save no realizan cambios.

Cuando cualquiera de las dos tareas query user se ejecuta en un método de autenticación y todavía no hay una cuenta local asociada a la respuesta de autenticación actual, el primer usuario encontrado de forma inequívoca en el orden de ejecución de las claim transforms se convierte en la cuenta local de la respuesta. Una tarea Query internal user con Target solo proporciona claims locales y mantiene esta asociación de cuenta sin cambios. Si la autenticación continúa mediante pasos de Extended UI, FoxIDs conserva la instantánea de acceso de la cuenta seleccionada en la secuencia del servidor y la utiliza cuando se completa la respuesta. Después, FoxIDs aplica la asociación a las sesiones activas y a los refresh token grants. Un usuario interno o un usuario externo conectado que se autentique directamente mediante el método de autenticación tiene prioridad, y una asociación existente nunca se sustituye por una query posterior.

Si una claim transformation inicia interactivamente otro método de autenticación, la autenticación redirigida se ejecuta como un nuevo login flow. Una asociación de cuenta local seleccionada por una query anterior no se conserva durante esa redirección.

Las tareas query user de un registro de aplicación pueden añadir claims, pero no crean ni modifican la asociación de cuenta local del login.

Las tareas query user hacen que el ID estable del usuario seleccionado esté disponible como una claim local:

Claim task	Claim local	Valor
Query internal user	_local:internal_user_id	El ID de usuario técnico y estable de FoxIDs del usuario interno seleccionado.
Query external user	_local:external_user_id	El ID técnico y estable de usuario externo de FoxIDs del usuario externo seleccionado.

Seleccione explícitamente la claim local en las outgoing claims de la tarea, o seleccione *, para que esté disponible para las transformaciones posteriores de la misma secuencia. Las claims locales se eliminan del resultado final, salvo que su valor se asigne a una claim no local.

Por ejemplo, después de buscar un usuario interno por correo electrónico o nombre de usuario, una tarea Match claim and return error puede comprobar _local:internal_user_id y detener el flow si no se encontró un usuario interno único. Una transformación Match claim puede, en cambio, añadir otra claim solo cuando la búsqueda sea correcta. El ID de usuario estable permanece local a la secuencia de transformaciones, pero sigue proporcionando una base fiable para las decisiones posteriores.

Para Query internal user y Save claim on internal user, la claim de lookup se lee del conjunto actual de claims. El valor Lookup claim on internal user define cómo se compara el usuario interno:

• sub coincide con el user ID del usuario interno.
• email, phone_number y preferred_username buscan primero en los identifiers del usuario interno con coincidencia sin distinguir mayúsculas y minúsculas cuando la capitalización es relevante. Si no se encuentra ningún usuario por identifier, la búsqueda continúa en las claims almacenadas del usuario.
• Después, la búsqueda continúa en las claims almacenadas del usuario interno para el mismo tipo de claim y un valor coincidente sin distinguir mayúsculas y minúsculas. Esto se aplica a todos los tipos de claim de lookup si antes no se encontró ningún usuario.

Si la búsqueda encuentra exactamente un usuario interno, Query internal user añade o reemplaza claims seleccionadas de ese usuario en el conjunto actual de claims. Save claim on internal user añade o reemplaza la claim seleccionada en ese usuario con valores de la claim de valor de actualización seleccionada. Si no se encuentra ningún usuario, o si se encuentra más de un usuario mediante claims, no se añaden ni guardan claims de usuario interno.

Para Query external user y Save claim on external user, la claim de lookup se lee del conjunto actual de claims y se compara con la fuente de usuarios externos seleccionada. Use link_claim como claim de lookup en el usuario externo para coincidir por el valor de link claim del usuario externo.

Tipos de claim task que admiten acciones If match e If not match:

• Match claim and return error - devuelve un error si el tipo de claim coincide o no coincide.
• Match claim and value and return error - devuelve un error si el tipo y el valor de la claim coinciden o no coinciden.
• Regex match and return error - devuelve un error si el tipo y el valor de la claim coinciden o no coinciden con la expresión regular.
• Match claim and log event - escribe el valor de la claim seleccionada en el log si el tipo de claim coincide.
• Match claim and start authentication - inicia un nuevo flujo de login iniciando un método de autenticación si el tipo de claim coincide o no coincide.
• Match claim and value and start authentication - inicia un nuevo flujo de login iniciando un método de autenticación si el tipo y el valor de la claim coinciden o no coinciden.
• Regex match and start authentication - inicia un nuevo flujo de login iniciando un método de autenticación si el tipo y el valor de la claim coinciden o no coinciden con la expresión regular.

Para las return error tasks, configure el error de protocolo devuelto al cliente o requester. Las configuraciones OpenID Connect y OAuth 2.0 devuelven un error y una descripción opcional. Las configuraciones SAML 2.0 devuelven un código de estado SAML y un mensaje.

Las start authentication claim tasks se pueden usar para step-up cuando el usuario ha iniciado sesión con un factor y se requiere otro factor, o si se requiere información adicional (claims).

Cargar un usuario interno en claims locales

Configure el Target opcional de Query internal user para cargar los claims de otro usuario para comprobaciones o transformaciones, manteniendo la asociación del inicio de sesión con la cuenta local. Introduzca un nombre como target; FoxIDs añade _local: y coloca el nombre delante de cada tipo de claim seleccionado:

Claim seleccionado	Resultado local con Target target
sub	_local:target:sub
email	_local:target:email
role	_local:target:role
_local:internal_user_id	_local:target:_local:internal_user_id
_local:access_node	_local:target:_local:access_node
_local:access_claim	_local:target:_local:access_claim
_local:access_path_claim	_local:target:_local:access_path_claim

El tipo de claim original completo se conserva bajo el nombre del target. Así, los claims auxiliares locales de cuentas y Access Structure se distinguen de los claims ordinarios. La búsqueda incluye claims resueltos a partir de pertenencias activas de Access Structure, respetando el ajuste Forward claims de la estructura, y claims auxiliares locales para comprobar pertenencias.

Seleccione los claims por sus nombres originales en Claims from internal user, o utilice *. El nombre completo del claim local, incluidos el prefijo y el nombre del target, debe respetar el límite de 100 caracteres. Deje Target vacío para añadir o sustituir los claims seleccionados directamente en la colección de claims actual.

Varias consultas y llamadas a Claims API pueden completar el mismo target. Add claim añade los valores devueltos. Replace claim sustituye los valores de los tipos de claim devueltos bajo ese target y conserva los demás claims que ya estén presentes.

Utilice los claims del target en las transformaciones posteriores del mismo conjunto. Por ejemplo, compruebe _local:target:role, o asigne _local:target:sub a _internal:selected_user_id para conservar ese valor en conjuntos de transformaciones posteriores. Los claims locales del target se eliminan al terminar el conjunto.

Claims locales, internos y de sesión

Utilice estos prefijos para elegir la duración de un valor usado por las transformaciones y tareas de claims. Un conjunto de transformaciones es una lista ordenada de transformaciones y tareas: por ejemplo, el primer nivel del método de autenticación, una lista de Extended UI, el segundo nivel o la lista de un registro de aplicación. Pasar a otro conjunto importa incluso si ambos pertenecen al mismo método.

Prefijo	Uso	Dónde está disponible el valor	¿Disponible en un inicio de sesión posterior en una aplicación?
_local:	Valor o decisión temporal dentro de un conjunto	Transformaciones y tareas posteriores del mismo conjunto. Se elimina al terminar el conjunto.	No. FoxIDs puede proporcionar un nuevo contexto local de solicitud o tarea en un conjunto nuevo.
_internal:	Valor necesario para conjuntos posteriores del flujo de autenticación actual	Transformaciones del método, continuaciones como Extended UI y transformaciones de la aplicación. Se elimina antes de que la respuesta de protocolo salga de FoxIDs.	No. Cree o copie de nuevo el valor en el nuevo flujo.
_session:	Valor pequeño conservado para el mismo usuario autenticado	Se restaura antes del primer nivel y está disponible durante las transformaciones intermedias y el segundo nivel. Se guarda tras completar correctamente el segundo nivel y se elimina antes de las transformaciones de la aplicación.	Sí, mediante el mismo método de autenticación mientras la sesión del usuario siga siendo válida.
_impersonate:	Una identidad de destino preparada para la suplantación	Transformaciones del método de autenticación y Extended UI, hasta completar la suplantación después de las transformaciones de segundo nivel.	Prepare de nuevo el destino en cada flujo de inicio de sesión.

Por ejemplo, _local:customer_found puede controlar la siguiente tarea de la lista; _internal:customer_category puede leerse después en una transformación de aplicación; _session:profileId puede conservar un perfil seleccionado para el siguiente inicio de sesión en una aplicación.

Las transformaciones que crean un usuario externo vinculado trabajan con los claims seleccionados para ese paso junto con los claims _session: actuales. Seleccione un claim _internal: como entrada si las transformaciones de creación necesitan su valor. Los claims de sesión permanecen en el flujo de autenticación y no se guardan en la cuenta del usuario externo.

Transformaciones como Constant, Map, Match claim y Match claim and value pueden crear o utilizar estos claims con sus acciones normales. El prefijo controla su duración. Utilice _session: en el método de autenticación: los claims de sesión creados por transformaciones de aplicación no se guardan en la sesión del método.

Copiar un valor a otra duración

Una transformación Map copia un valor al claim de salida seleccionado. El origen y el destino son claims separados y siguen la duración de sus propios prefijos. Si los nombres son distintos, Replace claim sustituye los valores existentes del claim de destino y conserva el claim de origen. Los cambios posteriores en uno no actualizan automáticamente el otro.

Por ejemplo, cuando una tarea Query internal user devuelve _local:internal_user_id, añada en el mismo conjunto una transformación Map de _local:internal_user_id a _internal:selected_user_id. Los conjuntos posteriores pueden leer _internal:selected_user_id después de eliminarse el claim local. Una transformación del método también puede copiar un valor _internal: a un claim _session: para conservarlo en inicios de sesión posteriores.

Transmitir un valor de sesión a las transformaciones de aplicación

Suponga que _session:profileId contiene customer-456 y las transformaciones de aplicación necesitan ese valor. Configure esta transformación en la lista de segundo nivel del método de autenticación, después de las que cambien el perfil seleccionado:

Ajuste	Valor
Tipo de transformación	Map
Acción	Replace claim
Claim de entrada	_session:profileId
Claim de salida	_internal:profileId

El flujo continúa así:

1. Ambos claims contienen customer-456 durante las transformaciones restantes del método.
2. Al terminar el segundo nivel, FoxIDs guarda _session:profileId para inicios de sesión posteriores y lo elimina de la colección actual de claims.
3. _internal:profileId pasa a las transformaciones de aplicación. Puede utilizarse allí para decisiones sin emitirse a la aplicación.
4. Si la aplicación necesita el valor en su token o assertion, añada una transformación Map en la aplicación de _internal:profileId a un claim ordinario como profile_id y configure su emisión.

En el siguiente inicio de sesión en una aplicación, FoxIDs restaura _session:profileId para el mismo usuario autenticado. La transformación del método crea un nuevo _internal:profileId para ese flujo. El mismo procedimiento se aplica cuando FoxIDs convierte claims entre JWT y SAML.

Transmisión, mapeo de protocolo y API externas

Los claims internos y de sesión no necesitan una entrada en Forward claims; los límites generales de longitud siguen aplicándose. Los nombres reservados no cambian con el mapeo de protocolo JWT/SAML, incluido el automático. Utilice una transformación de claim Map para copiar valores entre prefijos; los mapeos de protocolo no pueden crear tipos de claims reservados.

Ninguno de los tres espacios de nombres reservados se emite en tokens o assertions, ni siquiera con * en Issue claims. También se excluyen de las solicitudes y respuestas de la API de claims externa. Mapee el valor seleccionado a un claim ordinario antes de enviarlo a una API y, si hace falta, un claim ordinario de la respuesta a uno reservado después.

Los prefijos distinguen mayúsculas y minúsculas y están reservados por FoxIDs. Los claims reservados recibidos de un protocolo o una API de integración se eliminan antes de las transformaciones. Los almacenados en un usuario existente se ignoran, y las tareas no pueden guardarlos en usuarios internos o externos. Si una tarea inicia otro método de autenticación, la colección actual de claims no se transfiere al nuevo flujo de inicio de sesión.

Claims de sesión

Utilice claims _session: para conservar pequeñas cantidades de estado del mismo usuario autenticado entre inicios de sesión del navegador en distintas aplicaciones. Las sesiones deben estar habilitadas en el método de autenticación; están habilitadas de forma predeterminada. FoxIDs admite claims de sesión en Login, External Login, OpenID Connect, SAML 2.0, WS-Federation y Environment Link.

FoxIDs hace disponibles los claims de sesión guardados antes de las transformaciones de primer nivel. Permanecen disponibles durante las transformaciones intermedias, Extended UI y el segundo nivel. Al completarse correctamente estas transformaciones, FoxIDs guarda los claims de sesión resultantes. Eliminar un claim de sesión en una transformación también elimina su valor guardado. Para utilizar un valor de sesión guardado en las transformaciones de aplicación, cópielo a un claim interno antes de que termine el método de autenticación.

Los claims de sesión pertenecen al usuario autenticado originalmente, con independencia de los cambios en sub mediante transformaciones. Solo se restauran con un subject autenticado coincidente y una sesión válida y activa del mismo método. Un método que acepte varios issuers debe recibir subjects únicos entre todos ellos. Las tareas que inician autenticación no transfieren claims de sesión a otro método; los flujos que solo procesan tokens no leen ni guardan claims de sesión del navegador.

Login y External Login pueden reutilizar su sesión del navegador. Los métodos basados en protocolos externos siguen autenticando ante el proveedor de identidad externo en cada inicio de sesión en una aplicación; FoxIDs restaura los claims de sesión después de verificar la identidad devuelta. Siguen la duración de la sesión del método y dejan de estar disponibles tras cerrar la sesión o revocarla.

Cuando un nuevo inicio de sesión verifica al mismo usuario mientras su sesión anterior sigue siendo válida, FoxIDs conserva los valores guardados de esa sesión durante las transformaciones de claims y Extended UI hasta que las transformaciones de segundo nivel se completan correctamente y los sustituyen. Un nuevo inicio de sesión completado reinicia la duración absoluta de la sesión del método de autenticación; la reutilización de una sesión Login o External Login sigue sus duraciones deslizante y absoluta configuradas.

Login y External Login conservan los claims originales en la sesión del navegador antes de ejecutar las transformaciones de claims. Tras completarse correctamente las transformaciones de segundo nivel, FoxIDs actualiza los claims de sesión del usuario autenticado, también después de Extended UI. Esta actualización conserva los claims ordinarios y el vencimiento de la sesión. Cada método de autenticación mantiene un usuario actual y un conjunto de claims de sesión en el navegador. Un nuevo inicio de sesión sigue el comportamiento normal de las sesiones del método de autenticación; el navegador utiliza la última cookie de sesión recibida.

Los claims de sesión tienen estos límites de almacenamiento:

Límite	Valor
Nombre del claim	100 caracteres, incluido _session:, con un nombre de claim JWT válido y un nombre tras el prefijo que no esté vacío ni contenga solo espacios en blanco
Valor individual	1.000 caracteres
Número de claims	10 pares nombre/valor; cada valor de un claim multivalor cuenta por separado
Longitud total de los valores	2.000 caracteres

Se omiten los claims con nombres inválidos o valores vacíos o compuestos solo por espacios en blanco. Los valores más largos se truncan. Los claims se procesan en orden; el guardado se detiene si el siguiente claim válido superaría el límite de cantidad o longitud total. La validación general de claims durante la autenticación sigue aplicándose.

Por ejemplo, una transformación del método de autenticación puede conservar una referencia a un destino de suplantación autorizado en _session:impersonation_target_id. Los siguientes inicios de sesión mediante ese método pueden usarla para cargar el usuario de destino y comprobar de nuevo los permisos. Consulte Suplantación de identidad para ver el ejemplo completo.

Claims externas - API

Puede llamar a su propia API desde FoxIDs con una transformación de claim. La API se llama con claims y las claims devueltas por la API se pueden añadir con una acción de añadir o reemplazar. La API solo se llama si existe al menos una claim seleccionada. Puede usar * para seleccionar y enviar todas las claims a su API.

Los claims reservados _local:, _internal:, _session: y _impersonate: se excluyen de las solicitudes y respuestas API. Para intercambiar un valor reservado seleccionado, mapéelo a un claim ordinario antes de la llamada, o mapee después un claim ordinario de la respuesta a uno reservado.

Las reclamaciones protegidas, como sid y auth_time, se descartan de las respuestas de la API. Las demás reclamaciones de la respuesta se procesan según la acción configurada.

Escenarios de uso:

• Llamar a su API desde un método de autenticación cada vez que un usuario se autentica en FoxIDs o con un proveedor de identidad externo. Luego puede encontrar al usuario en su base de datos y devolver un ID de usuario y quizá un ID de cliente o cualquier cosa relevante. Por ejemplo, también puede crear el usuario en su base de datos.
• Llamar a su API desde un registro de aplicación con el ID de usuario (sub) y consultar los roles del usuario en su base de datos. Su API devolvería entonces una lista vacía o una lista de claims de rol o quizá una estructura de permisos más compleja.

Cargar los claims de respuesta de la API en claims locales

Configure el Target opcional de External claims API para utilizar los claims de la respuesta en comprobaciones o transformaciones posteriores. Con Target establecido en target, un claim llamado sub en la respuesta de la API se convierte en _local:target:sub, y role se convierte en _local:target:role. La API devuelve nombres de claims ordinarios; FoxIDs añade el prefijo local después de filtrar y validar la respuesta. El nombre completo del claim local debe respetar el límite de 100 caracteres. Deje Target vacío para añadir o sustituir los claims de la respuesta directamente en la colección de claims actual.

Varias llamadas a la API y consultas de usuarios internos pueden completar el mismo target. Add claim añade los valores devueltos. Replace claim sustituye los tipos de claim devueltos bajo ese target y conserva los demás. Una respuesta vacía deja los claims existentes del target sin cambios.

Los claims locales del target están disponibles dentro del conjunto de transformaciones actual. Asigne un valor como _local:target:sub a _internal:selected_user_id para utilizarlo en conjuntos posteriores.

Implementar la API

Debe implementar una API sencilla que FoxIDs llamará cuando se ejecute la transformación de claim. Consulte el código de ejemplo.

La API tiene una URL base y la funcionalidad se divide en carpetas. Actualmente solo se admite la carpeta claims (funcionalidad) para solicitar una lista de claims.

Si la URL base de la API es https://somewhere.org/myclaimsstore la URL de la carpeta claims será https://somewhere.org/myclaimsstore/claims.

FoxIDs Cloud llama a su API desde la dirección IP 57.128.60.142. La dirección IP saliente puede cambiar y se pueden añadir más con el tiempo.

Solicitud

Protegida con HTTP Basic auth: usuario external_claims, contraseña = secreto configurado.

La API se llama con HTTP POST y un cuerpo JSON.

Este es un cuerpo JSON de solicitud con dos claims de entrada:

{
  "claims": [
    { "type": "sub", "value": "1b1ac05e-5937-4939-a49c-0e84a89662df" },
    { "type": "email", "value": "some@test.org" }
  ]
}

Respuesta - Éxito

En caso de éxito la API debe devolver el código HTTP 200 y una lista de claims (la lista puede estar vacía).

FoxIDs ignora los claims cuyo type o value falta, es null, está vacío o solo contiene espacios en blanco. Con el registro de trazas de mensajes activado, la traza de la respuesta incluye los claims recibidos antes de filtrarlos. Los mensajes de traza largos se truncan.

Por ejemplo, el sub del usuario (ID de usuario / nombre de usuario), el ID de cliente y los roles:

{
    "claims": [
        { "type": "sub", "value": "somewhere/external-some@test.org" },
        { "type": "customer_id", "value": "1234abcd" },
        { "type": "role", "value": "admin_access" },
        { "type": "role", "value": "read_access" },
        { "type": "role", "value": "write_access" }
    ]
}

Respuesta - Error

La API debe devolver el código HTTP 401 (Unauthorized) y un error (requerido) si se rechaza el Basic auth. Opcionalmente agregue una descripción del error en ErrorMessage.

{
    "error": "invalid_api_id_secret",
    "ErrorMessage": "Invalid API ID or secret"
}

Si ocurren otros errores, la API debe devolver el código HTTP 500 u otro código de error apropiado. Se recomienda añadir un mensaje de error técnico ErrorMessage para diagnóstico (solo se registra; nunca se muestra al usuario final).

Los mensajes de error devueltos por la API en ErrorMessage NO se muestran al usuario; solo se registran.

Ejemplo de API

El ejemplo ExternalClaimsApiSample muestra cómo implementar la API en ASP.NET Core.

Puede usar esta colección de Postman para llamar y probar su API con Postman.

Configurar

Configure FoxIDs para llamar a su API desde una transformación de claim en FoxIDs Control Client.

1. Navegue a la sección Claim Transform
2. Haga clic en Add claim transform
3. Haga clic en External claims API
4. Seleccione Add claim o Replace claim
5. Agregue las claims seleccionadas p. ej. sub en Select claims
6. Agregue la URL base de la API sin la carpeta claims en API URL
7. Agregue el API secret
8. Configure opcionalmente Target para cargar los claims de la respuesta en claims locales
9. Haga clic en Update

Ejemplos de transformaciones de claims

Dividir la claim name en las dos claims given_name y family_name

La transformación dividirá el valor de la claim name en el primer espacio y añadirá respectivamente las claims given_name y family_name, si aún no existen. Si hay más de un espacio en el valor de la claim name, no se añadirán nuevas claims given_name y family_name porque ya existen.

Use dos transformaciones de claim Regex map.

• Encuentre el valor de la claim family_name con la regex ^\S+\s(?<map>\S+)$
• Encuentre el valor de la claim given_name con la regex ^(?<map>\S+)\s\S+$

Eliminar el nombre del método de autenticación añadido por defecto de sub

El nombre del método de autenticación se añade por defecto al valor de la claim sub como un prefijo separado por una barra vertical, p. ej., some-auth-method|my-external-user-id.

Puede usar un reemplazo de claim en la claim sub para eliminar el valor de prefijo añadido por defecto.

La transformación dividirá el valor de la claim sub y reemplazará la claim con una nueva sub que solo contiene el ID original.

Use una transformación de claim Regex map y seleccione la acción Replace claim.

Encuentre el ID sin el nombre del método de autenticación añadido por defecto con la regex ^([^|]+)\|(?<map>.+)$

Puede hacer lo mismo en un método de autenticación SAML 2.0 usando la claim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier (que contiene el valor NameID de la respuesta de autenticación SAML 2.0) en lugar de la claim sub.

Comparar email con _local:mfa:email y agregar amr

El ejemplo se ejecuta en un método de autenticación utilizado como elemento MFA. Compara el claim email devuelto por el método con _local:mfa:email del usuario Login. Si los dos valores de correo electrónico son iguales y coinciden con una expresión regular, se añade el claim amr con el nombre del método de autenticación como valor (ese nombre se configura como valor de amr).

El flujo MFA de Login utiliza el claim amr añadido para validar que el elemento MFA se completó correctamente. El claim email devuelto y los demás claims del método de autenticación no se combinan con los del método de autenticación Login.

Use una transformación de claim Concatenate seguida de una transformación de claim Regex match.

• Concatenate: Nueva claim _local:compare_emails, acción Replace claim, concatenate claims email y _local:mfa:email, concatenate format string {0}|{1}.
• Regex match: Nueva claim amr, acción Replace claim, select claim _local:compare_emails, regex value match ^([^|]+)\|\1$, nuevo valor establecido en el nombre del método de autenticación (por ejemplo 9fk5z3vg).

Suplantación de identidad

Use la transformación Impersonation en un método de autenticación para emitir claims de otro usuario, conservando al usuario autenticado original como actor. Las sesiones deben estar habilitadas en el método de autenticación; lo están de forma predeterminada.

Cargue el destino con Query internal user, una API de claims externa o ambas, estableciendo Target en un nombre como target. Compruebe el permiso del usuario autenticado y los claims necesarios del destino antes de seleccionarlo con una transformación Impersonation. Target es obligatorio y su valor predeterminado en Control Client es target. Un parámetro de solicitud de la aplicación selecciona un destino; no otorga permiso para suplantar identidades.

Conserve una referencia al destino seleccionado en un claim de sesión para repetir la búsqueda en posteriores inicios de sesión de las aplicaciones. La referencia puede ser un ID de usuario interno o un ID de perfil externo y no tiene que coincidir con el sub emitido del destino. El ejemplo de usuario interno de abajo usa impersonation_target_id tanto para el parámetro de solicitud como para el claim de sesión; son nombres de ejemplo que puede adaptar a su flujo.

El destino seleccionado debe contener exactamente un sub distinto y no vacío. De lo contrario, la transformación continúa sin seleccionar ese destino. La búsqueda de un usuario interno deshabilitado no devuelve claims. Use una tarea de error condicional si su política exige rechazar el inicio de sesión cuando no se puede seleccionar un destino.

La transformación prepara claims _impersonate: para su finalización después de completar correctamente las transformaciones de segundo nivel. Por ejemplo, _local:target:sub se convierte en _impersonate:sub y _local:target:_local:internal_user_id en _impersonate:_local:internal_user_id. También puede prepararlos con transformaciones ordinarias. Permanecen disponibles entre los conjuntos de transformaciones del método de autenticación y durante Extended UI.

Al finalizar, FoxIDs sustituye los claims de identidad ordinarios del usuario por los del destino seleccionado, conserva el contexto de autenticación verificado y añade un claim act cuyo sub identifica al usuario autenticado original. El subject del actor es el sub de FoxIDs del usuario antes de que la suplantación sustituya sus claims. Las transformaciones de la aplicación reciben esta identidad efectiva. Los claims auxiliares reservados no se emiten a las aplicaciones.

Cuentas de destino internas

Cuando existe _impersonate:_local:internal_user_id, FoxIDs comprueba que el usuario interno existe y está habilitado, incluida la política de Access Structure aplicable, y asocia la cuenta de destino con la sesión y los grants junto a la cuenta original. Si el usuario interno de destino no es válido, no existe o está deshabilitado, no se realiza ninguna suplantación.

Deshabilitar o eliminar cualquiera de las cuentas asociadas revoca la sesión activa y los grants de tokens de actualización. La revocación de acceso de Access Structure y las comprobaciones de pertenencias temporales también se aplican al destino asociado. Para un destino proporcionado únicamente por una API sin asociación a una cuenta interna, la API y las transformaciones configuradas determinan su disponibilidad en cada inicio de sesión.

Ejemplo: suplantar a un usuario interno

Este ejemplo permite a un empleado con el valor allow_impersonation en el claim role seleccionar un usuario interno y continuar suplantándolo en posteriores inicios de sesión de las aplicaciones. Un inicio de sesión sin destino seleccionado continúa como el usuario original.

El diagrama sigue las ocho transformaciones configuradas a continuación. La referencia de destino se conserva entre inicios de sesión; los claims del destino y los permisos del empleado se comprueban de nuevo en cada inicio de sesión.

Configure impersonation_target_id en Allowed request parameters de cada registro de aplicación que lo envíe. La aplicación proporciona un ID de usuario interno como valor del parámetro, que FoxIDs expone como _local:params:impersonation_target_id. Consulte Parámetros de solicitud de aplicaciones. Asegúrese de que los claims del empleado incluyen role=allow_impersonation.

Añada las siguientes ocho entradas, en orden, a Second-level claim transforms del método de autenticación Login.

1. Map: recuperar la referencia de destino guardada. Use Replace claim, establezca Select claim en _session:impersonation_target_id y New claim en _local:impersonation_target_id.

2. Map: aplicar un destino de la aplicación. Use Replace claim, establezca Select claim en _local:params:impersonation_target_id y New claim en _local:impersonation_target_id. Un parámetro proporcionado sustituye la selección guardada. Si falta, se conserva el valor del paso 1.

3. Match claim and value: comprobar el rol del empleado. Use Replace claim, establezca Select claim en role, Match value en allow_impersonation, New claim en _local:impersonation_check_passed y New value en true.

4. Match claim: permitir el inicio de sesión sin destino. Use Replace claim, if not match, establezca Select claim en _local:impersonation_target_id, New claim en _local:impersonation_check_passed y New value en true.

El claim de comprobación local indica que el inicio de sesión puede continuar: el empleado tiene el rol necesario o no se ha seleccionado ningún destino. La comprobación del rol se realiza antes de que el destino sustituya los claims del usuario original.

5. Match claim and return error: rechazar una selección no autorizada. Use If not match y seleccione _local:impersonation_check_passed. Establezca Error en access_denied y Error message en You are not allowed to impersonate another user.

6. Query internal user: cargar el destino. Use Replace claim, establezca Lookup claim en _local:impersonation_target_id, Lookup claim on internal user en sub, Claims from internal user en * y Target en target. La búsqueda compara el ID de usuario interno y carga sus claims, incluidos los claims de Access Structure reenviados y los auxiliares locales, bajo _local:target:. Por ejemplo, proporciona _local:target:sub y _local:target:_local:internal_user_id.

7. Impersonation: seleccionar el destino cargado. Use Replace claim y establezca Target en target.

8. Map: conservar el destino para posteriores inicios de sesión. Use Replace claim, establezca Select claim en _local:target:_local:internal_user_id y New claim en _session:impersonation_target_id. Esto guarda el ID estable del usuario cargado como referencia para el siguiente inicio de sesión.

Si su política limita a qué usuarios se puede suplantar, añada comprobaciones del destino entre los pasos 6 y 7. Por ejemplo, compruebe _local:target:role o el claim auxiliar de Access Structure _local:target:_local:access_node.

Si la búsqueda no proporciona ningún destino, estos ocho pasos finalizan sin suplantación y conservan cualquier referencia de destino guardada anteriormente. Añada una tarea de error condicional después de la búsqueda si un destino no disponible debe causar el rechazo del inicio de sesión, o elimine explícitamente el claim de sesión para borrar la selección guardada.

Continuar y cambiar la suplantación

Cada inicio de sesión de una aplicación vuelve a ejecutar las transformaciones del método de autenticación. En el ejemplo anterior, leen la referencia de _session:impersonation_target_id cuando falta _local:params:impersonation_target_id, cargan los claims actuales del destino y repiten las comprobaciones de permisos antes de seleccionar la suplantación. La referencia guardada permanece vinculada al usuario autenticado original y al mismo método de autenticación.

Para seleccionar otro destino, proporcione una nueva referencia en el parámetro de solicitud y sustituya el claim de sesión guardado cuando el nuevo destino supere las comprobaciones. Para finalizar la suplantación, borre la referencia guardada y complete las transformaciones sin un destino de suplantación válido.

Una finalización correcta con el mismo destino conserva su sid. Seleccionar otro destino, iniciar una suplantación o finalizar sin un destino válido crea un nuevo sid y revoca la sesión activa anterior y los grants de tokens de actualización.

UserInfo y el canje de grants rechazan una sesión activa revocada. Las aplicaciones y API que validan tokens localmente deben seguir aplicando sus propias reglas de sesión y duración de tokens. El cierre de sesión único SAML utiliza los valores registrados en la emisión de cada aplicación.

Las sesiones activas y los grants de tokens de actualización muestran el subject suplantado y el actor original en Control Client y Control API. Los eventos de auditoría de inicio de sesión incluyen al actor. Eventos de auditoría de suplantación independientes registran el inicio, el cambio y la finalización, incluidos los ID de sesión anteriores y actuales.

Documentación relacionada

• Reclamaciones
• Estructura de acceso
• Inicio de sesión y detección del reino de origen
• Método de autenticación OpenID Connect
• Método de autenticación SAML 2.0