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.

As quatro tarefas de utilizador indicadas acima consideram um utilizador indisponível quando a conta está desativada diretamente ou através de uma membership ativa numa estrutura de acesso. O utilizador é excluído antes de o FoxIDs determinar se a pesquisa encontrou exatamente um utilizador, pelo que as tarefas query não adicionam claims e as tarefas save não efetuam alterações.

Quando uma das duas tarefas query user é executada num método de autenticação e ainda não existe uma conta local associada à resposta de autenticação atual, o primeiro utilizador correspondido de forma inequívoca na ordem de execução das claim transformations torna-se a conta local da resposta. Se a autenticação continuar através de passos Extended UI, o FoxIDs mantém este snapshot de acesso na sequência server-side e utiliza-o quando a resposta é concluída. Em seguida, o FoxIDs aplica a associação às sessões ativas e aos refresh token grants. Um utilizador interno ou um utilizador externo associado que seja autenticado diretamente pelo método de autenticação tem prioridade, e uma associação existente nunca é substituída por uma query posterior.

Se uma claim transformation iniciar interativamente outro método de autenticação, a autenticação redirecionada é executada como um novo login flow. Uma associação de conta local selecionada por uma query anterior não é transportada através desse redirecionamento.

As tarefas query user num registo de aplicação podem adicionar claims, mas não criam nem alteram a associação de conta local do login.

As tarefas query user disponibilizam o ID estável do utilizador selecionado como um claim local:

Claim task	Claim local	Valor
Query internal user	_local:internal_user_id	O ID técnico e estável de utilizador FoxIDs do utilizador interno selecionado.
Query external user	_local:external_user_id	O ID técnico e estável de utilizador externo FoxIDs do utilizador externo selecionado.

Selecione explicitamente o claim local nos outgoing claims da tarefa, ou selecione *, para o disponibilizar às transformações seguintes na mesma sequência. Os claims locais são removidos do resultado final, exceto se o respetivo valor for mapeado para um claim não local.

Os tipos de claim que começam por _local: e _internal: são reservados pelo FoxIDs. Os claims em qualquer destes namespaces recebidos de um método de autenticação, de uma entrada de protocolo ou de uma claims API externa são removidos antes de poderem ser considerados fidedignos. Os claims reservados armazenados num utilizador existente são ignorados, e as claim tasks não podem guardá-los num utilizador interno ou externo.

• Os claims _local: existem apenas no conjunto atual de claim transformations e claim tasks. Qualquer transformação normal pode criar um claim _local:*, as transformações seguintes no mesmo conjunto podem utilizá-lo e o FoxIDs remove-o sempre quando o conjunto termina.
• Os claims _internal: podem transportar valores entre conjuntos de claim transformations e claim tasks dentro do FoxIDs. Qualquer transformação normal pode criar um claim _internal:* e um conjunto posterior pode lê-lo. O FoxIDs remove os claims internos antes de os claims saírem do FoxIDs num token, numa assertion ou noutra resposta de protocolo.

Por exemplo, uma transformação num método de autenticação pode criar _internal:account_category. Um conjunto de transformações posterior no método de autenticação ou no registo de aplicação pode utilizar esse claim para tomar uma decisão sem o expor à aplicação.

Por exemplo, depois de procurar um utilizador interno por e-mail ou nome de utilizador, uma tarefa Match claim and return error pode verificar _local:internal_user_id e interromper o flow se não tiver sido encontrado um único utilizador interno. Uma transformação Match claim pode, em alternativa, adicionar outro claim apenas quando a pesquisa for bem-sucedida. O ID estável do utilizador permanece local à sequência de transformações, continuando a fornecer uma base fiável para decisões posteriores.

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).

O FoxIDs ignora os claims cujo type ou value está em falta, é null, está vazio ou contém apenas espaços em branco. Com o rastreio de mensagens de registo ativado, o rastreio da resposta inclui os claims recebidos antes de serem filtrados. As mensagens de rastreio longas são truncadas.

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