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 transformaciones de claims que admiten todas las acciones:

• Match claim - realizar la acción si el tipo de claim coincide
• Match claim and value - realizar la acción si el tipo y el valor de la claim coinciden
• Regex match - realizar la acción si el tipo de claim coincide y el valor coincide con la expresión regular

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

• Map - realizar la acción si el tipo de claim coincide, luego mapear el valor de la claim a una nueva claim
• Regex map - realizar la acción si el tipo de claim coincide y el valor coincide con el grupo de la expresión regular, luego mapear el valor del grupo a una nueva claim

Tipos de transformaciones de claims que admiten las acciones Add claim y Replace claim:

• Constant - siempre realizar la acción (añadir/reemplazar una claim con un valor constante)
• Concatenate - realizar la acción si uno o más tipos de claims coinciden, luego concatenar los valores de las claims en una nueva claim
• External claims API - llamar a una API externa con las claims seleccionadas para añadir/reemplazar claims con claims externas
• DK XML privilege to JSON - convertir el privilegio DK a JSON.

Tipos de tareas de claims que admiten las acciones Add claim y Replace claim:

• Query internal user - hacer coincidir la claim y encontrar exactamente un usuario interno basado en el valor de la claim. La solicitud fallará si se encuentra más de un usuario. Luego añadir/reemplazar las claims del usuario.
• Query external user - hacer coincidir la claim y encontrar exactamente un usuario externo basado en el valor de la claim. La solicitud fallará si se encuentra más de un usuario. Luego añadir/reemplazar las claims del usuario.

Tipos de tareas de claims que admiten las acciones If match y If not match:

• Match claim and return error - devolver un error si el tipo de claim coincide/no coincide.
• Match claim and value and return error - devolver un error si el tipo y el valor de la claim coinciden/no coinciden.
• Regex match and return error - devolver un error si el tipo y el valor de la claim coinciden/no coinciden con la expresión regular.
• Match claim and start authentication - iniciar un nuevo flujo de login iniciando un método de autenticación si el tipo de claim coincide/no coincide.
• Match claim and value and start authentication - iniciar un nuevo flujo de login iniciando un método de autenticación si el tipo y el valor de la claim coinciden/no coinciden.
• Regex match and start authentication - iniciar un nuevo flujo de login iniciando un método de autenticación si el tipo de claim coincide y el valor coincide/no coincide con la expresión regular.

Las tareas de claims de inicio de autenticación 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).