Uitgebreide UI

Je kunt de login gebruikersinterface (UI) flow uitbreiden met aangepaste loginpagina's die zijn opgebouwd uit dynamische elementen. De uitgebreide UI's ondersteunen culture en meerdere talen volledig. Het is mogelijk om meerdere aangepaste UI's met verschillende dynamische elementen te maken. Elke uitgebreide UI-pagina kan optioneel een API aanroepen. Als een API wordt aangeroepen, worden de geretourneerde claims toegevoegd aan de claims-collectie; anders worden de invoerwaarden toegevoegd als het output claim type dat op de dynamische elementen is gedefinieerd.

De dynamische elementen bestaan uit vaste velden, een aanpasbaar veld en zowel tekst- als HTML-inhoudelementen. Hiermee kun je eenvoudig de naam van de gebruiker vragen, één of meerdere zelf gedefinieerde velden gebruiken en een logo en link tonen op een uitgebreide UI-pagina.

Uitgebreide UI's kunnen worden toegevoegd aan de volgende authenticatiemethoden in het tabblad Extended UI; login, external login, OpenID Connect, SAML 2.0 en environment link.

Selecteer uitgebreide UI-pagina Je selecteert een uitgebreide UI-pagina in de loginflow door de claim type open_extended_ui toe te voegen met de naam van de uitgebreide UI-pagina in de first-level claim transforms. In een SAML 2.0 authenticatiemethode selecteer je de uitgebreide UI-pagina met de overeenkomstige SAML 2.0 claim http://schemas.foxids.com/ws/identity/claims/openextendedui in de first-level claim transforms. Daarna kunnen uitgebreide UI-pagina's worden geselecteerd in de extended UI claim transforms door de claim type open_extended_ui (alleen JWT claim) toe te voegen met de naam van de volgende uitgebreide UI-pagina.

Voorbeeld Deze voorbeeldpagina vraagt de gebruiker om zijn burgerservicenummer in te voeren (getoond in twee talen). De voorbeeld uitgebreide UI voegt de invoerwaarde toe aan de claims-collectie als claim type social_security_number. In een echte situatie zou je waarschijnlijk een API aanroepen om het burgerservicenummer te valideren. In het Engels:

In het Deens:

De voorbeeldpagina is geconfigureerd in een authenticatiemethode in het tabblad Extended UI met drie elementen.

De uitgebreide UI kan worden aangepast met CSS in de login authenticatiemethode genaamd Default login, tenzij je een andere loginmethode maakt en die gebruikt. Er is veel flexibiliteit in het ontwerp van de dialogen.

Vertalingen

De teksten (en foutmeldingen) die in dynamische elementen worden gebruikt, worden automatisch vertaald als ze zijn gedefinieerd als globale teksten met vertalingen. Anders wordt automatisch een textelement aangemaakt in de environment waar je vertalingen kunt toevoegen. Als je meerdere talen wilt ondersteunen, moet je de teksten in het Engels maken en vertalingen toevoegen.

Je vindt de teksten en vertalingen in het tabblad Settings en daarna in het tabblad Texts.

API implementeren

Elke uitgebreide UI-pagina kan een API aanroepen met het resultaat van de dynamische elementen en geselecteerde claims. De API kan vervolgens de gebruikersinvoer valideren en bij succes claims of een foutmelding aan de gebruiker teruggeven.

Je moet een eenvoudige API implementeren die FoxIDs aanroept wanneer de gebruiker de pagina verstuurt. Bekijk de sample code.

De API heeft een base URL en de functionaliteit is verdeeld in mappen. Momenteel wordt alleen de validate map (functionaliteit) voor het valideren van de dynamische elementen en geselecteerde claims ondersteund. Andere mappen kunnen later worden toegevoegd.

Als de base URL voor de API https://somewhere.org/mystore is, is de URL voor de validate map https://somewhere.org/mystore/validate.

FoxIDs Cloud roept je API aan vanaf IP-adres 57.128.60.142. Het uitgaande IP-adres kan veranderen en er kunnen in de loop van de tijd meer worden toegevoegd.

Request

De API-call is beveiligd met HTTP Basic authentication, waarbij FoxIDs de ID external_extended_ui als gebruikersnaam en het geconfigureerde secret als wachtwoord verstuurt.

De API wordt aangeroepen met HTTP POST en een JSON body.

Dit is een request JSON body met twee dynamische elementen en twee 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 Bij succes moet de API HTTP code 200 retourneren en een lijst met claims (de lijst kan leeg zijn).

Bijvoorbeeld de geldige invoerwaarden als claims:

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

Error De API moet HTTP code 401 (Unauthorized) retourneren en een error (vereist) als de Basic authentication wordt afgewezen. Voeg optioneel een foutbeschrijving toe in ErrorMessage.

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

De API kan HTTP code 400 (401 en 403 worden ook ondersteund) en een error (vereist) retourneren als de input wordt afgewezen. Voeg optioneel een foutmelding voor de gebruiker toe in UiErrorMessage en een foutbeschrijving in ErrorMessage. UiErrorMessage wordt vertaald als tekst en moet in het Engels zijn als je meerdere talen wilt ondersteunen.

Een algemene validatiefout:

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

Een validatiefout gekoppeld aan een dynamisch element via de elementnaam:

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

Als er andere fouten optreden, moet de API HTTP code 500 of een andere passende foutcode retourneren. Het wordt aanbevolen om een technische foutmelding in ErrorMessage toe te voegen. De foutmelding kan later in de FoxIDs logs worden gevonden.

Foutmeldingen die door de API in ErrorMessage worden geretourneerd, worden NIET aan de gebruiker getoond; ze worden alleen gelogd.

API Sample

De sample ExternalExtendedUiApiSample laat zien hoe je de API implementeert in ASP.NET Core.

Je kunt deze Postman collection gebruiken om je API aan te roepen en te testen met Postman.

Configure

Configureer een uitgebreide UI-pagina in een authenticatiemethode om je API aan te roepen in FoxIDs Control Client.

Navigeer naar het tabblad Authentication en selecteer de authenticatiemethode, en selecteer vervolgens het tabblad Extended UI. Zoek de uitgebreide UI-pagina en configureer de API.

• Optioneel claims selecteren die naar de API moeten worden verzonden.
• Voeg de base API URL zonder de validate map toe in API URL
• Voeg de API secret toe
• Voeg een algemene foutmelding toe die aan de gebruiker wordt getoond als de API een fout retourneert zonder UiErrorMessage