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.

Si crea una nueva claim con una transformación o tarea de claims de primer nivel, la claim es local al método de autenticación, excepto para un método de autenticación Login. En un método de autenticación, la claim se reenvía si el tipo de claim se agrega a la lista Forward claims, o si * (predeterminado) se incluye en la lista.

Si crea una nueva claim con una transformación o tarea de claims, la claim es local al registro de aplicación. En un registro de aplicación, debe agregar la claim o * a la lista Issue claims. Alternativamente, para OpenID Connect, agregue la claim a la lista Voluntary claims de un scope y solicite el scope desde su aplicación.

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 añadidas en AddLocalClaims:

• _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)

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.
• 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.

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).

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.

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.

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).

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. 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 compara el email del usuario autenticado actualmente con el email del usuario MFA ya autenticado _local:mfa:email. Si los dos valores de email son iguales y coinciden mediante un regex match, se agrega la claim amr con el nombre del método de autenticación como valor (el nombre del método de autenticación está configurado como valor amr).

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).