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 - corresponder ao claim e encontrar exatamente um utilizador interno com base no valor do claim. O pedido falha se for encontrado mais do que um utilizador. Depois adiciona/substitui os claims do utilizador.
• Query external user - corresponder ao claim e encontrar exatamente um utilizador externo com base no valor do claim. O pedido falha se for encontrado mais do que um utilizador. Depois adiciona/substitui os claims do utilizador.

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

• Match claim and return error - devolver um erro se o tipo de claim corresponder/não corresponder.
• Match claim and value and return error - devolver um erro se o tipo de claim e o valor corresponderem/não corresponderem.
• Regex match and return error - devolver um erro se o tipo de claim e o valor do claim corresponderem/não corresponderem à expressão regular.
• Match claim and start authentication - iniciar um novo fluxo de login ao iniciar um método de autenticação se o tipo de claim corresponder/não corresponder.
• Match claim and value and start authentication - iniciar um novo fluxo de login ao iniciar um método de autenticação se o tipo de claim e o valor corresponderem/não corresponderem.
• Regex match and start authentication - iniciar um novo fluxo de login ao iniciar um método de autenticação se o tipo de claim e o valor do claim corresponderem/não corresponderem à expressão regular.

As tarefas de claim start authentication 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