Interfaccia utente estesa

Puoi estendere il flusso dell'interfaccia utente (UI) di login con pagine di login personalizzate costruite con elementi dinamici. Le interfacce estese supportano completamente culture e piu lingue. E possibile creare piu UI personalizzate con elementi dinamici diversi.
Ogni pagina di UI estesa puo facoltativamente chiamare un'API. Se viene chiamata un'API, i claim restituiti vengono aggiunti alla raccolta di claim; altrimenti, i valori di input vengono aggiunti come tipo di claim di output definito sugli elementi dinamici.

Gli elementi dinamici consistono in campi fissi, un campo personalizzabile ed elementi di contenuto testuale e HTML. Con questo puoi facilmente chiedere il nome dell'utente, usare uno o piu campi da te definiti e mostrare un logo e un link in una pagina di UI estesa.

Le interfacce estese possono essere aggiunte ai seguenti metodi di autenticazione nella scheda Extended UI: login, external login, OpenID Connect, SAML 2.0 ed environment link.

Selezionare la pagina di UI estesa
Selezioni una pagina di UI estesa nel flusso di login aggiungendo il tipo di claim open_extended_ui con il nome della pagina di UI estesa nelle trasformazioni dei claim di primo livello. In un metodo di autenticazione SAML 2.0, seleziona la pagina di UI estesa con il corrispondente claim SAML 2.0 http://schemas.foxids.com/ws/identity/claims/openextendedui nelle trasformazioni dei claim di primo livello.
Successivamente, le pagine di UI estesa possono essere selezionate nelle trasformazioni dei claim della UI estesa aggiungendo il tipo di claim open_extended_ui (solo claim JWT) con il nome della pagina di UI estesa successiva.

Esempio
Questa pagina di esempio chiede all'utente di inserire il proprio numero di previdenza sociale (mostrato in due lingue). L'esempio di UI estesa aggiunge il valore di input alla raccolta di claim come tipo di claim social_security_number. In uno scenario reale, probabilmente chiameresti un'API per validare il numero di previdenza sociale.
In inglese:
Extended UI with Social security number field in English

In danese:
Extended UI with Social security number field in Danish

La pagina di esempio e configurata in un metodo di autenticazione nella scheda Extended UI con tre elementi.

Configure Extended UI with Social security number input field

La UI estesa puo essere personalizzata con CSS nel metodo di autenticazione login chiamato Default login, a meno che tu non crei un altro metodo di login e usi quello. C'e parecchia flessibilita nel modo in cui i dialoghi possono essere progettati.

Traduzioni

I testi (e i messaggi di errore) usati negli elementi dinamici vengono tradotti automaticamente se sono definiti come testi globali con traduzioni. Altrimenti viene creato automaticamente un elemento di testo negli ambienti dove puoi aggiungere traduzioni. Se vuoi supportare piu lingue, dovresti creare i testi in inglese e aggiungere le traduzioni.

Trovi i testi e le traduzioni nella scheda Settings e poi nella scheda Texts. Configure Extended UI with Social security number input field

Implementare API

Ogni pagina di UI estesa puo chiamare un'API con il risultato degli elementi dinamici e dei claim selezionati. L'API puo quindi validare l'input dell'utente e restituire, in caso di successo, claim oppure un messaggio di errore all'utente.

Devi implementare una semplice API che FoxIDs chiama quando l'utente invia la pagina.
Consulta il codice sample.

L'API ha un URL base e la funzionalita e suddivisa in cartelle. Attualmente e supportata solo la cartella validate (funzionalita) per validare gli elementi dinamici e i claim selezionati.
Altre cartelle potrebbero essere aggiunte in seguito.

Se l'URL base dell'API e https://somewhere.org/mystore, l'URL per la cartella validate sara https://somewhere.org/mystore/validate.

FoxIDs Cloud chiama la tua API dall'indirizzo IP 57.128.60.142.
L'indirizzo IP in uscita puo cambiare e nel tempo potrebbero essere aggiunti altri IP.

Richiesta

La chiamata API e protetta con HTTP Basic authentication, dove FoxIDs invia l'ID external_extended_ui come username e il secret configurato come password.

L'API viene chiamata con HTTP POST e un body JSON.

Questo e un body JSON di richiesta con due elementi dinamici e due claim:

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

Risposta

Successo
In caso di successo, l'API dovrebbe restituire codice HTTP 200 e un elenco di claims (l'elenco puo essere vuoto).

Ad esempio, i valori di input validi come claim:

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

Errore
L'API deve restituire codice HTTP 401 (Unauthorized) e un error (obbligatorio) se l'autenticazione Basic viene rifiutata. Facoltativamente aggiungi una descrizione dell'errore in ErrorMessage.

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

L'API puo restituire codice HTTP 400 (sono supportati anche 401 e 403), e un error (obbligatorio) se l'input viene rifiutato. Facoltativamente aggiungi un messaggio di errore per l'utente in UiErrorMessage e una descrizione dell'errore in ErrorMessage.
UiErrorMessage viene tradotto come testo e dovrebbe essere in inglese se vuoi supportare piu lingue.

Un errore di validazione generale:

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

Un errore di validazione collegato a un elemento dinamico tramite il nome dell'elemento:

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

Se si verificano altri errori, l'API dovrebbe restituire codice HTTP 500 o un altro codice di errore appropriato. Si raccomanda di aggiungere un messaggio tecnico di errore in ErrorMessage. Il messaggio di errore potra poi essere trovato successivamente nei log FoxIDs.

I messaggi di errore restituiti dall'API in ErrorMessage NON vengono mostrati all'utente; vengono solo registrati nei log.

Sample API

Il sample ExternalExtendedUiApiSample mostra come implementare l'API in ASP.NET Core.

Puoi usare questa Postman collection per chiamare e testare la tua API con Postman.

Configurare

Configura una pagina di UI estesa in un metodo di autenticazione per chiamare la tua API in FoxIDs Control Client.

Vai nella scheda Authentication e seleziona il metodo di autenticazione, quindi seleziona la scheda Extended UI. Trova la pagina di UI estesa e configura l'API.

Configure extended UI API

Seleziona facoltativamente i claim da inviare all'API.
Aggiungi l'URL base dell'API senza la cartella validate in API URL
Aggiungi API secret
Aggiungi un messaggio di errore generico da mostrare all'utente se l'API restituisce un errore senza UiErrorMessage