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

Dans les méthodes d’authentification disposant d’une liste Forward claims, ajoutez les claims ordinaires créés par les transformations de premier niveau à cette liste pour les rendre disponibles aux étapes suivantes, ou incluez * (par défaut). Les méthodes Login transmettent ces claims sans cette liste.

Les préfixes réservés _local:, _internal:, _session: et _impersonate: déterminent l’utilisation des claims pendant l’authentification. Consultez Claims locaux, internes et de session pour leurs différentes durées de vie.

Pour émettre un claim ordinaire depuis un enregistrement d’application, ajoutez-le ou ajoutez * à Issue claims. Avec OpenID Connect, vous pouvez aussi l’ajouter aux Voluntary claims d’un scope et demander ce scope depuis l’application. Les claims réservés ne sont jamais émis, même avec *.

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.

Et les tâches de revendications.

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.

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.

Claims locaux généraux ajoutés à partir de la requête de connexion :

• _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)
• _local:params:{name} - un paramètre de requête d’application autorisé, avec le nom du paramètre en minuscules et un claim par valeur (uniquement s’il est fourni)

Lorsqu’une méthode d’authentification est utilisée comme élément Advanced MFA, ses propres transformations de claims reçoivent les claims locaux suivants pour l’utilisateur déjà authentifié par la méthode d’authentification Login :

Claim	Valeur
_local:mfa:user_id	L’ID utilisateur technique stable de l’utilisateur dans FoxIDs.
_local:mfa:user_identifier	L’identifiant utilisé pour l’authentification Login. Si aucun identifiant n’a été fourni, FoxIDs utilise l’adresse e-mail, le numéro de téléphone ou le nom d’utilisateur.
_local:mfa:username	Le nom d’utilisateur enregistré de l’utilisateur.
_local:mfa:email	L’adresse e-mail enregistrée de l’utilisateur, ou la valeur de son claim email si l’adresse enregistrée est vide.
_local:mfa:phone	Le numéro de téléphone enregistré de l’utilisateur, ou la valeur de son claim phone_number si le numéro enregistré est vide.

Seuls les claims dont la valeur n’est pas vide sont ajoutés. Ces transformations traitent les claims renvoyés par le fournisseur d’identité externe et peuvent ajouter la valeur AMR requise par l’élément MFA. Le flux MFA de Login utilise la réponse transformée pour valider cette valeur AMR. Les autres claims renvoyés par la méthode d’authentification ne sont ni fusionnés avec ceux de la méthode d’authentification Login, ni transmis à ses transformations de claims générales.

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.
• Impersonation - prépare une cible locale sélectionnée comme utilisateur effectif après les transformations de la méthode d’authentification. Voir Impersonation.
• 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.

Les quatre tâches utilisateur répertoriées ci-dessus considèrent un utilisateur comme indisponible lorsque le compte est désactivé directement ou par une adhésion active à une structure d’accès. L’utilisateur est exclu avant que FoxIDs détermine si la recherche a trouvé exactement un utilisateur, de sorte que les tâches query n’ajoutent aucun claim et que les tâches save n’apportent aucune modification.

Lorsque l’une des deux tâches query user s’exécute sur une méthode d’authentification et qu’aucun compte local n’est déjà associé à la réponse d’authentification actuelle, le premier utilisateur mis en correspondance de manière unique dans l’ordre d’exécution des claim transforms devient le compte local de la réponse. Une tâche Query internal user avec un Target fournit uniquement des claims locaux et laisse cette association de compte inchangée. Si l’authentification se poursuit via des étapes Extended UI, FoxIDs conserve l’instantané d’accès du compte sélectionné dans la séquence côté serveur et l’utilise lorsque la réponse est finalisée. FoxIDs applique ensuite l’association aux sessions actives et aux refresh token grants. Un utilisateur interne ou un utilisateur externe lié, authentifié directement par la méthode d’authentification, est prioritaire, et une association existante n’est jamais remplacée par une query ultérieure.

Si une claim transformation démarre interactivement une autre méthode d’authentification, l’authentification redirigée s’exécute comme un nouveau login flow. Une association de compte local sélectionnée par une query antérieure n’est pas conservée lors de cette redirection.

Les tâches query user sur un enregistrement d’application peuvent ajouter des claims, mais elles ne créent ni ne modifient l’association de compte local du login.

Les tâches query user rendent l’ID stable de l’utilisateur sélectionné disponible en tant que claim local :

Claim task	Claim local	Valeur
Query internal user	_local:internal_user_id	L’ID utilisateur FoxIDs technique et stable de l’utilisateur interne sélectionné.
Query external user	_local:external_user_id	L’ID utilisateur externe FoxIDs technique et stable de l’utilisateur externe sélectionné.

Sélectionnez explicitement le claim local dans les outgoing claims de la tâche, ou sélectionnez *, pour le rendre disponible aux transformations suivantes de la même séquence. Les claims locaux sont supprimés du résultat final, sauf si leur valeur est mappée vers un claim non local.

Par exemple, après avoir recherché un utilisateur interne par e-mail ou nom d’utilisateur, une tâche Match claim and return error peut vérifier _local:internal_user_id et arrêter le flow si aucun utilisateur interne unique n’a été trouvé. Une transformation Match claim peut à la place ajouter un autre claim uniquement lorsque la recherche réussit. L’ID utilisateur stable reste local à la séquence de transformations tout en fournissant une base fiable pour les décisions suivantes.

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.

Charger un utilisateur interne dans des claims locaux

Définissez le Target facultatif de Query internal user pour charger les claims d’un autre utilisateur à des fins de vérification ou de transformation, tout en conservant l’association de la connexion au compte local. Saisissez un nom tel que target ; FoxIDs ajoute _local: et place ce nom devant chaque type de claim sélectionné :

Claim sélectionné	Résultat local avec 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

Le type de claim d’origine complet est conservé sous le nom de la cible. Les claims auxiliaires locaux des comptes et d’Access Structure restent ainsi distincts des claims ordinaires. La recherche inclut les claims issus des appartenances Access Structure actives, en respectant le paramètre Forward claims de la structure, ainsi que les claims auxiliaires locaux de vérification des appartenances.

Sélectionnez les claims par leur nom d’origine dans Claims from internal user, ou utilisez *. Le nom complet du claim local, y compris le préfixe et le nom du target, doit respecter la limite de 100 caractères. Laissez Target vide pour ajouter ou remplacer les claims sélectionnés directement dans la collection de claims actuelle.

Plusieurs recherches et appels Claims API peuvent alimenter le même target. Add claim ajoute les valeurs renvoyées. Replace claim remplace les valeurs des types de claims renvoyés sous ce target et conserve les autres claims déjà présents.

Utilisez les claims du target dans les transformations suivantes du même ensemble. Par exemple, vérifiez _local:target:role, ou mappez _local:target:sub vers _internal:selected_user_id pour conserver cette valeur dans les ensembles de transformations suivants. Les claims locaux du target sont supprimés à la fin de l’ensemble.

Claims locaux, internes et de session

Ces préfixes permettent de choisir la durée de vie d’une valeur utilisée par les transformations et tâches de claims. Un ensemble de transformations est une liste ordonnée de transformations et de tâches : par exemple, le premier niveau d’une méthode d’authentification, une liste Extended UI, le second niveau ou la liste d’un enregistrement d’application. Passer à un autre ensemble est significatif même si les deux appartiennent à la même méthode.

Préfixe	Utilisation	Disponibilité de la valeur	Disponible lors d’une connexion ultérieure à une application ?
_local:	Valeur ou décision temporaire dans un ensemble	Transformations et tâches suivantes du même ensemble. Supprimé à la fin de l’ensemble.	Non. FoxIDs peut fournir un nouveau contexte local de requête ou de tâche dans un nouvel ensemble.
_internal:	Valeur nécessaire aux ensembles suivants du flux d’authentification actuel	Transformations de la méthode, étapes de continuation comme Extended UI et transformations de l’application. Supprimé avant que la réponse de protocole quitte FoxIDs.	Non. Recréez ou recopiez la valeur dans le nouveau flux.
_session:	Petite valeur conservée pour le même utilisateur authentifié	Restauré avant le premier niveau ; disponible pendant les transformations intermédiaires et le second niveau. Enregistré après un second niveau réussi, puis supprimé avant les transformations de l’application.	Oui, via la même méthode d’authentification tant que la session de l’utilisateur reste valide.
_impersonate:	Une identité cible préparée pour l’impersonation	Transformations de la méthode d’authentification et Extended UI, jusqu’à la finalisation de l’impersonation après les transformations de second niveau.	Préparez à nouveau la cible à chaque flux de connexion.

Par exemple, _local:customer_found peut piloter la tâche suivante de la liste ; _internal:customer_category peut être lu plus tard par une transformation d’application ; _session:profileId peut conserver un profil sélectionné pour la prochaine connexion à une application.

Les transformations de création d’un utilisateur externe lié utilisent les claims sélectionnés pour cette étape ainsi que les claims _session: actuels. Sélectionnez un claim _internal: en entrée si ces transformations ont besoin de sa valeur. Les claims de session restent dans le flux d’authentification et ne sont pas enregistrés sur le compte utilisateur externe.

Les transformations telles que Constant, Map, Match claim et Match claim and value peuvent créer ou utiliser ces claims avec leurs actions habituelles. Le préfixe détermine la durée de vie. Utilisez _session: sur la méthode d’authentification : les claims de session créés par les transformations d’application ne sont pas enregistrés dans la session de la méthode.

Copier une valeur vers une autre durée de vie

Une transformation Map copie une valeur dans le claim de sortie sélectionné. La source et la destination sont des claims distincts, chacun suivant la durée de vie de son préfixe. Lorsque les noms diffèrent, Replace claim remplace les valeurs existantes du claim de destination et conserve le claim source. Modifier ensuite un claim ne met pas automatiquement l’autre à jour.

Par exemple, lorsqu’une tâche Query internal user renvoie _local:internal_user_id, ajoutez dans le même ensemble une transformation Map de _local:internal_user_id vers _internal:selected_user_id. Les ensembles suivants peuvent lire _internal:selected_user_id après la suppression du claim local. Une transformation de la méthode d’authentification peut de même copier une valeur _internal: vers un claim _session: pour la conserver lors de connexions ultérieures.

Transmettre une valeur de session aux transformations d’application

Supposons que _session:profileId contienne customer-456 et que les transformations d’application aient besoin de cette valeur. Configurez cette transformation dans la liste de second niveau de la méthode d’authentification, après celles qui modifient le profil sélectionné :

Paramètre	Valeur
Type de transformation	Map
Action	Replace claim
Claim d’entrée	_session:profileId
Claim de sortie	_internal:profileId

La suite du flux est la suivante :

1. Les deux claims contiennent customer-456 pour les transformations restantes de la méthode d’authentification.
2. À la fin du second niveau, FoxIDs enregistre _session:profileId pour les connexions ultérieures et le retire de la collection de claims actuelle.
3. _internal:profileId est transmis aux transformations d’application. Elles peuvent l’utiliser pour leurs décisions sans l’émettre à l’application.
4. Si l’application a besoin de la valeur dans son token ou son assertion, ajoutez une transformation Map sur l’application de _internal:profileId vers un claim ordinaire comme profile_id, puis configurez son émission.

Lors de la prochaine connexion à une application, FoxIDs restaure _session:profileId pour le même utilisateur authentifié. La transformation de la méthode crée un nouveau _internal:profileId pour ce flux. La même approche s’applique lorsque FoxIDs convertit les claims entre JWT et SAML.

Transmission, mapping de protocole et API externes

Les claims internes et de session ne nécessitent aucune entrée dans Forward claims ; les limites générales de longueur s’appliquent toujours. Les noms réservés ne changent pas lors du mapping de protocole JWT/SAML, y compris automatique. Utilisez une transformation de claim Map pour copier une valeur entre préfixes ; les mappings de protocole ne peuvent pas créer de types de claims réservés.

Aucun des trois espaces de noms réservés n’est émis dans les tokens ou assertions, même avec * dans Issue claims. Ils sont également exclus des requêtes et réponses de l’API de claims externe. Mappez une valeur sélectionnée vers un claim ordinaire avant de l’envoyer à une API, puis, si nécessaire, un claim ordinaire de la réponse vers un claim réservé.

Les préfixes sont sensibles à la casse et réservés par FoxIDs. Les claims réservés reçus d’un protocole ou d’une API d’intégration sont supprimés avant les transformations. Ceux stockés sur un utilisateur existant sont ignorés, et les tâches ne peuvent pas les enregistrer sur un utilisateur interne ou externe. Si une tâche démarre une autre méthode d’authentification, la collection de claims actuelle n’est pas transférée au nouveau flux de connexion.

Claims de session

Utilisez les claims _session: pour conserver de petites quantités d’état pour le même utilisateur authentifié entre les connexions par navigateur à différentes applications. Les sessions doivent être activées sur la méthode d’authentification ; elles le sont par défaut. FoxIDs prend en charge les claims de session pour Login, External Login, OpenID Connect, SAML 2.0, WS-Federation et Environment Link.

FoxIDs rend les claims de session enregistrés disponibles avant les transformations de premier niveau. Ils restent disponibles pendant les transformations intermédiaires, Extended UI et le second niveau. Lorsque ces transformations se terminent avec succès, FoxIDs enregistre les claims de session résultants. Supprimer un claim de session dans une transformation supprime aussi sa valeur enregistrée. Pour utiliser une valeur de session enregistrée dans les transformations d’application, copiez-la vers un claim interne avant la fin de la méthode d’authentification.

Les claims de session appartiennent à l’utilisateur initialement authentifié, indépendamment des modifications de sub par les transformations. Ils ne sont restaurés qu’avec un subject authentifié correspondant et une session valide et active sur la même méthode. Une méthode acceptant plusieurs issuers doit recevoir des subjects uniques entre tous ces issuers. Une tâche de démarrage d’authentification ne transmet pas les claims de session à une autre méthode ; les flux traitant uniquement des tokens ne lisent ni n’enregistrent les claims de session du navigateur.

Login et External Login peuvent réutiliser leur session de navigateur. Les méthodes basées sur des protocoles externes authentifient toujours auprès du fournisseur d’identité externe à chaque connexion à une application ; FoxIDs restaure les claims de session après vérification de l’identité renvoyée. Ils suivent la durée de vie de la session de la méthode et ne sont plus disponibles après déconnexion ou révocation de la session.

Lorsqu’une nouvelle connexion vérifie le même utilisateur alors que sa session précédente est encore valide, FoxIDs conserve les valeurs enregistrées de cette session pendant les transformations de claims et Extended UI, jusqu’à ce que les transformations de second niveau se terminent avec succès et les remplacent. Une nouvelle connexion menée à terme redémarre la durée de vie absolue de la session de la méthode d’authentification ; la réutilisation d’une session Login ou External Login suit ses durées de vie glissante et absolue configurées.

Login et External Login conservent les claims d’origine dans la session du navigateur avant d’exécuter les transformations de claims. Après la réussite des transformations de second niveau, FoxIDs met à jour les claims de session de l’utilisateur authentifié, y compris après Extended UI. Cette mise à jour préserve les claims ordinaires et l’expiration de la session. Chaque méthode d’authentification conserve un seul utilisateur courant et un seul ensemble de claims de session dans le navigateur. Une nouvelle connexion suit le fonctionnement normal des sessions de la méthode d’authentification ; le navigateur utilise le dernier cookie de session reçu.

Les claims de session ont les limites de stockage suivantes :

Limite	Valeur
Nom du claim	100 caractères, y compris _session:, avec un nom de claim JWT valide et un nom après le préfixe qui n’est ni vide ni composé uniquement d’espaces
Valeur individuelle	1 000 caractères
Nombre de claims	10 paires nom/valeur ; chaque valeur d’un claim à valeurs multiples compte séparément
Longueur totale des valeurs	2 000 caractères

Les claims dont le nom est invalide ou la valeur est vide ou uniquement composée d’espaces sont omis. Les valeurs plus longues sont tronquées. Les claims sont traités dans l’ordre ; l’enregistrement s’arrête lorsque le prochain claim valide dépasserait le nombre autorisé ou la longueur totale. La validation générale des claims pendant l’authentification s’applique toujours.

Par exemple, une transformation de méthode d’authentification peut conserver une référence à une cible d’impersonation autorisée dans _session:impersonation_target_id. Les connexions ultérieures aux applications via cette méthode peuvent utiliser cette référence pour charger la cible et vérifier à nouveau les autorisations. Consultez Impersonation pour l’exemple complet.

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.

Les claims réservés _local:, _internal:, _session: et _impersonate: sont exclus des requêtes et réponses API. Pour échanger une valeur réservée sélectionnée, mappez-la vers un claim ordinaire avant l’appel, ou mappez ensuite un claim ordinaire de la réponse vers un claim réservé.

Les revendications protégées, telles que sid et auth_time, sont supprimées des réponses API. Les autres revendications de la réponse sont traitées conformément à l’action configurée.

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.

Charger les claims de réponse de l’API dans des claims locaux

Définissez le Target facultatif de External claims API pour utiliser les claims de la réponse dans des vérifications ou transformations ultérieures. Lorsque Target est défini sur target, un claim nommé sub dans la réponse de l’API devient _local:target:sub, et role devient _local:target:role. L’API renvoie des noms de claims ordinaires ; FoxIDs ajoute le préfixe local après avoir filtré et validé la réponse. Le nom complet du claim local doit respecter la limite de 100 caractères. Laissez Target vide pour ajouter ou remplacer les claims de la réponse directement dans la collection de claims actuelle.

Plusieurs appels API et recherches d’utilisateurs internes peuvent alimenter le même target. Add claim ajoute les valeurs renvoyées. Replace claim remplace les types de claims renvoyés sous ce target et conserve les autres. Une réponse vide laisse les claims existants du target inchangés.

Les claims locaux du target sont disponibles dans l’ensemble de transformations actuel. Mappez une valeur telle que _local:target:sub vers _internal:selected_user_id pour l’utiliser dans les ensembles suivants.

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

FoxIDs ignore les claims dont le champ type ou value est absent, vaut null, est vide ou ne contient que des caractères d'espacement. Lorsque la journalisation des traces de messages est activée, la trace de la réponse inclut les claims reçus avant leur filtrage. Les longs messages de trace sont tronqués.

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.

1. Accédez à la section Claim Transform
2. Cliquez sur Add claim transform
3. Cliquez sur External claims API
4. Sélectionnez Add claim ou Replace claim
5. Ajoutez les revendications sélectionnées par ex. sub dans Select claims
6. Ajoutez l’URL de base de l’API sans le dossier claims dans API URL
7. Ajoutez le API secret
8. Définissez éventuellement Target pour charger les claims de la réponse dans des claims locaux
9. 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.

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

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

Cet exemple s’exécute dans une méthode d’authentification utilisée comme élément MFA. Il compare le claim email renvoyé par cette méthode avec _local:mfa:email de l’utilisateur Login. Si les deux valeurs e-mail sont identiques et correspondent à une expression régulière, le claim amr est ajouté avec le nom de la méthode d’authentification comme valeur (ce nom est configuré comme valeur amr).

Le flux MFA de Login utilise le claim amr ajouté pour valider que l’élément MFA a été exécuté avec succès. Le claim email renvoyé et les autres claims de la méthode d’authentification ne sont pas fusionnés avec ceux de la méthode d’authentification Login.

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

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

Impersonation

Utilisez la transformation Impersonation sur une méthode d’authentification pour émettre des claims pour un autre utilisateur tout en conservant l’utilisateur authentifié d’origine comme acteur. Les sessions doivent être activées sur la méthode d’authentification ; elles le sont par défaut.

Chargez la cible avec Query internal user, une API de claims externe ou les deux, en définissant Target sur un nom tel que target. Vérifiez l’autorisation de l’utilisateur authentifié et les claims requis de la cible avant de la sélectionner avec une transformation Impersonation. Target est obligatoire et vaut target par défaut dans le Control Client. Un paramètre de requête de l’application sélectionne une cible ; il n’accorde pas l’autorisation d’impersonation.

Conservez une référence à la cible sélectionnée dans un claim de session pour répéter la recherche lors des connexions ultérieures aux applications. La référence peut être un identifiant d’utilisateur interne ou de profil externe et ne doit pas nécessairement correspondre au sub émis pour la cible. L’exemple d’utilisateur interne ci-dessous utilise impersonation_target_id pour le paramètre de requête et le claim de session ; ces noms sont des exemples à adapter à votre flux.

La cible sélectionnée doit contenir exactement un sub distinct et non vide. Sinon, la transformation continue sans sélectionner cette cible. La recherche d’un utilisateur interne désactivé ne fournit aucun claim. Utilisez une tâche d’erreur conditionnelle si votre politique exige de refuser la connexion lorsqu’aucune cible ne peut être sélectionnée.

La transformation prépare des claims _impersonate: pour leur traitement final après la réussite des transformations de second niveau. Par exemple, _local:target:sub devient _impersonate:sub et _local:target:_local:internal_user_id devient _impersonate:_local:internal_user_id. Vous pouvez aussi préparer ces claims avec des transformations ordinaires. Ils restent disponibles entre les ensembles de transformations de la méthode d’authentification et dans Extended UI.

Lors de la finalisation, FoxIDs remplace les claims d’identité ordinaires de l’utilisateur par ceux de la cible, conserve le contexte d’authentification vérifié et ajoute un claim act dont le sub identifie l’utilisateur authentifié d’origine. Le subject de cet acteur est le sub FoxIDs de l’utilisateur avant le remplacement de ses claims par l’impersonation. Les transformations de l’application reçoivent cette identité effective. Les claims auxiliaires réservés ne sont pas émis aux applications.

Comptes cibles internes

Lorsque _impersonate:_local:internal_user_id est présent, FoxIDs vérifie que l’utilisateur interne existe et est activé, y compris la politique Access Structure applicable, et associe le compte cible à la session et aux grants en plus du compte d’origine. Si l’utilisateur cible interne est invalide, inexistant ou désactivé, aucune impersonation n’est effectuée.

La désactivation ou la suppression de l’un des comptes associés révoque la session active et les grants de jetons de rafraîchissement. La révocation de l’accès Access Structure et les vérifications des appartenances limitées dans le temps s’appliquent aussi à la cible associée. Pour une cible fournie uniquement par une API sans association de compte interne, l’API et les transformations configurées déterminent sa disponibilité à chaque connexion.

Exemple : impersoner un utilisateur interne

Cet exemple permet à un employé dont le claim role contient allow_impersonation de sélectionner un utilisateur interne et de continuer à l’impersoner lors de connexions ultérieures aux applications. Une connexion sans cible sélectionnée se poursuit avec l’utilisateur d’origine.

Le diagramme suit les huit transformations configurées ci-dessous. La référence cible est conservée entre les connexions ; les claims de la cible et les droits de l’employé sont vérifiés à nouveau à chaque connexion.

Configurez impersonation_target_id dans Allowed request parameters de chaque enregistrement d’application qui l’envoie. L’application fournit un identifiant d’utilisateur interne comme valeur du paramètre, que FoxIDs rend disponible sous _local:params:impersonation_target_id. Voir Paramètres de requête des applications. Vérifiez que les claims de l’employé contiennent role=allow_impersonation.

Ajoutez les huit entrées suivantes, dans l’ordre, aux Second-level claim transforms de la méthode d’authentification Login.

1. Map : restaurer la référence de cible enregistrée. Utilisez Replace claim, définissez Select claim sur _session:impersonation_target_id et New claim sur _local:impersonation_target_id.

2. Map : appliquer une cible provenant de l’application. Utilisez Replace claim, définissez Select claim sur _local:params:impersonation_target_id et New claim sur _local:impersonation_target_id. Un paramètre fourni remplace la sélection enregistrée. En son absence, la valeur de l’étape 1 est conservée.

3. Match claim and value : vérifier le rôle de l’employé. Utilisez Replace claim, définissez Select claim sur role, Match value sur allow_impersonation, New claim sur _local:impersonation_check_passed et New value sur true.

4. Match claim : autoriser la connexion sans cible. Utilisez Replace claim, if not match, définissez Select claim sur _local:impersonation_target_id, New claim sur _local:impersonation_check_passed et New value sur true.

Le claim de contrôle local signifie que la connexion peut continuer : soit l’employé possède le rôle requis, soit aucune cible n’est sélectionnée. Le rôle est vérifié avant que la cible ne remplace les claims de l’utilisateur d’origine.

5. Match claim and return error : refuser une sélection non autorisée. Utilisez If not match et sélectionnez _local:impersonation_check_passed. Définissez Error sur access_denied et Error message sur You are not allowed to impersonate another user.

6. Query internal user : charger la cible. Utilisez Replace claim, définissez Lookup claim sur _local:impersonation_target_id, Lookup claim on internal user sur sub, Claims from internal user sur * et Target sur target. La recherche correspond à l’identifiant d’utilisateur interne et charge ses claims, y compris les claims Access Structure transmis et les claims auxiliaires locaux, sous _local:target:. Elle fournit par exemple _local:target:sub et _local:target:_local:internal_user_id.

7. Impersonation : sélectionner la cible chargée. Utilisez Replace claim et définissez Target sur target.

8. Map : conserver la cible pour les connexions ultérieures. Utilisez Replace claim, définissez Select claim sur _local:target:_local:internal_user_id et New claim sur _session:impersonation_target_id. L’identifiant stable de l’utilisateur chargé devient ainsi la référence de la prochaine connexion.

Si votre politique limite les utilisateurs pouvant être impersonés, ajoutez les vérifications de cible entre les étapes 6 et 7. Vérifiez par exemple _local:target:role ou le claim auxiliaire Access Structure _local:target:_local:access_node.

Si la recherche ne fournit aucune cible, ces huit étapes se terminent sans impersonation et conservent toute référence de cible déjà enregistrée. Ajoutez une tâche d’erreur conditionnelle après la recherche si une cible indisponible doit entraîner le refus de la connexion, ou supprimez explicitement le claim de session pour effacer la sélection enregistrée.

Poursuivre et modifier l’impersonation

Chaque connexion à une application réexécute les transformations de la méthode d’authentification. Dans l’exemple ci-dessus, elles lisent la référence de cible dans _session:impersonation_target_id lorsque _local:params:impersonation_target_id est absent, chargent les claims actuels de la cible et répètent les vérifications d’autorisation avant de sélectionner l’impersonation. La référence reste liée à l’utilisateur authentifié d’origine et à la même méthode d’authentification.

Pour sélectionner une autre cible, fournissez une nouvelle référence dans le paramètre de requête et remplacez le claim de session enregistré une fois les contrôles réussis. Pour terminer l’impersonation, effacez la référence et terminez les transformations sans cible d’impersonation valide.

Une finalisation réussie avec la même cible conserve son sid. La sélection d’une autre cible, le démarrage d’une impersonation ou une finalisation sans cible valide crée un nouveau sid et révoque la session active précédente et les grants de jetons de rafraîchissement.

UserInfo et l’utilisation des grants refusent une session active révoquée. Les applications et API qui valident les jetons localement doivent toujours appliquer leurs propres règles de session et de durée de vie des jetons. Le single logout SAML utilise les valeurs enregistrées lors de l’émission pour chaque application.

Les sessions actives et les grants de jetons de rafraîchissement affichent le subject impersoné et l’acteur d’origine dans le Control Client et la Control API. Les événements d’audit de connexion incluent l’acteur. Des événements d’audit d’impersonation distincts enregistrent le démarrage, la modification et l’arrêt, avec les identifiants de session précédents et actuels.

Documentation associée

• Demandes d'indemnisation
• Structure d'accès
• Connexion et détection du royaume d'origine
• Méthode d'authentification OpenID Connect
• Méthode d'authentification SAML 2.0