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.

Nos métodos de autenticação com uma lista Forward claims, adicione a essa lista os claims comuns criados pelas transformações de primeiro nível para os disponibilizar nos passos seguintes, ou inclua * (predefinição). Os métodos Login encaminham estes claims sem essa lista.

Os prefixos reservados _local:, _internal:, _session: e _impersonate: determinam como os claims são utilizados durante a autenticação. Consulte Claims locais, internos e de sessão para conhecer os diferentes períodos de disponibilidade.

Para emitir um claim comum a partir de um registo de aplicação, adicione-o ou adicione * a Issue claims. No OpenID Connect também pode adicioná-lo aos Voluntary claims de um scope e pedir esse scope na aplicação. Os claims reservados não são emitidos, mesmo com *.

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 gerais adicionados a partir do pedido de início de sessão:

• _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)
• _local:params:{name} - um parâmetro de pedido da aplicação permitido, com o nome do parâmetro em minúsculas e um claim por valor (apenas se for fornecido)

Quando um método de autenticação é utilizado como elemento de Advanced MFA, as suas próprias transformações de claims recebem os seguintes claims locais para o utilizador já autenticado pelo método de autenticação Login:

Claim	Valor
_local:mfa:user_id	O ID de utilizador técnico estável do utilizador no FoxIDs.
_local:mfa:user_identifier	O identificador utilizado na autenticação Login. Se não tiver sido fornecido um identificador, o FoxIDs utiliza o endereço de e-mail, o número de telefone ou o nome de utilizador.
_local:mfa:username	O nome de utilizador registado do utilizador.
_local:mfa:email	O endereço de e-mail registado do utilizador, ou o valor do seu claim email se o endereço registado estiver vazio.
_local:mfa:phone	O número de telefone registado do utilizador, ou o valor do seu claim phone_number se o número registado estiver vazio.

Só são adicionados claims com um valor não vazio. Estas transformações processam os claims devolvidos pelo fornecedor de identidade externo e podem adicionar o valor AMR exigido pelo elemento MFA. O fluxo MFA de Login utiliza a resposta transformada para validar esse valor AMR. Os restantes claims devolvidos pelo método de autenticação não são combinados com os claims do método de autenticação Login nem enviados para as suas transformações de claims gerais.

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 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.
• Impersonation - prepara um target local selecionado como utilizador efetivo após as transformações do método de autenticação. Consulte Personificação.
• 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. Uma tarefa Query internal user com Target fornece apenas claims locais e mantém esta associação de conta inalterada. Se a autenticação continuar através de passos Extended UI, o FoxIDs mantém o snapshot de acesso da conta selecionada 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.

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

Carregar um utilizador interno em claims locais

Defina o Target opcional de Query internal user para carregar os claims de outro utilizador para verificações ou transformações, mantendo a associação do início de sessão à conta local. Introduza um nome como target; o FoxIDs adiciona _local: e coloca o nome antes de cada tipo de claim selecionado:

Claim selecionado	Resultado local com Target target
sub	_local:target:sub
email	_local:target:email
role	_local:target:role
_local:internal_user_id	_local:target:_local:internal_user_id
_local:access_node	_local:target:_local:access_node
_local:access_claim	_local:target:_local:access_claim
_local:access_path_claim	_local:target:_local:access_path_claim

O tipo original completo do claim é mantido sob o nome do target. Isto distingue os claims auxiliares locais de contas e Access Structure dos claims normais. A pesquisa inclui claims resolvidos a partir de associações ativas de Access Structure, respeitando a definição Forward claims da estrutura, bem como claims auxiliares locais para verificar associações.

Selecione os claims pelos nomes originais em Claims from internal user ou utilize *. O nome completo do claim local, incluindo o prefixo e o nome do target, deve respeitar o limite de 100 caracteres. Deixe Target vazio para adicionar ou substituir os claims selecionados diretamente na coleção de claims atual.

Várias pesquisas e chamadas a Claims API podem preencher o mesmo target. Add claim adiciona os valores devolvidos. Replace claim substitui os valores dos tipos de claim devolvidos sob esse target e mantém os restantes claims já presentes.

Utilize os claims do target nas transformações seguintes do mesmo conjunto. Por exemplo, verifique _local:target:role ou mapeie _local:target:sub para _internal:selected_user_id para preservar esse valor em conjuntos de transformações posteriores. Os claims locais do target são removidos no final do conjunto.

Claims locais, internos e de sessão

Utilize estes prefixos para escolher o tempo de vida de um valor usado por transformações e tarefas de claims. Um conjunto de transformações é uma lista ordenada de transformações e tarefas: por exemplo, o primeiro nível do método de autenticação, uma lista Extended UI, o segundo nível ou a lista de um registo de aplicação. A passagem para outro conjunto é relevante mesmo quando ambos pertencem ao mesmo método.

Prefixo	Utilização	Onde o valor está disponível	Disponível num início de sessão posterior numa aplicação?
_local:	Valor ou decisão temporários num conjunto	Transformações e tarefas seguintes do mesmo conjunto. Removido no fim do conjunto.	Não. O FoxIDs pode fornecer novo contexto local de pedido ou tarefa num novo conjunto.
_internal:	Valor necessário em conjuntos posteriores do fluxo de autenticação atual	Transformações do método, continuações como Extended UI e transformações da aplicação. Removido antes de a resposta do protocolo sair do FoxIDs.	Não. Crie ou copie novamente o valor no novo fluxo.
_session:	Pequeno valor mantido para o mesmo utilizador autenticado	Restaurado antes do primeiro nível; disponível nas transformações intermédias e no segundo nível. Guardado após um segundo nível concluído com êxito e removido antes das transformações da aplicação.	Sim, através do mesmo método de autenticação enquanto a sessão do utilizador for válida.
_impersonate:	Uma identidade de destino preparada para personificação	Transformações do método de autenticação e Extended UI, até à conclusão da personificação após as transformações de segundo nível.	Prepare novamente o target em cada fluxo de início de sessão.

Por exemplo, _local:customer_found pode controlar a tarefa seguinte da mesma lista; _internal:customer_category pode ser lido mais tarde por uma transformação da aplicação; _session:profileId pode manter um perfil selecionado para o próximo início de sessão numa aplicação.

As transformações que criam um utilizador externo associado trabalham com os claims selecionados para esse passo e com os claims _session: atuais. Selecione um claim _internal: como entrada se as transformações de criação precisarem desse valor. Os claims de sessão permanecem no fluxo de autenticação e não são guardados na conta do utilizador externo.

Transformações como Constant, Map, Match claim e Match claim and value podem criar ou utilizar estes claims através das suas ações habituais. O prefixo controla o tempo de vida. Utilize _session: no método de autenticação: os claims de sessão criados pelas transformações da aplicação não são guardados na sessão do método.

Copiar um valor para outro tempo de vida

Uma transformação Map copia um valor para o claim de saída selecionado. A origem e o destino são claims distintos, com o tempo de vida dos respetivos prefixos. Quando os nomes diferem, Replace claim substitui os valores existentes do claim de destino e mantém o claim de origem. Alterações posteriores a um não atualizam automaticamente o outro.

Por exemplo, quando uma tarefa Query internal user devolve _local:internal_user_id, adicione no mesmo conjunto uma transformação Map de _local:internal_user_id para _internal:selected_user_id. Os conjuntos seguintes podem ler _internal:selected_user_id depois de o claim local ser removido. Uma transformação do método também pode copiar um valor _internal: para um claim _session: para o manter em inícios de sessão posteriores.

Transmitir um valor de sessão às transformações da aplicação

Suponha que _session:profileId contém customer-456 e que as transformações da aplicação precisam desse valor. Configure esta transformação na lista de segundo nível do método de autenticação, depois das que alteram o perfil selecionado:

Definição	Valor
Tipo de transformação	Map
Ação	Replace claim
Claim de entrada	_session:profileId
Claim de saída	_internal:profileId

O fluxo continua da seguinte forma:

1. Ambos os claims contêm customer-456 durante as transformações restantes do método.
2. No fim do segundo nível, o FoxIDs guarda _session:profileId para inícios de sessão posteriores e remove-o da coleção atual de claims.
3. _internal:profileId passa para as transformações da aplicação. Pode ser usado para decisões sem ser emitido para a aplicação.
4. Se a aplicação precisar do valor no seu token ou assertion, adicione uma transformação Map na aplicação de _internal:profileId para um claim comum como profile_id e configure a sua emissão.

No próximo início de sessão numa aplicação, o FoxIDs restaura _session:profileId para o mesmo utilizador autenticado. A transformação do método cria um novo _internal:profileId para esse fluxo. A mesma abordagem aplica-se quando o FoxIDs converte claims entre JWT e SAML.

Encaminhamento, mapeamento de protocolo e API externas

Os claims internos e de sessão não precisam de uma entrada em Forward claims; os limites gerais de comprimento continuam a aplicar-se. Os nomes reservados não são alterados pelo mapeamento de protocolo JWT/SAML, incluindo o automático. Utilize uma transformação de claim Map para copiar valores entre prefixos; os mapeamentos de protocolo não podem criar tipos de claims reservados.

Nenhum dos três espaços de nomes reservados é emitido em tokens ou assertions, mesmo com * em Issue claims. São também excluídos dos pedidos e respostas da API de claims externa. Mapeie o valor selecionado para um claim comum antes de o enviar a uma API e, se necessário, um claim comum da resposta para um claim reservado depois.

Os prefixos distinguem maiúsculas de minúsculas e são reservados pelo FoxIDs. Os claims reservados recebidos de um protocolo ou de uma API de integração são removidos antes das transformações. Os guardados num utilizador existente são ignorados, e as tarefas não podem guardá-los em utilizadores internos ou externos. Se uma tarefa iniciar outro método de autenticação, a coleção atual de claims não é transferida para o novo fluxo de início de sessão.

Claims de sessão

Utilize claims _session: para manter pequenas quantidades de estado para o mesmo utilizador autenticado entre inícios de sessão no navegador em diferentes aplicações. As sessões têm de estar ativadas no método de autenticação; estão ativadas por predefinição. O FoxIDs suporta claims de sessão em Login, External Login, OpenID Connect, SAML 2.0, WS-Federation e Environment Link.

O FoxIDs disponibiliza os claims de sessão guardados antes das transformações de primeiro nível. Permanecem disponíveis nas transformações intermédias, no Extended UI e no segundo nível. Quando estas transformações terminam com êxito, o FoxIDs guarda os claims de sessão resultantes. Remover um claim de sessão numa transformação também remove o seu valor guardado. Para utilizar um valor de sessão guardado nas transformações da aplicação, copie-o para um claim interno antes de o método de autenticação terminar.

Os claims de sessão pertencem ao utilizador autenticado originalmente, independentemente das alterações a sub nas transformações. Só são restaurados com um subject autenticado correspondente e uma sessão válida e ativa no mesmo método. Um método que aceite vários issuers tem de receber subjects únicos entre todos esses issuers. Uma tarefa que inicia autenticação não transfere claims de sessão para outro método; os fluxos que apenas processam tokens não leem nem guardam claims de sessão do navegador.

Login e External Login podem reutilizar a sessão do navegador. Os métodos baseados em protocolos externos continuam a autenticar no fornecedor de identidade externo em cada início de sessão numa aplicação; o FoxIDs restaura os claims de sessão depois de verificar a identidade devolvida. Estes claims seguem o tempo de vida da sessão do método e ficam indisponíveis após terminar a sessão ou revogá-la.

Quando um novo início de sessão verifica o mesmo utilizador enquanto a sessão anterior ainda é válida, o FoxIDs mantém os valores guardados dessa sessão durante as transformações de claims e o Extended UI, até que as transformações de segundo nível terminem com êxito e os substituam. Um novo início de sessão concluído reinicia o tempo de vida absoluto da sessão do método de autenticação; a reutilização de uma sessão Login ou External Login segue os tempos de vida deslizante e absoluto configurados.

O Login e o External Login mantêm os claims originais na sessão do navegador antes de executar as transformações de claims. Após a conclusão com êxito das transformações de segundo nível, o FoxIDs atualiza os claims de sessão do utilizador autenticado, incluindo após o Extended UI. Esta atualização mantém os claims comuns e a expiração da sessão. Cada método de autenticação mantém um utilizador atual e um conjunto de claims de sessão no navegador. Um novo início de sessão segue o comportamento normal das sessões do método de autenticação; o navegador utiliza o último cookie de sessão recebido.

Os claims de sessão têm estes limites de armazenamento:

Limite	Valor
Nome do claim	100 caracteres, incluindo _session:, com um nome de claim JWT válido e um nome após o prefixo que não esteja vazio nem contenha apenas espaços em branco
Valor individual	1 000 caracteres
Número de claims	10 pares nome/valor; cada valor de um claim com vários valores conta separadamente
Comprimento total dos valores	2 000 caracteres

Os claims com nomes inválidos ou valores vazios ou constituídos apenas por espaços em branco são omitidos. Os valores mais longos são truncados. Os claims são considerados por ordem; a gravação para quando o próximo claim válido excederia o limite de quantidade ou de comprimento total. A validação geral de claims durante a autenticação continua a aplicar-se.

Por exemplo, uma transformação do método de autenticação pode guardar uma referência a um target de personificação autorizado em _session:impersonation_target_id. Os inícios de sessão posteriores através desse método podem usar a referência para carregar o target e verificar novamente as permissões. Consulte Personificação para ver o exemplo completo.

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.

Os claims reservados _local:, _internal:, _session: e _impersonate: são excluídos dos pedidos e respostas API. Para trocar um valor reservado selecionado, mapeie-o para um claim comum antes da chamada, ou mapeie posteriormente um claim comum da resposta para um reservado.

Os claims protegidos, como sid e auth_time, são descartados das respostas da API. Os restantes claims da resposta são processados de acordo com a ação configurada.

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.

Carregar os claims da resposta da API em claims locais

Defina o Target opcional de External claims API para utilizar os claims da resposta em verificações ou transformações seguintes. Com Target definido como target, um claim com o nome sub na resposta da API passa a _local:target:sub e role passa a _local:target:role. A API devolve nomes de claims normais; o FoxIDs adiciona o prefixo local depois de filtrar e validar a resposta. O nome completo do claim local deve respeitar o limite de 100 caracteres. Deixe Target vazio para adicionar ou substituir os claims da resposta diretamente na coleção de claims atual.

Várias chamadas API e pesquisas de utilizadores internos podem preencher o mesmo target. Add claim adiciona os valores devolvidos. Replace claim substitui os tipos de claim devolvidos sob esse target e mantém os restantes. Uma resposta vazia deixa os claims existentes do target inalterados.

Os claims locais do target estão disponíveis no conjunto de transformações atual. Mapeie um valor como _local:target:sub para _internal:selected_user_id para o utilizar em conjuntos posteriores.

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. Defina opcionalmente Target para carregar os claims da resposta em claims locais
9. 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 é executado num método de autenticação utilizado como elemento MFA. Compara o claim email devolvido pelo método com _local:mfa:email do utilizador Login. Se os dois valores de e-mail forem iguais e corresponderem a uma expressão regular, é adicionado o claim amr com o nome do método de autenticação como valor (esse nome é configurado como valor de amr).

O fluxo MFA de Login utiliza o claim amr adicionado para validar que o elemento MFA foi concluído com sucesso. O claim email devolvido e os restantes claims do método de autenticação não são combinados com os claims do método de autenticação Login.

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

Personificação

Utilize a transformação Impersonation num método de autenticação para emitir claims para outro utilizador, mantendo o utilizador autenticado original como ator. As sessões têm de estar ativadas no método de autenticação; estão ativadas por predefinição.

Carregue o target com Query internal user, uma API de claims externa ou ambos, definindo Target para um nome como target. Verifique a permissão do utilizador autenticado e os claims necessários do target antes de o selecionar com uma transformação Impersonation. Target é obrigatório e tem o valor predefinido target no Control Client. Um parâmetro de pedido da aplicação seleciona um target; não concede permissão para personificar.

Guarde uma referência ao target selecionado num claim de sessão para repetir a pesquisa nos inícios de sessão posteriores das aplicações. A referência pode ser um ID de utilizador interno ou um ID de perfil externo e não tem de corresponder ao sub emitido do target. O exemplo de utilizador interno abaixo usa impersonation_target_id para o parâmetro de pedido e para o claim de sessão; estes nomes são exemplos a adaptar ao seu fluxo.

O target selecionado tem de conter exatamente um sub distinto e não vazio. Caso contrário, a transformação continua sem selecionar esse target. A pesquisa de um utilizador interno desativado não devolve claims. Utilize uma tarefa de erro condicional se a sua política exigir a rejeição do início de sessão quando não for possível selecionar um target.

A transformação prepara claims _impersonate: para conclusão após transformações de segundo nível bem-sucedidas. Por exemplo, _local:target:sub passa a _impersonate:sub e _local:target:_local:internal_user_id passa a _impersonate:_local:internal_user_id. Também pode prepará-los com transformações normais. Permanecem disponíveis entre os conjuntos de transformações do método de autenticação e através de Extended UI.

Na conclusão, o FoxIDs substitui os claims de identidade normais do utilizador pelos claims normais do target, mantém o contexto de autenticação verificado e adiciona um claim act cujo sub identifica o utilizador autenticado original. O subject do ator é o sub do utilizador no FoxIDs antes de a personificação substituir os seus claims. As transformações da aplicação recebem esta identidade efetiva. Os claims auxiliares reservados não são emitidos para as aplicações.

Contas de destino internas

Quando existe _impersonate:_local:internal_user_id, o FoxIDs verifica se o utilizador interno existe e está ativado, incluindo a política Access Structure aplicável, e associa a conta de destino à sessão e aos grants juntamente com a conta original. Se o utilizador interno de destino for inválido, não existir ou estiver desativado, não é efetuada qualquer personificação.

Desativar ou eliminar qualquer uma das contas associadas revoga a sessão ativa e os grants de tokens de atualização. A revogação de acesso em Access Structure e as verificações de associações limitadas no tempo também se aplicam ao target associado. Para um target fornecido apenas por uma API, sem associação a uma conta interna, a API e as transformações configuradas determinam a sua disponibilidade em cada início de sessão.

Exemplo: personificar um utilizador interno

Este exemplo permite a um colaborador com o valor allow_impersonation no claim role selecionar um utilizador interno e continuar a personificá-lo nos inícios de sessão posteriores das aplicações. Um início de sessão sem target selecionado prossegue como o utilizador original.

O diagrama segue as oito transformações configuradas abaixo. A referência de destino é mantida entre inícios de sessão; os claims do destino e as permissões do colaborador são verificados novamente em cada início de sessão.

Configure impersonation_target_id em Allowed request parameters de cada registo de aplicação que o envia. A aplicação fornece um ID de utilizador interno como valor do parâmetro, que o FoxIDs disponibiliza como _local:params:impersonation_target_id. Consulte Parâmetros de pedido de aplicações. Garanta que os claims do colaborador contêm role=allow_impersonation.

Adicione as oito entradas seguintes, por ordem, a Second-level claim transforms do método de autenticação Login.

1. Map: restaurar a referência de target guardada. Utilize Replace claim, defina Select claim como _session:impersonation_target_id e New claim como _local:impersonation_target_id.

2. Map: aplicar um target da aplicação. Utilize Replace claim, defina Select claim como _local:params:impersonation_target_id e New claim como _local:impersonation_target_id. Um parâmetro fornecido substitui a seleção guardada. Na sua ausência, mantém-se o valor do passo 1.

3. Match claim and value: verificar a função do colaborador. Utilize Replace claim, defina Select claim como role, Match value como allow_impersonation, New claim como _local:impersonation_check_passed e New value como true.

4. Match claim: permitir o início de sessão sem target. Utilize Replace claim, if not match, defina Select claim como _local:impersonation_target_id, New claim como _local:impersonation_check_passed e New value como true.

O claim de verificação local significa que o início de sessão pode continuar: o colaborador tem a função necessária ou não foi selecionado nenhum target. A função é verificada antes de o target substituir os claims do utilizador original.

5. Match claim and return error: rejeitar uma seleção não autorizada. Utilize If not match e selecione _local:impersonation_check_passed. Defina Error como access_denied e Error message como You are not allowed to impersonate another user.

6. Query internal user: carregar o target. Utilize Replace claim, defina Lookup claim como _local:impersonation_target_id, Lookup claim on internal user como sub, Claims from internal user como * e Target como target. A pesquisa corresponde ao ID de utilizador interno e carrega os seus claims, incluindo claims Access Structure encaminhados e claims auxiliares locais, sob _local:target:. Por exemplo, fornece _local:target:sub e _local:target:_local:internal_user_id.

7. Impersonation: selecionar o target carregado. Utilize Replace claim e defina Target como target.

8. Map: conservar o target para inícios de sessão posteriores. Utilize Replace claim, defina Select claim como _local:target:_local:internal_user_id e New claim como _session:impersonation_target_id. Isto guarda o ID estável do utilizador carregado como referência para o próximo início de sessão.

Se a sua política restringir os utilizadores que podem ser personificados, adicione verificações do target entre os passos 6 e 7. Por exemplo, verifique _local:target:role ou o claim auxiliar Access Structure _local:target:_local:access_node.

Se a pesquisa não fornecer nenhum target, estes oito passos terminam sem personificação e mantêm qualquer referência de target anteriormente guardada. Adicione uma tarefa de erro condicional após a pesquisa se um target indisponível tiver de provocar a rejeição do início de sessão, ou remova explicitamente o claim de sessão se a seleção guardada tiver de ser apagada.

Continuar e alterar a personificação

Cada início de sessão de uma aplicação executa novamente as transformações do método de autenticação. No exemplo anterior, estas leem a referência de _session:impersonation_target_id quando não existe _local:params:impersonation_target_id, carregam os claims atuais do target e repetem as verificações de permissões antes de selecionar a personificação. A referência guardada continua associada ao utilizador autenticado original e ao mesmo método de autenticação.

Para selecionar outro target, forneça uma nova referência no parâmetro de pedido e substitua o claim de sessão guardado depois de o novo target passar as verificações. Para terminar a personificação, apague a referência guardada e conclua as transformações sem um target de personificação válido.

Uma conclusão bem-sucedida com o mesmo target mantém o respetivo sid. Selecionar outro target, iniciar uma personificação ou concluir sem um target válido cria um novo sid e revoga a sessão ativa anterior e os grants de tokens de atualização.

UserInfo e a utilização de grants rejeitam uma sessão ativa revogada. As aplicações e API que validam tokens localmente devem continuar a aplicar as suas próprias regras de sessão e de duração dos tokens. O single logout SAML utiliza os valores registados na emissão para cada aplicação.

As sessões ativas e os grants de tokens de atualização mostram o subject personificado e o ator original no Control Client e na Control API. Os eventos de auditoria de início de sessão incluem o ator. Eventos de auditoria de personificação separados registam o início, a alteração e a paragem, incluindo os ID de sessão anteriores e atuais.

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