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 claim transform qui prennent en charge toutes les actions :

Match claim - vérifie si le type de claim sélectionné existe. Pour les actions add et replace, le claim sortant est écrit avec la nouvelle valeur lorsque le claim existe. Les actions if not match s'exécutent lorsque le claim est absent. Une action remove supprime le claim sortant sélectionné lorsque le claim existe.
Match claim and value - vérifie si le type de claim sélectionné existe avec la valeur configurée. Pour les actions add et replace, le claim sortant est écrit avec la nouvelle valeur lorsque le type et la valeur correspondent. Les actions if not match s'exécutent lorsque le claim existe mais que la valeur ne correspond pas. Une action remove supprime le claim sortant sélectionné lorsque le type et la valeur correspondent.
Regex match - vérifie si le type de claim sélectionné existe et si la valeur correspond à l'expression régulière configurée. Pour les actions add et replace, le claim sortant est écrit avec la nouvelle valeur lorsque l'expression régulière correspond. Les actions if not match s'exécutent lorsque le claim existe mais que la valeur ne correspond pas à l'expression régulière. Une action remove supprime le claim sortant sélectionné lorsque l'expression régulière correspond.

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

Map - copie la valeur du claim sélectionné vers le claim sortant. Avec Add claim, if new claim does not exist, la valeur est écrite uniquement si le claim sortant n'existe pas déjà.
Regex map - extrait le groupe d'expression régulière nommé map de la valeur du claim sélectionné et écrit la valeur extraite dans le claim sortant. Avec Add claim, if new claim does not exist, la valeur est écrite uniquement si le claim sortant n'existe pas déjà.

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

Constant - écrit toujours la valeur constante configurée dans le claim sortant.
Concatenate - construit le claim sortant à partir des valeurs des claims sélectionnés. La chaîne de format utilise des espaces réservés comme {0}, {1} et {2} pour les valeurs sélectionnées dans l'ordre.
External claims API - envoie les claims sélectionnés à une API externe. Les claims retournés par l'API sont ajoutés aux claims sortants ou les remplacent.
DK XML privilege to JSON - convertit un claim XML DK privilege en claims JSON, un claim pour chaque élément XML PrivilegeGroup.

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

Query internal user - utilise la valeur du claim de lookup pour trouver exactement un utilisateur interne, puis ajoute ou remplace les claims sélectionnés de cet utilisateur dans le claim set actuel.
Query external user - utilise la valeur du claim de lookup pour trouver exactement un utilisateur externe, puis ajoute ou remplace les claims sélectionnés de cet utilisateur dans le claim set actuel.
Save claim on internal user - utilise la valeur du claim de lookup pour trouver exactement un utilisateur interne, puis ajoute ou remplace le claim sélectionné sur cet utilisateur avec les valeurs du claim de valeur de mise à jour sélectionné dans le claim set actuel.
Save claim on external user - utilise la valeur du claim de lookup pour trouver exactement un utilisateur externe, puis ajoute ou remplace le claim sélectionné sur cet utilisateur avec les valeurs du claim de valeur de mise à jour sélectionné dans le claim set actuel.

Pour Query internal user et Save claim on internal user, le claim de lookup est lu depuis le claim set actuel. La valeur Lookup claim on internal user définit comment l'utilisateur interne est mis en correspondance :

sub correspond à l'ID utilisateur de l'utilisateur interne.
email, phone_number et preferred_username recherchent d'abord dans les identifiers de l'utilisateur interne avec une correspondance sans tenir compte de la casse lorsque la casse est pertinente. Si aucun utilisateur n'est trouvé par identifier, la recherche continue dans les claims stockés de l'utilisateur.
La recherche continue ensuite dans les claims stockés de l'utilisateur interne pour le même type de claim et une valeur correspondante sans tenir compte de la casse. Cela s'applique à tous les types de claim de lookup si aucun utilisateur n'a d'abord été trouvé.

Si la recherche trouve exactement un utilisateur interne, Query internal user ajoute ou remplace les claims sélectionnés de cet utilisateur dans le claim set actuel. Save claim on internal user ajoute ou remplace le claim sélectionné sur cet utilisateur avec les valeurs du claim de valeur de mise à jour sélectionné. Si aucun utilisateur n'est trouvé, ou si plusieurs utilisateurs sont trouvés via les claims, aucun claim utilisateur interne n'est ajouté ni enregistré.

Pour Query external user et Save claim on external user, le claim de lookup est lu depuis le claim set actuel et mis en correspondance avec la source d'utilisateurs externes sélectionnée. Utilisez link_claim comme claim de lookup sur l'utilisateur externe pour faire correspondre la valeur de link claim de l'utilisateur externe.

Types de claim task qui prennent en charge les actions If match et If not match :

Match claim and return error - retourne une erreur si le type de claim correspond ou ne correspond pas.
Match claim and value and return error - retourne une erreur si le type et la valeur du claim correspondent ou ne correspondent pas.
Regex match and return error - retourne une erreur si le type et la valeur du claim correspondent ou ne correspondent pas à l'expression régulière.
Match claim and log event - écrit la valeur du claim sélectionné dans le log si le type de claim correspond.
Match claim and start authentication - démarre un nouveau flux de login en initiant une méthode d'authentification si le type de claim correspond ou ne correspond pas.
Match claim and value and start authentication - démarre un nouveau flux de login en initiant une méthode d'authentification si le type et la valeur du claim correspondent ou ne correspondent pas.
Regex match and start authentication - démarre un nouveau flux de login en initiant une méthode d'authentification si le type et la valeur du claim correspondent ou ne correspondent pas à l'expression régulière.

Pour les return error tasks, configurez l'erreur de protocole retournée au client ou au requester. Les configurations OpenID Connect et OAuth 2.0 retournent une error et une error description optionnelle. Les configurations SAML 2.0 retournent un code de statut SAML et un message.

Les start authentication claim tasks peuvent être utilisées pour le step-up lorsque l'utilisateur est connecté avec un facteur et qu'un autre facteur est requis, ou si des informations supplémentaires (claims) 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 ^([^|]+)\|(?<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).