Erweitertes UI

Sie können den Login Benutzeroberflächen (UI) Flow mit benutzerdefinierten Login Seiten erweitern, die aus dynamischen Elementen bestehen. Die erweiterten UIs unterstützen Culture und mehrere Sprachen vollständig. Es ist möglich, mehrere benutzerdefinierte UIs mit unterschiedlichen dynamischen Elementen zu erstellen. Jede erweiterte UI Seite kann optional eine API aufrufen. Wenn eine API aufgerufen wird, werden die zurückgegebenen Claims zur Claims-Sammlung hinzugefügt; andernfalls werden die Eingabewerte als die Output Claim Type hinzugefügt, die in den dynamischen Elementen definiert ist.

Die dynamischen Elemente bestehen aus festen Feldern, einem benutzerdefinierten Feld sowie Text- und HTML-Inhaltselementen. Damit können Sie einfach nach dem Namen des Benutzers fragen, ein oder mehrere selbst definierte Felder verwenden und ein Logo sowie einen Link auf einer erweiterten UI Seite anzeigen.

Erweiterte UIs können in den folgenden Authentifizierungsmethoden im Tab Extended UI hinzugefügt werden: login, external login, OpenID Connect, SAML 2.0 und environment link.

Erweiterte UI Seite auswählen Sie wählen eine erweiterte UI Seite im Login Flow, indem Sie den Claim Type open_extended_ui mit dem Namen der erweiterten UI Seite in den first-level claim transforms hinzufügen. In einer SAML 2.0 Authentifizierungsmethode wählen Sie die erweiterte UI Seite mit dem entsprechenden SAML 2.0 Claim http://schemas.foxids.com/ws/identity/claims/openextendedui in den first-level claim transforms. Anschließend können erweiterte UI Seiten in den erweiterten UI Claim Transforms ausgewählt werden, indem Sie den Claim Type open_extended_ui (nur JWT Claim) mit dem nächsten erweiterten UI Seitennamen hinzufügen.

Beispiel Diese Beispielseite fordert den Benutzer auf, seine Sozialversicherungsnummer einzugeben (in zwei Sprachen dargestellt). Die Beispiel-Erweiterte UI fügt den Eingabewert der Claims-Sammlung als Claim Type social_security_number hinzu. In einem realen Szenario würden Sie wahrscheinlich eine API aufrufen, um die Sozialversicherungsnummer zu validieren. Auf Englisch:

Auf Dänisch:

Die Beispielseite ist in einer Authentifizierungsmethode im Tab Extended UI mit drei Elementen konfiguriert.

Die erweiterte UI kann mit CSS in der Login Authentifizierungsmethode Default login angepasst werden, es sei denn, Sie erstellen eine andere Login-Methode und verwenden diese. Es gibt viel Flexibilität, wie die Dialoge gestaltet werden können.

Übersetzungen

Die Texte (und Fehlermeldungen) in dynamischen Elementen werden automatisch übersetzt, wenn sie als globale Texte mit Übersetzungen definiert sind. Andernfalls wird automatisch ein Textelement in den Umgebungen erstellt, in denen Sie Übersetzungen hinzufügen können. Wenn Sie mehrere Sprachen unterstützen möchten, sollten Sie die Texte auf Englisch erstellen und Übersetzungen hinzufügen.

Sie finden die Texte und Übersetzungen im Tab Settings und dann im Tab Texts.

API implementieren

Jede erweiterte UI Seite kann eine API aufrufen mit dem Ergebnis aus den dynamischen Elementen und ausgewählten Claims. Die API kann dann die Benutzereingabe validieren und bei Erfolg Claims oder eine Fehlermeldung an den Benutzer zurückgeben.

Sie müssen eine einfache API implementieren, die FoxIDs aufruft, wenn der Benutzer die Seite absendet. Bitte sehen Sie sich den Sample Code an.

Die API hat eine Base URL, und die Funktionalität ist in Ordner unterteilt. Aktuell wird nur der Ordner validate (Funktionalität) zur Validierung der dynamischen Elemente und ausgewählten Claims unterstützt. Weitere Ordner können später hinzugefügt werden.

Wenn die Base URL der API https://somewhere.org/mystore ist, lautet die URL für den Ordner validate: https://somewhere.org/mystore/validate.

FoxIDs Cloud ruft Ihre API von der IP-Adresse 57.128.60.142 auf. Die ausgehende IP-Adresse kann sich ändern und im Laufe der Zeit können weitere hinzukommen.

Request

Der API-Aufruf wird mit HTTP Basic authentication gesichert, wobei FoxIDs die ID external_extended_ui als Benutzername und das konfigurierte Secret als Passwort sendet.

Die API wird mit HTTP POST und einem JSON Body aufgerufen.

Dies ist ein Request JSON Body mit zwei dynamischen Elementen und zwei Claims:

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

Response

Success Bei Erfolg sollte die API den HTTP Code 200 und eine Liste von claims zurückgeben (die Liste kann leer sein).

Zum Beispiel die gültigen Eingabewerte als Claims:

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

Error Die API muss den HTTP Code 401 (Unauthorized) und einen error (erforderlich) zurückgeben, wenn die Basic Authentication abgelehnt wird. Optional fügen Sie eine Fehlerbeschreibung in ErrorMessage hinzu.

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

Die API kann den HTTP Code 400 (401 und 403 werden ebenfalls unterstützt) und einen error (erforderlich) zurückgeben, wenn die Eingabe abgelehnt wird. Optional fügen Sie eine Fehlermeldung für den Benutzer in UiErrorMessage und eine Fehlerbeschreibung in ErrorMessage hinzu. UiErrorMessage wird als Text übersetzt und sollte auf Englisch sein, wenn Sie mehrere Sprachen unterstützen möchten.

Ein allgemeiner Validierungsfehler:

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

Ein Validierungsfehler, der an ein dynamisches Element über den Elementnamen gebunden ist:

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

Wenn andere Fehler auftreten, sollte die API den HTTP Code 500 oder einen anderen geeigneten Fehlercode zurückgeben. Es wird empfohlen, eine technische Fehlermeldung in ErrorMessage hinzuzufügen. Die Fehlermeldung kann später in den FoxIDs Logs gefunden werden.

Fehlermeldungen, die die API in ErrorMessage zurückgibt, werden dem Benutzer NICHT angezeigt; sie werden nur geloggt.

API Sample

Das Sample ExternalExtendedUiApiSample zeigt, wie die API in ASP.NET Core implementiert wird.

Sie können diese Postman collection verwenden, um Ihre API mit Postman aufzurufen und zu testen.

Configure

Konfigurieren Sie eine erweiterte UI Seite in einer Authentifizierungsmethode, um Ihre API im FoxIDs Control Client aufzurufen.

Navigieren Sie zum Tab Authentication, wählen Sie die Authentifizierungsmethode und dann den Tab Extended UI. Finden Sie die erweiterte UI Seite und konfigurieren Sie die API.

• Optional Claims auswählen, die an die API gesendet werden sollen.
• Base API URL ohne den validate Ordner in API URL hinzufügen
• API secret hinzufügen
• Eine generische Fehlermeldung hinzufügen, die dem Benutzer angezeigt wird, wenn die API einen Fehler ohne UiErrorMessage zurückgibt