Interface étendue

Vous pouvez étendre le flux d’interface utilisateur (UI) de connexion avec des pages personnalisées construites à partir d’éléments dynamiques. Les interfaces étendues prennent entièrement en charge la culture et plusieurs langues. Il est possible de créer plusieurs interfaces personnalisées avec différents éléments dynamiques. Chaque page d’interface étendue peut appeler une API de manière optionnelle. Si une API est appelée, les revendications retournées sont ajoutées à la collection de revendications ; sinon, les valeurs d’entrée sont ajoutées en tant que type de revendication de sortie défini sur les éléments dynamiques.

Les éléments dynamiques se composent de champs fixes, d’un champ personnalisable et d’éléments de contenu texte et HTML. Avec cela, vous pouvez facilement demander le nom de l’utilisateur, utiliser un ou plusieurs champs définis par vous et afficher un logo et un lien sur une page d’interface étendue.

Les interfaces étendues peuvent être ajoutées aux méthodes d’authentification suivantes dans l’onglet Extended UI ; login, login externe, OpenID Connect, SAML 2.0 et lien d’environnement.

Sélectionner la page d’interface étendue Vous sélectionnez une page d’interface étendue dans le flux de connexion en ajoutant le type de revendication open_extended_ui avec le nom de la page d’interface étendue dans les transformations de revendications de premier niveau. Dans une méthode d’authentification SAML 2.0, sélectionnez la page d’interface étendue avec la revendication SAML 2.0 correspondante http://schemas.foxids.com/ws/identity/claims/openextendedui dans les transformations de revendications de premier niveau. Ensuite, des pages d’interface étendue peuvent être sélectionnées dans les transformations de revendications d’interface étendue en ajoutant le type de revendication open_extended_ui (revendication JWT uniquement) avec le nom de la page d’interface étendue suivante.

Exemple Cette page d’exemple demande à l’utilisateur de saisir son numéro de sécurité sociale (affiché en deux langues). L’interface étendue d’exemple ajoute la valeur saisie à la collection de revendications en tant que type de revendication social_security_number. Dans un scénario réel, vous appelleriez probablement une API pour valider le numéro de sécurité sociale. En anglais :

En danois :

La page d’exemple est configurée dans une méthode d’authentification dans l’onglet Extended UI avec trois éléments.

L’interface étendue peut être personnalisée avec du CSS dans la méthode d’authentification login appelée Default login, sauf si vous créez une autre méthode de login et l’utilisez à la place. Les dialogues offrent une grande flexibilité de conception.

Traductions

Les textes (et messages d’erreur) utilisés dans les éléments dynamiques sont automatiquement traduits s’ils sont définis comme textes globaux avec traductions. Sinon, un élément de texte est automatiquement créé dans les environnements où vous pouvez ajouter des traductions. Si vous souhaitez prendre en charge plusieurs langues, vous devriez créer les textes en anglais et ajouter des traductions.

Vous trouverez les textes et traductions dans l’onglet Settings puis l’onglet Texts.

Implémenter l’API

Chaque page d’interface étendue peut appeler une API avec le résultat des éléments dynamiques et des revendications sélectionnées. L’API peut ensuite valider l’entrée utilisateur et, en cas de succès, retourner des revendications ou un message d’erreur à l’utilisateur.

Vous devez implémenter une API simple que FoxIDs appelle lorsque l’utilisateur soumet la page. Veuillez consulter le code d’exemple.

L’API possède une URL de base, et la fonctionnalité est divisée en dossiers. Actuellement, seul le dossier validate (fonctionnalité) pour valider les éléments dynamiques et les revendications sélectionnées est pris en charge. D’autres dossiers peuvent être ajoutés plus tard.

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

FoxIDs Cloud appelle votre API depuis l’adresse IP 57.128.60.142. L’adresse IP sortante peut être modifiée et d’autres peuvent être ajoutées avec le temps.

Requête

L’appel API est sécurisé avec l’authentification HTTP Basic, où FoxIDs envoie l’ID external_extended_ui comme nom d’utilisateur et le secret configuré comme mot de passe.

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

Voici un corps de requête JSON avec deux éléments dynamiques et deux revendications :

{
 "elements": [
        {
            "Name": "ne5uqp5z",
            "Type": "Email",
            "ClaimType": "email",
            "Value": "some@test.org"
        },
        {
            "Name": "ktvywqwc",
            "Type": "Custom",
            "ClaimType": "my_claim",
            "Value": "123456"
        }
    ],
 "claims": [
        {
            "type": "sub",
            "value": "1b1ac05e-5937-4939-a49c-0e84a89662df"
        },
        {
            "type": "email",
            "value": "some_other@test.org"
        }
    ]
}

Réponse

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

Par exemple, les valeurs d’entrée valides en tant que revendications :

{
    "claims": [
        {
            "type": "email",
            "value": "some@test.org"
        },
        {
            "type": "my_claim",
            "value": "123456"
        }
    ]
}

Erreur L’API doit retourner le code HTTP 401 (Unauthorized) et une error (requise) si l’authentification Basic est rejetée. Ajoutez éventuellement une description d’erreur dans ErrorMessage.

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

L’API peut retourner le code HTTP 400 (401 et 403 sont également pris en charge) et une error (requise) si l’entrée est rejetée. Ajoutez éventuellement un message d’erreur à l’utilisateur dans UiErrorMessage et une description d’erreur dans ErrorMessage. Le UiErrorMessage est traduit en tant que texte et doit être en anglais si vous souhaitez prendre en charge plusieurs langues.

Une erreur de validation générale :

{
    "error": "invalid",
    "ErrorMessage": "Something is not accepted.",
    "UiErrorMessage": "Please change the thing that is wrong."
}

Une erreur de validation liée à un élément dynamique par le nom de l’élément :

{
    "error": "invalid",
    "elements": [
           {
               "Name": "ktvywqwc",
               "ErrorMessage": "The element is not valid because of something.",
               "UiErrorMessage": "Please change the value to the correct value."
           }
       ]
}

Si d’autres erreurs surviennent, l’API doit retourner le code HTTP 500 ou un autre code d’erreur approprié. Il est recommandé d’ajouter un message d’erreur technique dans ErrorMessage. Le message d’erreur pourra ensuite être trouvé dans les journaux FoxIDs.

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

Exemple d’API

L’exemple ExternalExtendedUiApiSample montre comment implémenter l’API en ASP.NET Core.

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

Configurer

Configurez une page d’interface étendue dans une méthode d’authentification pour appeler votre API dans FoxIDs Control Client.

Allez dans l’onglet Authentication et sélectionnez la méthode d’authentification, puis sélectionnez l’onglet Extended UI. Trouvez la page d’interface étendue et configurez l’API.

• Optionnellement, sélectionnez les revendications qui doivent être envoyées à l’API.
• Ajoutez l’URL de base de l’API sans le dossier validate dans API URL
• Ajoutez le API secret
• Ajoutez un message d’erreur générique qui est affiché à l’utilisateur si l’API retourne une erreur sans UiErrorMessage