Transformations de revendications et tâches de revendications

Chaque méthode d’authentification et enregistrement d’application FoxIDs gère les revendications et prend en charge les transformations de revendications et les tâches de revendications. Cela signifie que plusieurs ensembles de transformations et de tâches de revendications peuvent être exécutés pour chaque authentification utilisateur. D’abord, les transformations et tâches de revendications sont exécutées sur la méthode d’authentification, puis sur l’enregistrement d’application.

Des sous-ensembles supplémentaires de transformations et de tâches de revendications peuvent être exécutés si un utilisateur ou un utilisateur externe est créé.

Claim transform flow diagram

Si vous créez une nouvelle revendication avec une transformation ou une tâche de revendication de premier niveau, la revendication est locale à la méthode d’authentification, sauf pour une méthode d’authentification Login.
Dans une méthode d’authentification, la revendication est transférée si le type de revendication est ajouté à la liste Forward claims, ou si * (par défaut) est inclus dans la liste.

Si vous créez une nouvelle revendication avec une transformation ou une tâche de revendication, la revendication est locale à l’enregistrement d’application.
Dans un enregistrement d’application, vous devez ajouter la revendication ou * à la liste Issue claims. Sinon, pour OpenID Connect, ajoutez la revendication à la liste Voluntary claims d’une portée et demandez la portée depuis votre application.

Veuillez consulter les exemples de transformations de revendications.

Activez Log claim trace dans les paramètres de journalisation pour voir les revendications avant et après transformation dans les journaux.

Les transformations de revendications peuvent être configurées dans une méthode d’authentification Login.

FoxIDs authentication method claim transform

Et les tâches de revendications.

FoxIDs authentication method claim task

De la même manière, les transformations de revendications et les tâches de revendications peuvent être configurées comme premier et second niveau dans une méthode d’authentification OpenID Connect.

FoxIDs application registration claim transform

Les revendications sont par défaut représentées comme des revendications JWT. Si la méthode d’authentification est SAML 2.0, les revendications de premier niveau sont représentées comme des revendications SAML 2.0. Si l’enregistrement d’application est SAML 2.0, les revendications sont représentées comme des revendications SAML 2.0.

Une transformation de revendications et une tâche de revendications exécutent l’une des sept actions possibles selon le type de transformation ou de tâche.

Actions des transformations et tâches de revendications :

Add claim - ajouter une nouvelle revendication
Add claim, if not match - effectuer l’ajout si la condition ne correspond pas
Replace claim - ajouter une nouvelle revendication et supprimer les revendications existantes si une ou plusieurs existent
Replace claim, if not match - effectuer le remplacement si la condition ne correspond pas
Remove claim - supprimer les revendications si une ou plusieurs existent
If match - effectuer l’action si la condition correspond
If not match - effectuer l’action si la condition ne correspond pas

Les transformations et tâches de revendications s’exécutent dans l’ordre, et les actions s’exécutent donc dans l’ordre. Cela signifie qu’il est possible de créer une variable locale en ajoutant une revendication et de prendre ensuite des décisions basées sur cette revendication dans la séquence. Une revendication est locale dans l’ensemble des transformations et tâches de revendications si elle commence par _local:.

Lorsque les transformations et tâches de revendications s’exécutent dans un flux de login, FoxIDs ajoute automatiquement des revendications locales à partir de la requête de login avant d’exécuter les transformations. Ces revendications _local: sont destinées aux décisions dans la séquence de transformations/tâches et sont supprimées de la sortie.

Revendications locales ajoutées dans AddLocalClaims :

_local:login_action - l’action de la requête de login, stockée en camelCase
_local:user_id - l’ID utilisateur de la requête de login (uniquement si fourni)
_local:max_age - l’âge max de la requête de login (uniquement si défini et supérieur à 0)
_local:login_hint - l’indication de la requête de login (uniquement si fournie)
_local:acr - les valeurs ACR de la requête de login sous forme de liste séparée par des espaces (uniquement si fournies)

Avec l’action Add claim, if not match, il est possible d’ajouter une revendication (variable locale) si une autre revendication ou une valeur de revendication n’existe pas.

Types de transformations de revendications qui prennent en charge toutes les actions :

Match claim - effectuer l’action si le type de revendication correspond
Match claim and value - effectuer l’action si le type et la valeur de revendication correspondent
Regex match - effectuer l’action si le type de revendication correspond et si la valeur correspond à l’expression régulière

Types de transformations de revendications qui prennent en charge les actions Add claim, Replace claim et Add claim, if new claim does not exist :

Map - effectuer l’action si le type de revendication correspond, puis mapper la valeur de la revendication vers une nouvelle revendication
Regex map - effectuer l’action si le type de revendication correspond et si la valeur correspond au groupe d’expression régulière, puis mapper la valeur du groupe vers une nouvelle revendication

Types de transformations de revendications qui prennent en charge les actions Add claim et Replace claim :

Constant - toujours effectuer l’action (ajouter/remplacer une revendication avec une valeur constante)
Concatenate - effectuer l’action si un ou plusieurs types de revendications correspondent, puis concaténer les valeurs des revendications dans une nouvelle revendication
External claims API - appeler une API externe avec les revendications sélectionnées pour ajouter/remplacer des revendications avec des revendications externes
DK XML privilege to JSON - convertir le privilège DK en JSON.

Types de tâches de revendications qui prennent en charge les actions Add claim et Replace claim :

Query internal user - faire correspondre la revendication et trouver exactement un utilisateur interne basé sur la valeur de la revendication. La requête échoue si plus d’un utilisateur est trouvé. Puis ajouter/remplacer les revendications de l’utilisateur.
Query external user - faire correspondre la revendication et trouver exactement un utilisateur externe basé sur la valeur de la revendication. La requête échoue si plus d’un utilisateur est trouvé. Puis ajouter/remplacer les revendications de l’utilisateur.

Types de tâches de revendications qui prennent en charge les actions If match et If not match :

Match claim and return error - renvoyer une erreur si le type de revendication correspond/ne correspond pas.
Match claim and value and return error - renvoyer une erreur si le type et la valeur de revendication correspondent/ne correspondent pas.
Regex match and return error - renvoyer une erreur si le type et la valeur de revendication correspondent/ne correspondent pas à l’expression régulière.
Match claim and start authentication - démarrer un nouveau flux de login en initiant une méthode d’authentification si le type de revendication correspond/ne correspond pas.
Match claim and value and start authentication - démarrer un nouveau flux de login en initiant une méthode d’authentification si le type et la valeur de revendication correspondent/ne correspondent pas.
Regex match and start authentication - démarrer un nouveau flux de login en initiant une méthode d’authentification si le type de revendication correspond et si la valeur correspond/ne correspond pas à l’expression régulière.

Les tâches de revendications de démarrage d’authentification peuvent être utilisées pour un step-up lorsque l’utilisateur est connecté avec un facteur et qu’un autre facteur est requis, ou si des informations supplémentaires (revendications) sont nécessaires.

Revendications externes - API

Vous pouvez appeler votre propre API depuis FoxIDs avec une transformation de revendication. L’API est appelée avec des revendications et les revendications retournées par l’API peuvent être ajoutées avec une action d’ajout ou de remplacement. L’API n’est appelée que si au moins une revendication sélectionnée existe. Vous pouvez utiliser * pour sélectionner et envoyer toutes les revendications à votre API.

Cas d’usage :

Appeler votre API depuis une méthode d’authentification à chaque authentification d’un utilisateur, soit dans FoxIDs, soit auprès d’un fournisseur d’identité externe. Vous pouvez ensuite trouver l’utilisateur dans votre base de données et renvoyer un ID utilisateur et peut-être un ID client ou tout ce qui est pertinent. Par exemple, vous pouvez aussi créer l’utilisateur dans votre base de données.
Appeler votre API depuis un enregistrement d’application avec l’ID utilisateur (sub) et interroger les rôles de l’utilisateur dans votre base de données. Votre API renverrait alors soit une liste vide, soit une liste de revendications de rôles, ou éventuellement une structure de droits plus complexe.

Implémenter l’API

Vous devez implémenter une API simple que FoxIDs appelle lorsque la transformation de revendication est exécutée.
Veuillez consulter le code d’exemple.

L’API a une URL de base, et la fonctionnalité est divisée en dossiers. Actuellement, seul le dossier claims (fonctionnalité) pour demander une liste de revendications est pris en charge.

Si l’URL de base de l’API est https://somewhere.org/myclaimsstore, l’URL du dossier claims sera https://somewhere.org/myclaimsstore/claims.

FoxIDs Cloud appelle votre API depuis l’adresse IP 57.128.60.142.
L’adresse IP sortante peut changer et d’autres peuvent être ajoutées au fil du temps.

Requête

Sécurisée par HTTP Basic auth : nom d’utilisateur external_claims, mot de passe = secret configuré.

L’API est appelée avec HTTP POST et un corps JSON.

Voici un corps JSON de requête avec deux revendications d’entrée :

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

Réponse - Succès

En cas de succès, l’API doit renvoyer le code HTTP 200 et une liste de claims (la liste peut être vide).

Par exemple, le sub de l’utilisateur (ID utilisateur / nom d’utilisateur), l’ID client et les rôles :

{
    "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" }
    ]
}

Réponse - Erreur

L’API doit renvoyer le code HTTP 401 (Unauthorized) et un error (obligatoire) si le Basic auth est rejeté. Ajoutez éventuellement une description d’erreur dans ErrorMessage.

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

Si d’autres erreurs se produisent, l’API doit renvoyer le code HTTP 500 ou un autre code d’erreur approprié.
Il est recommandé d’ajouter un message d’erreur technique ErrorMessage pour le diagnostic (il est uniquement journalisé ; jamais affiché à l’utilisateur final).

Les messages d’erreur retournés par l’API dans ErrorMessage ne sont PAS affichés à l’utilisateur ; ils sont seulement journalisés.

Exemple d’API

L’exemple ExternalClaimsApiSample montre comment implémenter l’API dans ASP.NET Core.

Vous pouvez utiliser cette collection Postman pour appeler et tester votre API avec Postman.

Configurer

Configurez FoxIDs pour appeler votre API depuis une transformation de revendication dans FoxIDs Control Client.

Accédez à la section Claim Transform
Cliquez sur Add claim transform
Cliquez sur External claims API
Sélectionnez Add claim ou Replace claim
Ajoutez les revendications sélectionnées par ex. sub dans Select claims
Ajoutez l’URL de base de l’API sans le dossier claims dans API URL
Ajoutez le API secret
Cliquez sur Update

Exemples de transformations de revendications

Diviser la revendication `name` en deux revendications `given_name` et `family_name`

La transformation séparera la valeur de la revendication name au premier espace et ajoutera respectivement les revendications given_name et family_name, si elles n’existent pas déjà.
S’il y a plus d’un espace dans la valeur de la revendication name, les nouvelles revendications given_name et family_name ne seront pas ajoutées car elles existent déjà.

Utilisez deux transformations de revendication Regex map.

Transform name to given_name and family_name

Trouvez la valeur de la revendication family_name avec la regex ^\S+\s(?<map>\S+)$
Trouvez la valeur de la revendication given_name avec la regex ^(?<map>\S+)\s\S+$

Supprimer le nom de la méthode d’authentification ajouté par défaut de `sub`

Le nom de la méthode d’authentification est ajouté par défaut à la valeur de revendication sub comme un préfixe séparé par un pipe, par exemple some-auth-method|my-external-user-id.

Vous pouvez utiliser un remplacement de revendication sur la revendication sub pour supprimer la valeur de préfixe ajoutée par défaut.

La transformation séparera la valeur de la revendication sub et remplacera la revendication par une nouvelle sub contenant uniquement l’ID d’origine.

Utilisez une transformation de revendication Regex map et sélectionnez l’action Replace claim.

Remove default added post authentication method name

Trouvez l’ID sans le nom de méthode d’authentification ajouté par défaut avec la regex ^(nemlogin\|)(?<map>.+)$

Vous pouvez faire la même chose dans une méthode d’authentification SAML 2.0 en utilisant la revendication http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier (qui contient la valeur NameID de la réponse d’authentification SAML 2.0) au lieu de la revendication sub.

Comparer `email` avec `_local:mfa:email` et ajouter `amr`

L’exemple compare email de l’utilisateur actuellement authentifié avec email de l’utilisateur MFA déjà authentifié _local:mfa:email. Si les deux valeurs email sont identiques et correspondent via un regex match, la revendication amr est ajoutée avec le nom de la méthode d’authentification comme valeur (le nom de la méthode d’authentification est configuré comme valeur amr).

Utilisez une transformation de revendication Concatenate suivie d’une transformation de revendication Regex match.

Comparer email et ajouter amr

Concatenate: Nouvelle revendication _local:compare_emails, action Replace claim, concatenate claims email et _local:mfa:email, concatenate format string {0}|{1}.
Regex match: Nouvelle revendication amr, action Replace claim, select claim _local:compare_emails, regex value match ^([^|]+)\|\1$, nouvelle valeur définie sur le nom de la méthode d’authentification (par exemple 9fk5z3vg).