Referência de reivindicações de token para agentes

Agentes utilizam reivindicações especializadas de tokens para identificar diferentes tipos de entidades e seus relacionamentos durante os fluxos de autenticação e autorização. Essas reivindicações permitem atribuição adequada, avaliação de apólices e trilhas de auditoria para operações de agentes. Este artigo descreve as reivindicações de tokens para aplicações agentes, detalhando como os tokens identificam as entidades agentes e seus papéis nos fluxos de autenticação.

Espera-se que os clientes que usam identidades de agente tratem os tokens de acesso emitidos a eles para usar em servidores de recursos como opacos e não tente analisá-los. No entanto, os servidores de recursos que recebem tokens de acesso emitidos aos agentes precisam analisar os tokens para validá-los e extrair declarações para fins de autorização.

Tipos de reivindicação de token central

Tokens emitidos para identidades usadas para acesso a recursos incluem alegações que normalmente se esperaria ver em tokens de acesso emitidos pela Microsoft Entra. Para mais informações, veja referência à reivindicação do token de acesso. O exemplo a seguir mostra um token de acesso de exemplo emitido a um agente agindo de forma autônoma.

{
  "aud": "f2510d34-8dca-4ab8-a0bc-aaec4d3a3e36",
  "iss": "https://sts.windows.net/00000001-0000-0ff1-ce00-000000000000/",
  "iat": 1753392285,
  "nbf": 1753392285,
  "exp": 1753421385,
  "aio": "Y2JgYGhn1nzmErKqi0vc4Fr6H22/C5/4FP+xZbZYpik8nRkp+gEA",
  "appid": "aaaaaaaa-1111-2222-3333-444444444444",
  "appidacr": "2",
  "idp": "https://sts.windows.net/00000001-0000-0ff1-ce00-000000000000/",
  "idtyp": "app",
  "oid": "bbbbbbbb-1111-2222-3333-444444444444",
  "rh": "1.AAAAAQAAAAAA8Q_OAAAAAAAAADQNUfLKjbhKoLyq7E06PjYAAAAAAA.",
  "sub": "cccccccc-1111-2222-3333-444444444444",
  "tid": "00000001-0000-0ff1-ce00-000000000000",
  "uti": "m5RaaRnoFUyp2TbSCAAAAA",
  "ver": "1.0",
  "xms_act_fct": "3 9 11",
  "xms_ftd": "Z5DrW4HFOkR_Lz0M5qETa260d2-fO6seMZJ_tOwRNuc",
  "xms_idrel": "7 10",
  "xms_sub_fct": "9 3 11",
  "xms_tnt_fct": "3 9",
  "xms_par_app_azp": "30cf4c22-9985-4ef7-8756-91cc888176bd"
}

Em tokens v2, você vê azp em vez de appid. Ambos se referem ao ID da aplicação da identidade do agente.

Você notaria que o token inclui algumas reivindicações que não eram vistas anteriormente em tokens de acesso emitidos para aplicações. As seguintes reivindicações opcionais também são suportadas para identificar que os tokens são para identidades de agentes. Eles também fornecem mais contexto em que a identidade do agente está atuando.

• xms_tnt_fct
• xms_sub_fct
• xms_act_fct
• xms_par_app_azp

Nome da declaração	Description
tid	ID de inquilino do cliente onde a identidade do agente está registrada. É o inquilino onde o token é válido.
sub	Sujeito (o usuário, principal do serviço ou identidade do agente sendo autenticada)
oid	ID do objeto do sujeito. ID de objeto de usuário para cenários de delegação de usuários. OID do principal do serviço com ID de agente para cenários exclusivos de aplicativos. OID de usuário agente para cenários de personificação de usuário.
idtyp	Tipo de entidade que o sujeito é. Os valores são user, app.
tid	ID de inquilino do cliente onde a identidade do agente está registrada.
xms_idrel	Relação entre o sujeito e o inquilino do recurso. Saiba mais.
aud	Audiência (a API que o agente está tentando acessar)
azp ou appid	Parte autorizada / ator. O ID da aplicação da identidade do agente. Permite a atribuição adequada de clientes nos logs de auditoria.
scp	Escopo. Permissões delegadas para tokens de contexto do usuário. Presente apenas em delegação de usuários e cenários de agente de usuário. Vazio ou / para cenários exclusivos de aplicativos
xms_act_fct	Reivindicação de facetas de ator. Saiba mais.
xms_sub_fct	Reivindicação de facetas do sujeito. Saiba mais .
xms_tnt_fct	Reivindicação de facetas do inquilino. Saiba mais .
xms_par_app_azp	Solicitação principal da parte autorizada. Saiba mais .

xms_idrel

A xms_idrel reivindicação indica a relação de identidade entre a entidade para a qual o token é emitido e o inquilino do recurso.

Aqui estão os possíveis valores para a xms_idrel reivindicação. É uma reivindicação multivalorada, ou seja, pode ter múltiplos valores, separados por espaços. Os valores são representados como inteiros. Os valores válidos são sempre números ímpares começando a partir de 1.

Valor da Reivindicação	Description
1	Usuário membro
3	Usuário membro da MSA
5	Usuário convidado
7	Entidade de serviço
9	Princípio do dispositivo
11	Usuário GDAP
13	Aplicação SPLess
15	Passagem
17	Usuário nativo com identidade e perfil
19	Usuário nativo de identidade
21	Participante da reunião das equipes de identidade nativa
23	Participante da reunião do Teams autenticado por passthrough
25	Usuário nativo de compartilhamento de conteúdo com identidade
27	Membro totalmente sincronizado do MTO
29	Usuário fraco de MTO
31	Usuário DAP
33	Identidade federada gerenciada

xms_tnt_fct, xms_sub_fct e xms_act_fct reivindicações

A xms_tnt_fct reivindicação descreve o inquilino (identificado pela reivindicação tid ). As xms_sub_fct reivindicações e xms_act_fct são usadas para descrever fatos sobre o sujeito (sub) e o ator (azp ou appid) do token, respectivamente. Essas alegações fornecem mais contexto sobre a identidade do agente e as ações que ele está realizando.

Aqui estão os valores relevantes para essas afirmações. Essas reivindicações são multivaloradas, ou seja, podem ter múltiplos valores, separados por espaços. Os valores válidos são sempre números ímpares começando a partir de 1.

Valor da Reivindicação	Description
11	AgentIdentity
13	AgentIDUser

Você deve ignorar quaisquer valores que não sejam relevantes para seu cenário ou lógica de validação. Ignore os valores que não são relevantes para sua candidatura. Não assuma nenhuma ordem de valores nessas afirmações.

xms_par_app_azp

A xms_par_app_azp reivindicação é usada para identificar a aplicação principal da parte autorizada (azp ou appid). É um GUID, quando incluído. Você pode usar a reivindicação para determinar quem é o pai ou mãe

Registre o ID da aplicação principal para fins de auditoria. Os logs de login do ID do Microsoft Entra sempre incluem o ID pai, se disponível, então o servidor de recursos deve fazer o mesmo. Não é recomendado usar o ID do aplicativo principal para decisões de autorização, pois isso resultaria em acesso amplo por muitos agentes.

Exemplos por cenário

A seção a seguir descreve alguns cenários de autenticação e as reivindicações relevantes para cada um deles.

Identidade do agente agindo em nome de um usuário humano

Nesse cenário, a identidade do agente está agindo em nome de um usuário humano. O token de acesso inclui as seguintes reivindicações:

Nome da declaração	Description
tid	ID de inquilino do cliente
idtyp	user (indicando que o sujeito é um usuário)
xms_idrel	1 (indicando um usuário membro; outros também possíveis)
azp / appid	ID da aplicação da identidade do agente
scp	Permissões delegadas concedidas à identidade do agente
oid	ID do objeto do usuário
aud	Audiência de recursos para o token
xms_act_fct	11 (Identidade do Agente)

Identidade do agente agindo de forma autônoma

Nesse cenário, a identidade do agente age usando sua própria identidade. O token de acesso inclui as seguintes reivindicações:

Nome da declaração	Description
tid	ID de inquilino do cliente
idtyp	app (indicando que o assunto é uma aplicação)
xms_idrel	7 (indicando um principal de serviço)
azp / appid	ID da aplicação da identidade do agente
roles	Permissões concedidas à identidade do agente
oid	ID de objeto da identidade do agente
xms_act_fct	11 (Identidade do Agente)
xms_sub_fct	11 (Identidade do Agente)
aud	Audiência de recursos para o token
scp	Vazio ou / (sem mira).

A identidade do agente atua de forma autônoma via usuário agente

Nesse cenário, o agente obtém um token usando o usuário agente associado à sua identidade de agente. O token de acesso inclui as seguintes reivindicações:

Nome da declaração	Description
tid	ID de inquilino do cliente
idtyp	user (indicando que o sujeito é um usuário)
xms_idrel	1 (indicando um usuário membro; outros também possíveis)
azp / appid	ID da aplicação da identidade do agente
scp	Permissões delegadas concedidas à identidade do agente
oid	ID de objeto do usuário agente
xms_act_fct	11 (Identidade do agente)
xms_sub_fct	13 (Usuário agente)
aud	Audiência de recursos para o token