Interface de utilizador expandida

Pode estender o fluxo da interface de utilizador (UI) de login com páginas de login personalizadas construídas com elementos dinâmicos. As UIs expandidas suportam totalmente culture e múltiplas línguas. É possível criar várias UIs personalizadas com elementos dinâmicos diferentes.
Cada página de UI expandida pode opcionalmente chamar uma API. Se uma API for chamada, os claims devolvidos são adicionados à coleção de claims; caso contrário, os valores introduzidos são adicionados como o tipo de claim de saída definido nos elementos dinâmicos.

Os elementos dinâmicos consistem em campos fixos, um campo personalizável e elementos de conteúdo de texto e HTML. Com isto, pode facilmente pedir o nome do utilizador, usar um ou mais campos definidos por si e mostrar um logótipo e um link numa página de UI expandida.

As UIs expandidas podem ser adicionadas aos seguintes métodos de autenticação no separador Extended UI: login, external login, OpenID Connect, SAML 2.0 e environment link.

Selecionar página de UI expandida
Seleciona uma página de UI expandida no fluxo de login ao adicionar o tipo de claim open_extended_ui com o nome da página de UI expandida nas transformações de claims de primeiro nível. Num método de autenticação SAML 2.0, selecione a página de UI expandida com o claim SAML 2.0 correspondente http://schemas.foxids.com/ws/identity/claims/openextendedui nas transformações de claims de primeiro nível.
Subsequentemente, páginas de UI expandidas podem ser selecionadas nas transformações de claims da UI expandida ao adicionar o tipo de claim open_extended_ui (apenas claim JWT) com o nome da página de UI expandida seguinte.

Exemplo
Esta página de exemplo pede ao utilizador que introduza o seu número de segurança social (mostrado em duas línguas). O exemplo de UI expandida adiciona o valor introduzido à coleção de claims como o tipo de claim social_security_number. Num cenário real, provavelmente chamaria uma API para validar o número de segurança social.
Em inglês:
Extended UI with Social security number field in English

Em dinamarquês:
Extended UI with Social security number field in Danish

A página de exemplo está configurada num método de autenticação no separador Extended UI com três elementos.

Configure Extended UI with Social security number input field

A UI expandida pode ser personalizada com CSS no método de autenticação de login chamado Default login, a menos que crie outro método de login e use esse. Existe bastante flexibilidade na forma como os diálogos podem ser desenhados.

Traduções

Os textos (e mensagens de erro) usados em elementos dinâmicos são traduzidos automaticamente se estiverem definidos como textos globais com traduções. Caso contrário, é automaticamente criado um elemento de texto nos ambientes onde pode adicionar traduções. Se quiser suportar múltiplas línguas, deve criar os textos em inglês e adicionar traduções.

Encontra os textos e traduções no separador Settings e depois no separador Texts. Configure Extended UI with Social security number input field

Implementar API

Cada página de UI expandida pode chamar uma API com o resultado dos elementos dinâmicos e claims selecionados. A API pode então validar o input do utilizador e, em caso de sucesso, devolver claims ou uma mensagem de erro ao utilizador.

Precisa de implementar uma API simples que o FoxIDs chama quando o utilizador submete a página.
Consulte o código de exemplo.

A API tem um URL base e a funcionalidade está dividida em pastas. Atualmente, apenas é suportada a pasta validate (funcionalidade) para validar os elementos dinâmicos e os claims selecionados.
Podem ser adicionadas mais pastas mais tarde.

Se o URL base da API for https://somewhere.org/mystore, o URL da pasta validate será https://somewhere.org/mystore/validate.

O FoxIDs Cloud chama a sua API a partir do endereço IP 57.128.60.142.
O endereço IP de saída pode mudar e mais podem ser adicionados ao longo do tempo.

Pedido

A chamada da API é protegida com HTTP Basic authentication, em que o FoxIDs envia o ID external_extended_ui como username e o secret configurado como password.

A API é chamada com HTTP POST e um body JSON.

Este é um body JSON de pedido com dois elementos dinâmicos e dois 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"
        }
    ]
}

Resposta

Sucesso
Em caso de sucesso, a API deve devolver código HTTP 200 e uma lista de claims (a lista pode estar vazia).

Por exemplo, os valores de input válidos como claims:

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

Erroro
A API tem de devolver código HTTP 401 (Unauthorized) e um error (obrigatório) se a autenticação Basic for rejeitada. Opcionalmente adicione uma descrição do erro em ErrorMessage.

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

A API pode devolver código HTTP 400 (401 e 403 também são suportados), e um error (obrigatório) se o input for rejeitado. Opcionalmente adicione uma mensagem de erro para o utilizador em UiErrorMessage e uma descrição do erro em ErrorMessage.
UiErrorMessage é traduzido como texto e deve estar em inglês se quiser suportar múltiplas línguas.

Um erro geral de validação:

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

Um erro de validação ligado a um elemento dinâmico pelo nome do 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 ocorrerem outros erros, a API deve devolver código HTTP 500 ou outro código de erro apropriado. Recomenda-se adicionar uma mensagem de erro técnica em ErrorMessage. A mensagem de erro poderá depois ser encontrada nos logs do FoxIDs.

As mensagens de erro devolvidas pela API em ErrorMessage NÃO são mostradas ao utilizador; apenas são registadas.

Exemplo de API

O sample ExternalExtendedUiApiSample mostra como implementar a API em ASP.NET Core.

Pode usar esta Postman collection para chamar e testar a sua API com Postman.

Configurar

Configure uma página de UI expandida num método de autenticação para chamar a sua API no FoxIDs Control Client.

Navegue até ao separador Authentication e selecione o método de autenticação, depois selecione o separador Extended UI. Encontre a página de UI expandida e configure a API.

Configure extended UI API

Opcionalmente selecione claims que devem ser enviados para a API.
Adicione o URL base da API sem a pasta validate em API URL
Adicione o API secret
Adicione uma mensagem de erro genérica que é mostrada ao utilizador se a API devolver um erro sem UiErrorMessage