Transformações e tarefas de claims

Cada método de autenticação e registo de aplicação do FoxIDs trata claims e suporta transformações e tarefas de claims. Isto significa que múltiplos conjuntos de transformações e tarefas de claims podem ser executados para cada autenticação de utilizador. Primeiro, as transformações e tarefas de claims são executadas no método de autenticação e depois no registo de aplicação.

Subconjuntos adicionais de transformações e tarefas de claims podem ser executados se for criado um utilizador ou um utilizador externo.

Se criar um novo claim com uma transformação ou tarefa de claim de primeiro nível, o claim é local ao método de autenticação, exceto num método de autenticação Login.
Num método de autenticação, o claim é encaminhado se o tipo de claim for adicionado à lista Forward claims, ou se * (predefinição) estiver incluído nessa lista.

Se criar um novo claim com uma transformação ou tarefa de claim, o claim é local ao registo de aplicação.
Num registo de aplicação, deve adicionar o claim ou * à lista Issue claims. Em alternativa, para OpenID Connect, adicione o claim à lista Voluntary claims de um scope e peça o scope a partir da sua aplicação.

Veja por favor os exemplos de transformação de claims.

Ative Log claim trace nas definições de log para ver os claims antes e depois da transformação nos logs.

As transformações de claims podem ser configuradas num método de autenticação login.

E tarefas de claims.

Da mesma forma, transformações e tarefas de claims podem ser configuradas como primeiro e segundo nível num método de autenticação OpenID Connect.

Os claims são, por predefinição, representados como claims JWT. Se o método de autenticação for SAML 2.0, os claims de primeiro nível são representados como claims SAML 2.0. Se o registo de aplicação for SAML 2.0, os claims são representados como claims SAML 2.0.

Uma transformação de claim e uma tarefa de claim executam uma de até sete ações diferentes, dependendo do tipo específico de transformação ou tarefa.

Ações de transformações e tarefas de claims:

• Add claim - adicionar um novo claim
• Add claim, if not match - executar a ação de adicionar se a condição não corresponder
• Replace claim - adicionar um novo claim e remover claims existentes se um ou mais existirem
• Replace claim, if not match - executar a ação de substituir se a condição não corresponder
• Remove claim - remover os claims se um ou mais existirem
• If match - executar a ação se a condição corresponder
• If not match - executar a ação se a condição não corresponder

As transformações e tarefas de claims são executadas por ordem, e as ações são por isso executadas por ordem. Isto significa que é possível criar uma variável local adicionando um claim e mais tarde, na sequência, tomar decisões com base nesse claim. Um claim é local no conjunto de transformações e tarefas de claims se começar por _local:.

Quando transformações e tarefas de claims correm num fluxo de login, o FoxIDs adiciona automaticamente claims locais do pedido de login antes de executar as transformações. Estes claims _local: destinam-se a decisões internas dentro da sequência de transformação/tarefa e são removidos da saída.

Claims locais adicionados em AddLocalClaims:

• _local:login_action - a ação do pedido de login, guardada como camelCase
• _local:user_id - o ID de utilizador do pedido de login (apenas se fornecido)
• _local:max_age - o max age do pedido de login (apenas se definido e superior a 0)
• _local:login_hint - o hint do pedido de login (apenas se fornecido)
• _local:acr - os valores ACR do pedido de login como lista delimitada por espaços (apenas se fornecida)

Com a ação Add claim, if not match é possível adicionar um claim (variável local) se outro claim ou um valor de claim não existir.

Tipos de transformação de claims que suportam todas as ações:

• Match claim - executar a ação se o tipo de claim corresponder
• Match claim and value - executar a ação se o tipo de claim e o valor do claim corresponderem
• Regex match - executar a ação se o tipo de claim corresponder e o valor do claim corresponder à expressão regular

Tipos de transformação de claims que suportam as ações Add claim, Replace claim e Add claim, if new claim does not exist:

• Map - executar a ação se o tipo de claim corresponder, e depois mapear o valor do claim para um novo claim
• Regex map - executar a ação se o tipo de claim corresponder e o valor do claim corresponder ao grupo da expressão regular, e depois mapear o valor do grupo para um novo claim

Tipos de transformação de claims que suportam as ações Add claim e Replace claim:

• Constant - executar sempre a ação (adicionar/substituir um claim com um valor constante)
• Concatenate - executar a ação se um ou mais tipos de claim corresponderem, e depois concatenar os valores dos claims para um novo claim
• External claims API - chamar uma API externa com os claims selecionados para adicionar/substituir claims com claims externos
• DK XML privilege to JSON - converter o DK privilege para JSON

Tipos de tarefa de claim que suportam as ações Add claim e Replace claim:

• Query internal user - usar o valor do claim de lookup para encontrar um utilizador interno e depois adicionar ou substituir claims selecionados desse utilizador interno no claim set atual.
• Query external user - usar o valor do claim de lookup para encontrar um utilizador externo e depois adicionar ou substituir claims selecionados desse utilizador externo no claim set atual.
• Save claim on internal user - usar o valor do claim de lookup para encontrar um utilizador interno e depois adicionar ou substituir o claim selecionado nesse utilizador interno com valores do claim de valor de atualização selecionado no claim set atual.
• Save claim on external user - usar o valor do claim de lookup para encontrar um utilizador externo e depois adicionar ou substituir o claim selecionado nesse utilizador externo com valores do claim de valor de atualização selecionado no claim set atual.

Tipos de claim transform que suportam todas as ações:

• Match claim - verifica se o tipo de claim selecionado existe. Para ações add e replace, o claim de saída é escrito com o novo valor quando o claim existe. As ações if not match são executadas quando o claim não existe. Uma ação remove remove o claim de saída selecionado quando o claim existe.
• Match claim and value - verifica se o tipo de claim selecionado existe com o valor configurado. Para ações add e replace, o claim de saída é escrito com o novo valor quando o tipo e o valor correspondem. As ações if not match são executadas quando o claim existe mas o valor não corresponde. Uma ação remove remove o claim de saída selecionado quando o tipo e o valor correspondem.
• Regex match - verifica se o tipo de claim selecionado existe e se o valor corresponde à expressão regular configurada. Para ações add e replace, o claim de saída é escrito com o novo valor quando a expressão regular corresponde. As ações if not match são executadas quando o claim existe mas o valor não corresponde à expressão regular. Uma ação remove remove o claim de saída selecionado quando a expressão regular corresponde.

Tipos de claim transform que suportam as ações Add claim, Replace claim e Add claim, if new claim does not exist:

• Map - copia o valor do claim selecionado para o claim de saída. Com Add claim, if new claim does not exist, o valor só é escrito se o claim de saída ainda não existir.
• Regex map - extrai o grupo regex nomeado map do valor do claim selecionado e escreve o valor extraído no claim de saída. Com Add claim, if new claim does not exist, o valor só é escrito se o claim de saída ainda não existir.

Tipos de claim transform que suportam as ações Add claim e Replace claim:

• Constant - escreve sempre o valor constante configurado no claim de saída.
• Concatenate - constrói o claim de saída a partir de valores nos claims selecionados. A format string usa placeholders como {0}, {1} e {2} para os valores selecionados por ordem.
• External claims API - envia claims selecionados para uma API externa. Claims devolvidos pela API são adicionados ou substituem claims de saída.
• DK XML privilege to JSON - converte um claim XML DK privilege para claims JSON, um claim para cada elemento XML PrivilegeGroup.

Tipos de claim task que suportam as ações Add claim e Replace claim:

• Query internal user - usa o valor do lookup claim para encontrar exatamente um utilizador interno e depois adiciona ou substitui claims selecionados desse utilizador no claim set atual.
• Query external user - usa o valor do lookup claim para encontrar exatamente um utilizador externo e depois adiciona ou substitui claims selecionados desse utilizador no claim set atual.
• Save claim on internal user - usa o valor do lookup claim para encontrar exatamente um utilizador interno e depois adiciona ou substitui o claim selecionado nesse utilizador com valores do update value claim selecionado no claim set atual.
• Save claim on external user - usa o valor do lookup claim para encontrar exatamente um utilizador externo e depois adiciona ou substitui o claim selecionado nesse utilizador com valores do update value claim selecionado no claim set atual.

Para Query internal user e Save claim on internal user, o lookup claim é lido a partir do claim set atual. O valor Lookup claim on internal user define como o utilizador interno é correspondido:

• sub corresponde ao ID de utilizador do utilizador interno.
• email, phone_number e preferred_username pesquisam primeiro nos identifiers do utilizador interno com correspondência sem distinguir maiúsculas de minúsculas quando a capitalização é relevante. Se nenhum utilizador for encontrado por identifier, a pesquisa continua nos claims guardados do utilizador.
• A pesquisa continua depois nos claims guardados do utilizador interno para o mesmo tipo de claim e um valor correspondente sem distinguir maiúsculas de minúsculas. Isto aplica-se a todos os tipos de lookup claim se nenhum utilizador tiver sido encontrado primeiro.

Se a pesquisa encontrar exatamente um utilizador interno, Query internal user adiciona ou substitui claims selecionados desse utilizador no claim set atual. Save claim on internal user adiciona ou substitui o claim selecionado nesse utilizador com valores do update value claim selecionado. Se nenhum utilizador for encontrado, ou se for encontrado mais do que um utilizador através de claims, não são adicionados nem guardados claims de utilizador interno.

Para Query external user e Save claim on external user, o lookup claim é lido a partir do claim set atual e correspondido contra a fonte de utilizadores externos selecionada. Use link_claim como lookup claim no utilizador externo para corresponder ao valor de link claim desse utilizador.

Tipos de claim task que suportam as ações If match e If not match:

• Match claim and return error - devolve um erro se o tipo de claim corresponder ou não corresponder.
• Match claim and value and return error - devolve um erro se o tipo de claim e o valor corresponderem ou não corresponderem.
• Regex match and return error - devolve um erro se o tipo de claim e o valor corresponderem ou não corresponderem à expressão regular.
• Match claim and log event - escreve o valor do claim selecionado no log se o tipo de claim corresponder.
• Match claim and start authentication - inicia um novo login flow ao iniciar um método de autenticação se o tipo de claim corresponder ou não corresponder.
• Match claim and value and start authentication - inicia um novo login flow ao iniciar um método de autenticação se o tipo de claim e o valor corresponderem ou não corresponderem.
• Regex match and start authentication - inicia um novo login flow ao iniciar um método de autenticação se o tipo de claim e o valor corresponderem ou não corresponderem à expressão regular.

Para return error tasks, configure o erro de protocolo devolvido ao cliente ou requester. Configurações OpenID Connect e OAuth 2.0 devolvem um error e uma error description opcional. Configurações SAML 2.0 devolvem um SAML status code e uma message.

As start authentication claim tasks podem ser usadas para step-up quando o utilizador inicia sessão com um fator e é necessário outro fator, ou quando são necessárias informações adicionais (claims).

Claims externos - API

Pode chamar a sua própria API a partir do FoxIDs com uma transformação de claims. A API é chamada com claims e os claims devolvidos pela API podem ser adicionados com uma ação de add ou replace. A API só é chamada se pelo menos um claim selecionado existir. Pode usar * para selecionar e enviar todos os claims para a sua API.

Cenários de utilização:

• Chamar a sua API a partir de um método de autenticação sempre que um utilizador se autentica no FoxIDs ou com um identity provider externo. Pode então encontrar o utilizador na sua base de dados e devolver um user ID e talvez um customer ID ou basicamente qualquer coisa relevante. Por exemplo, também pode criar o utilizador na sua base de dados.
• Chamar a sua API a partir de um registo de aplicação com o user ID (sub) e consultar os roles do utilizador na sua base de dados. A sua API devolveria então uma lista vazia ou uma lista de role claims ou talvez uma estrutura de permissões mais complexa.

Implementar API

Tem de implementar uma API simples que o FoxIDs chama quando a transformação de claims é executada.
Veja por favor o código de exemplo.

A API tem um URL base e a funcionalidade está dividida em pastas. Atualmente, apenas a pasta claims (funcionalidade) para pedir uma lista de claims é suportada.

Se o URL base da API for https://somewhere.org/myclaimsstore, o URL para a pasta claims será https://somewhere.org/myclaimsstore/claims.

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

Protegido com HTTP Basic auth: username external_claims, password = secret configurado.

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

Este é um corpo JSON de pedido com dois claims de entrada:

{
  "claims": [
    { "type": "sub", "value": "1b1ac05e-5937-4939-a49c-0e84a89662df" },
    { "type": "email", "value": "some@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, o sub do utilizador (user ID / username), customer ID e roles:

{
    "claims": [
        { "type": "sub", "value": "somewhere/external-some@test.org" },
        { "type": "customer_id", "value": "1234abcd" },
        { "type": "role", "value": "admin_access" },
        { "type": "role", "value": "read_access" },
        { "type": "role", "value": "write_access" }
    ]
}

Resposta - Erro

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

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

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 para diagnóstico (apenas é registada no log; nunca é mostrada ao utilizador final).

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

Exemplo de API

O sample ExternalClaimsApiSample 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 o FoxIDs para chamar a sua API a partir de uma transformação de claims no FoxIDs Control Client.

1. Navegue até à secção Claim Transform
2. Clique em Add claim transform
3. Clique em External claims API
4. Selecione Add claim ou Replace claim
5. Adicione os claims selecionados, por exemplo sub, em Select claims
6. Adicione o URL base da API sem a pasta claims em API URL
7. Adicione o API secret
8. Clique em Update

Exemplos de transformação de claims

Dividir o claim name nos dois claims given_name e family_name

A transformação divide o valor do claim name no primeiro espaço encontrado e adiciona, respetivamente, os claims given_name e family_name, se ainda não existirem.
Se existir mais do que um espaço no valor do claim name, novos claims given_name e family_name não serão adicionados porque já existirão.

Use duas transformações de claims Regex map.

• Encontrar o valor do claim family_name com a regex ^\S+\s(?<map>\S+)$
• Encontrar o valor do claim given_name com a regex ^(?<map>\S+)\s\S+$

Remover o nome do método de autenticação adicionado por predefinição de sub

O nome do método de autenticação é adicionado por predefinição ao valor do claim sub como prefixo separado por um pipe, por exemplo some-auth-method|my-external-user-id.

Pode usar replace claim no claim sub para remover o valor prefixado adicionado por predefinição.

A transformação dividirá o valor do claim sub e substituirá o claim por um novo sub que contém apenas o ID original.

Use uma transformação de claim Regex map e selecione a ação Replace claim.

Encontrar o ID sem o nome do método de autenticação adicionado por predefinição com a regex ^([^|]+)\|(?<map>.+)$

Pode fazer o mesmo num método de autenticação SAML 2.0 usando o claim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier (que contém o valor NameID da SAML 2.0 Authn Response) em vez do claim sub.

Comparar email com _local:mfa:email e adicionar amr

O exemplo compara o email do utilizador atualmente autenticado com o _local:mfa:email do utilizador MFA já autenticado. Se os dois valores de email forem iguais e corresponderem a uma expressão regular, o claim amr é adicionado com o nome do método de autenticação como valor (o nome do método de autenticação é configurado como valor amr).

Use uma transformação de claim Concatenate seguida de uma transformação de claim Regex match.

• Concatenate: Novo claim _local:compare_emails, ação Replace claim, concatenar claims email e _local:mfa:email, formato de concatenação {0}|{1}.
• Regex match: Novo claim amr, ação Replace claim, selecionar claim _local:compare_emails, regex value match ^([^|]+)\|\1$, novo valor definido para o nome do método de autenticação (por exemplo 9fk5z3vg).

Documentação relacionada

• Claims
• Estrutura de acesso
• Login e Home Realm Discovery
• Método de autenticação OpenID Connect
• Método de autenticação SAML 2.0