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

Os agentes utilizam reivindicações especializadas de tokens para identificar diferentes tipos de entidades e as suas relações durante os fluxos de autenticação e autorização. Estas reclamações permitem uma atribuição adequada, avaliação de apólices e registos de auditoria para as operações dos agentes. Este artigo descreve as reivindicações de tokens para aplicações agentes, detalhando como os tokens identificam as entidades agente e os seus papéis nos fluxos de autenticação.

Espera-se que os clientes que usem identidades de agente tratem os tokens de acesso que lhes são atribuídos para uso nos servidores de recursos como opacos, e não tentem analisá-los. No entanto, os servidores de recursos que recebem tokens de acesso emitidos a agentes precisam de analisar os tokens para os validar e extrair reivindicações para fins de autorização.

Tipos de reivindicação de tokens centrais

Os tokens emitidos para identidades usadas para acesso a recursos incluem afirmações que normalmente se esperaria ver nos tokens de acesso emitidos pela Microsoft Entra. Para mais informações, consulte a referência à reivindicação do token de acesso. O exemplo seguinte mostra um token de acesso de exemplo emitido a um agente que atua de forma autónoma.

{
  "aud": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "iss": "https://sts.windows.net/00000001-0000-0ff1-ce00-000000000000/",
  "iat": 1753392285,
  "nbf": 1753392285,
  "exp": 1753421385,
  "aio": "Y2JgYGhn1nzmErKqi0vc4Fr6H22/C5/4FP+xZbZYpik8nRkp+gEA",
  "appid": "11112222-bbbb-3333-cccc-4444dddd5555",
  "appidacr": "2",
  "idp": "https://sts.windows.net/00000001-0000-0ff1-ce00-000000000000/",
  "idtyp": "app",
  "oid": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "rh": "1.AAAAAQAAAAAA8Q_OAAAAAAAAADQNUfLKjbhKoLyq7E06PjYAAAAAAA.",
  "sub": "bbbbbbbb-1111-2222-3333-cccccccccccc",
  "tid": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "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"
}

Nos tokens v2, vês azp em vez de appid. Ambas referem-se ao ID da aplicação da identidade do agente.

Notaria que o token inclui algumas reivindicações que não eram vistas anteriormente nos 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. Também fornecem mais contexto em que a identidade do agente está a atuar.

• xms_tnt_fct
• xms_sub_fct
• xms_act_fct
• xms_par_app_azp

Valores das reivindicações IDTYP por cenário

A idtyp reivindicação identifica o tipo de entidade que o sujeito do token representa. O valor depende de qual fluxo de agente emitido o token:

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, o que significa que 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 a partir de 1.

xms_tnt_fct, xms_sub_fct e xms_act_fct reclamações

A xms_tnt_fct reivindicação descreve o inquilino (identificado pela reivindicação tid ). As reivindicações xms_sub_fct e xms_act_fct são usadas para descrever factos sobre o sujeito (sub) e o ator (azp ou appid) do token, respetivamente. Estas afirmações fornecem mais contexto sobre a identidade do agente e as ações que este está a realizar.

Aqui estão os valores relevantes para estas afirmações. Estas reivindicações são multivaloradas, o que significa que podem ter múltiplos valores, separados por espaços. Os valores válidos são sempre números ímpares a partir de 1.

Deves ignorar quaisquer valores que não sejam relevantes para o teu cenário ou lógica de validação. Ignora os valores que não são relevantes para a tua candidatura. Não assumas qualquer ordem de valores nestas afirmações.

xms_par_app_azp

A xms_par_app_azp reivindicação é usada para identificar a candidatura principal da parte autorizada (azp ou appid). É um GUID, quando incluído. Pode usar a reclamação para determinar o progenitor

Registe o ID da aplicação principal para efeitos de auditoria. Os registos de início de sessão do Microsoft Entra ID incluem sempre o ID do pai, se disponível, por isso o servidor de recursos deve fazer o mesmo. Não é recomendado usar o ID da aplicação principal para decisões de autorização, pois isso resultaria em acesso generalizado por muitos agentes.

Exemplos de cenários

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

Identidade do agente a agir em nome de um utilizador humano

Neste cenário, a identidade do agente atua em nome de um utilizador humano. O token de acesso inclui as seguintes reivindicações:

Identidade do agente a agir de forma autónoma

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

A identidade do agente atua de forma autónoma através da conta de utilizador do agente

Neste cenário, o agente obtém um token usando a conta de utilizador do agente associada à sua identidade de agente. O token de acesso inclui as seguintes reivindicações: