Referência de declarações de token de acesso

Os tokens de acesso são JWT (tokens de Web JSON). As JWTs contêm os seguintes parâmetros:

• Cabeçalho: fornece informações sobre como validar o token, incluindo informações sobre o tipo de token e seu método de assinatura.
• Payload – contém todos os dados importantes sobre o usuário ou o aplicativo que está tentando chamar o serviço.
• Assinatura – é a matéria-prima usada para validar o token.

Cada peça é separada por um período (.) e separadamente codificada em Base 64.

As declarações estão presentes somente se existe um valor para preenchê-lo. Um aplicativo não deve usar uma dependência em uma declaração que esteja presente. Os exemplos incluem pwd_exp (nem todo locatário exige a expiração das senhas) e family_name (a credencial do cliente flui são em nome dos aplicativos, que não têm nomes). O token de acesso sempre conterá declarações suficientes para avaliação de acesso.

A plataforma de identidade da Microsoft utiliza algumas declarações para ajudar a proteger os tokens para reutilização. A descrição de Opaque marca essas reivindicações como não destinadas ao consumo público. Essas declarações podem ou não aparecer em um token, e novas declarações podem ser adicionadas sem aviso prévio.

Declarações de cabeçalho

Declaração	Formatar	Descrição
typ	Cadeia de caracteres – sempre JWT	Indica que o token é um JWT.
alg	String	Indica o algoritmo usado para assinar o token, por exemplo, RS256.
kid	String	Especifica a impressão digital da chave pública usada para validar a assinatura do token. Emitido nos tokens de acesso v1.0 e v2.0.
x5t	String	Funciona da mesma forma (em uso e valor) que kid. x5t e é uma declaração herdada emitida somente em tokens de acesso da v1.0 para fins de compatibilidade.

Declarações de conteúdo

Declaração	Formatar	Descrição	Considerações sobre autorização
acrs	Matriz de cadeias de caracteres JSON	Indica as IDs de Contexto de Autenticação das operações que o portador está qualificado para executar. As IDs de Contexto de Autenticação podem ser usadas para disparar uma demanda por autenticação passo a passo de dentro de seu aplicativo e serviços. Geralmente usado junto com a declaração xms_cc.
aud	Cadeia de caracteres, um URI da ID do aplicativo ou GUID	Especifica o público-alvo destinado do token. Em tokens v2.0, esse valor é sempre a ID do cliente da API. Em tokens v1.0, pode ser uma ID do cliente ou o URI do recurso usado na solicitação. O valor pode depender de como o cliente solicitou o token.	Esse valor deve ser validado, rejeite o token se o valor não corresponder ao público-alvo pretendido.
iss	Cadeia de caracteres, um URI de STS (serviço de token de segurança)	Identifica o STS que constrói e retorna o token e o locatário do Microsoft Entra do usuário autenticado. Se o token emitido for um token v2.0 (consulte a declaração ver), o URI será finalizado em /v2.0. O GUID que indica que o usuário é um consumidor da conta da Microsoft é 9188040d-6c67-4c5b-b112-36a304b66dad.	O aplicativo pode usar a parte do GUID da declaração para restringir o conjunto de locatários que podem entrar no aplicativo, se aplicável.
idp	Cadeia de caracteres, normalmente um URI de STS	Registra o provedor de identidade que autenticou a entidade do token. Esse valor é idêntico ao valor da declaração do Emissor, a menos que a conta de usuário não esteja no mesmo locatário que o emissor – convidados, por exemplo. Utiliza o valor iss se a reivindicação não estiver presente. Para contas pessoais usadas em um contexto organizacional (por exemplo, uma conta pessoal convidada para um locatário do Microsoft Entra), a declaração idp pode ser "live.com"ou um URI STS contendo o locatário 9188040d-6c67-4c5b-b112-36a304b66dad da conta da Microsoft.
iat	int, um carimbo de data/hora Unix	Especifica quando ocorreu a autenticação desse token.
nbf	int, um carimbo de data/hora Unix	Especifica o tempo após o qual o JWT pode ser processado.
exp	int, um carimbo de data/hora Unix	Especifica o tempo de expiração antes do qual o JWT pode ser aceito para processamento. Um recurso também pode rejeitar o token antes desse horário também. A rejeição pode ocorrer em uma alteração necessária na autenticação ou quando um token é revogado.
aio	Cadeia de caracteres opaca	Uma declaração interna usada pelo Microsoft Entra ID para registrar os dados para reutilização de token. Os recursos não devem usar essa declaração.
acr	Cadeia de caracteres, um 0 ou 1, presente apenas em tokens v1.0	Um valor de 0 para a declaração "Classe de contexto de autenticação" indica que a autenticação do usuário final não atendia aos requisitos do ISO/IEC 29115.
amr	Matriz JSON de cadeias de caracteres, presente somente em tokens v1.0	Identifica o método de autenticação do assunto do token.
appid	Cadeia de caracteres, um GUID, presente apenas em tokens v1.0	A ID do aplicativo do cliente que usa o token. O aplicativo pode agir como ele próprio ou em nome de um usuário. A ID do aplicativo normalmente representa um objeto de aplicativo, mas também pode representar um objeto de entidade de serviço no Microsoft Entra ID.	appid pode ser usado em decisões de autorização.
azp	Cadeia de caracteres, um GUID, presente apenas em tokens v2.0	Uma substituição para appid. A ID do aplicativo do cliente que usa o token. O aplicativo pode agir como ele próprio ou em nome de um usuário. A ID do aplicativo normalmente representa um objeto de aplicativo, mas também pode representar um objeto de entidade de serviço no Microsoft Entra ID.	azp pode ser usado em decisões de autorização.
appidacr	Cadeia de caracteres, um 0, 1 ou 2, presente apenas em tokens v1.0	Indica o método de autenticação do cliente. Para um cliente público, o valor é 0. Quando você usa a ID do cliente e o segredo do cliente, o valor é 1. Quando você utiliza um certificado do cliente para autenticação, o valor é 2.
azpacr	Cadeia de caracteres, um 0, 1 ou 2, presente apenas em tokens v2.0	Uma substituição para appidacr. Indica o método de autenticação do cliente. Para um cliente público, o valor é 0. Quando você usa a ID do cliente e o segredo do cliente, o valor é 1. Quando você utiliza um certificado do cliente para autenticação, o valor é 2.
preferred_username	Cadeia de caracteres, presente apenas em tokens v2.0.	O nome de usuário principal que representa o usuário. O valor poderia ser um endereço de email, um número de telefone ou um nome de usuário genérico sem um formato especificado. Usa o valor para dicas de nome de usuário e na interface do usuário legível por humanos como um nome de usuário. Para receber essa declaração, utilize o escopo profile.	Como esse valor é mutável, não o use para tomar decisões de autorização.
name	String	Fornece um valor legível por humanos que identifica a entidade do token. O valor pode variar, é mutável e serve somente para fins de exibição. Para receber essa declaração, utilize o escopo profile.	Não usar esse valor para tomar decisões de autorização.
scp	Cadeia de caracteres, uma lista de escopos separados por espaços	O conjunto de escopos expostos pelo aplicativo para o qual o aplicativo cliente solicitou (e recebeu) o consentimento. Incluído apenas para tokens de usuário.	O aplicativo deve verificar se os escopos são escopos válidos expostos pelo aplicativo e tomar decisões de autorização de acordo com o valor desses escopos.
roles	Matriz de cadeias de caracteres, uma lista de permissões	O conjunto de permissões expostas pelo aplicativo que o aplicativo ou o usuário solicitante recebeu permissão para chamar. O fluxo de credenciais do cliente utiliza esse conjunto de permissões no lugar dos escopos de usuário para os tokens de aplicativo. Para tokens de usuário, esse conjunto de valores contém as funções atribuídas ao usuário no aplicativo de destino.	Esses valores podem ser usados para gerenciar o acesso, como impor a autorização para acessar um recurso.
wids	Matriz de GUIDs RoleTemplateID	Denota as funções de todo o locatário atribuídas a esse usuário, da seção de funções presentes em funções internas do Microsoft Entra. A groupMembershipClaimspropriedade do manifesto do aplicativo configura essa declaração por aplicativo. Defina a declaração como All ou DirectoryRole.	Esses valores podem ser usados para gerenciar o acesso, como impor a autorização para acessar um recurso.
groups	Matriz JSON de GUIDs	Fornece IDs do objeto que representam as associações do grupo do assunto. A propriedade groupMembershipClaims do manifesto do aplicativo configura a declaração de grupos por aplicativo. Um valor de null exclui todos os grupos, um valor de SecurityGroup inclui funções de diretório e associações a Grupos de Segurança do Active Directory e um valor de All inclui grupos de segurança e listas de distribuição do Microsoft 365. Para outros fluxos, se o número de grupos em que o utilizador se encontra for superior a 150 para SAML e 200 para JWT, o Microsoft Entra ID adiciona uma declaração de excesso às fontes de declaração. As origens de declaração apontam para o ponto de extremidade do Microsoft Graph na lista dos grupos para o usuário.	Esses valores podem ser usados para gerenciar o acesso, como impor a autorização para acessar um recurso.
hasgroups	Booliano	Se houver algum, sempre true, indicará que o usuário pertence a pelo menos um grupo. Indica que o cliente deve usar a API do Microsoft Graph para determinar os grupos do usuário (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects).
groups:src1	Objeto JSON	Inclui um link para a lista completa de grupos do usuário quando as solicitações de token são muito grandes para o token. Para JWTs na forma de declaração distribuída, para SAML como uma nova declaração no lugar da declaração groups. Valor de exemplo de JWT: "groups":"src1" "_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }
sub	String	A entidade de segurança associada ao token. Por exemplo, o usuário de um aplicativo. Esse valor é imutável, não reatribua nem reutilize. O assunto é um identificador emparelhado exclusivo para uma determinada ID de aplicativo. Se um único usuário entrar em dois aplicativos diferentes usando duas IDs de cliente diferentes, esses aplicativos receberão dois valores diferentes para a declaração do assunto. O uso de dois valores diferentes depende da arquitetura e dos requisitos de privacidade. Veja também a declaração oid, que permanece a mesma em todos os aplicativos dentro de um locatário.	Esse valor pode ser usado para executar verificações de autorização, por exemplo, quando o token é usado para acessar um recurso, e pode ser usado como uma chave nas tabelas de banco de dados.
oid	Cadeia de caracteres, um GUID	O identificador imutável para o solicitante, que é a identidade verificada do usuário ou da entidade de serviço. Essa ID identifica exclusivamente o solicitante entre aplicativos. Duas assinaturas diferentes que entram no mesmo usuário recebem o mesmo valor na declaração oid. O oid pode ser usado ao fazer consultas nos serviços online da Microsoft, como o Microsoft Graph. O Microsoft Graph retornará essa ID como a propriedade id para uma determinada conta de usuário. Como o oid permite que vários aplicativos correlacionem as entidades de segurança, para receber essa declaração para os usuários, utilize o escopo profile. Se um usuário único existir em vários locatários, o usuário conterá uma ID de objeto diferente em cada locatário. Mesmo que o usuário faça logon em cada conta com as mesmas credenciais, as contas serão diferentes.	Esse valor pode ser usado para executar verificações de autorização, por exemplo, quando o token é usado para acessar um recurso, e pode ser usado como uma chave nas tabelas de banco de dados.
tid	Cadeia de caracteres, um GUID	Representa o locatário no qual o usuário está se conectando. Para contas corporativas e de estudante, o GUID é a ID de locatário imutável da organização à qual o usuário está se conectando. Para conexões no locatário de conta Microsoft pessoal (serviços como Xbox, Teams for Life ou Outlook), o valor é 9188040d-6c67-4c5b-b112-36a304b66dad. Para receber essa declaração, seu aplicativo precisa solicitar o escopo profile.	Esse valor deve ser considerado em conjunto com outras declarações em decisões de autorização.
unique_name	Cadeia de caracteres, presente apenas em tokens v1.0	Fornece um valor legível que identifica a entidade do token.	Esse valor pode ser diferente dentro de um locatário, e use-o apenas para fins de exibição.
uti	String	Declaração de identificador de token, equivalente a jti na especificação JWT. Identificador exclusivo por token que diferencia maiúsculas de minúsculas.
rh	Cadeia de caracteres opaca	Uma declaração interna usada pelo Azure para revalidar tokens. Os recursos não devem usar essa declaração.
ver	Cadeia de caracteres, 1.0 ou 2.0	Indica a versão do token de acesso.
xms_cc	Matriz de cadeias de caracteres JSON	Indica se o aplicativo cliente que adquiriu o token conseugue lidar com desafios de declarações. Geralmente, ele é usado junto com a declaração acrs. Essa declaração é comumente usada em cenários de Acesso condicional e Avaliação contínua de acesso. O servidor de recursos ou o aplicativo de serviço que o token é emitido para controlar a presença dessa declaração em um token. Um valor de cp1 no token de acesso é a maneira autoritativa de identificar que um aplicativo cliente é capaz de lidar com um desafio de declarações. Para obter mais informações, confira Desafios de declarações, solicitações de declarações e recursos de cliente.

Observação

As declarações roles, groups, scp e wids não são uma lista exaustiva de como um recurso pode autorizar um usuário ou aplicativo, nem uma lista completa de permissões concedidas ao chamador. O recurso de destino pode usar outro método para autorizar o acesso aos recursos protegidos.

Declaração de excedente de grupos

O Microsoft Entra ID limita o número de IDs de objeto que ele inclui na declaração de grupos para permanecer dentro do limite de tamanho do cabeçalho HTTP. Se um usuário for membro de mais grupos do que o limite excedente (150 para tokens SAML, 200 para tokens JWT), o Microsoft Entra ID não emite a declaração de grupos no token. Em vez disso, ele inclui uma declaração excedente no token que indica ao aplicativo para que consulte a API do Microsoft Graph a fim de recuperar a associação de grupo do usuário.

{
    ...
    "_claim_names": {
        "groups": "src1"
    },
    "_claim_sources": {
        "src1": {
            "endpoint": "[Url to get this user's group membership from]"
        }   
    }
    ...
}

Use o BulkCreateGroups.ps1 fornecido na pasta Scripts de Criação de Aplicativo para ajudar a testar cenários excedentes.

Observação

A URL retornada será uma URL do Graph do Azure AD (ou seja, graph.windows.net). Em vez de depender dessa URL, os serviços devem usar a declaração opcional idtyp (que identifica se o token é um aplicativo ou um token de aplicativo+usuário) para construir uma URL do Microsoft Graph para consultar a lista completa de grupos.

Declarações básicas v1.0

Os tokens v1.0 incluem as seguintes declarações, se aplicável, mas não os tokens v2.0 por padrão. Para usar essas declarações para v2.0, o aplicativo solicita-as usando declarações opcionais.

Declaração	Formatar	Descrição
ipaddr	String	O endereço IP por meio do qual o usuário se autenticou.
onprem_sid	Cadeia de caracteres, em formato SID	Nos casos em que o usuário tem uma autenticação local, essa declaração fornece o SID. Use essa declaração para autorização em aplicativos herdados.
pwd_exp	int, um carimbo de data/hora Unix	Indica quando a senha do usuário expira.
pwd_url	String	Uma URL onde os usuários podem redefinir sua senha.
in_corp	booleano	Indica se o cliente está se conectando por meio da rede corporativa.
nickname	String	Um nome adicional para o usuário, separado do nome ou sobrenome.
family_name	String	Fornece o sobrenome ou o nome da família do usuário, conforme definido no objeto de usuário.
given_name	String	Fornece o nome ou nome especificado do usuário, conforme definido no objeto de usuário.
upn	String	O nome de usuário do usuário. Pode ser um número de telefone, um endereço de email ou uma cadeia de caracteres sem formatação. Usar apenas para fins de exibição e fornecer dicas de nome de usuário em cenários de reautenticação.

amr claim

As identidades podem ser autenticadas de várias formas, que podem ser relevantes para o aplicativo. A declaração amr é uma matriz que pode conter vários itens, como ["mfa", "rsa", "pwd"], para uma autenticação que usou uma senha e o aplicativo Authenticator.

Valor	Descrição
pwd	Autenticação de senha, uma senha da Microsoft do usuário ou um segredo do cliente de um aplicativo.
rsa	A autenticação se baseava na prova de uma chave RSA, por exemplo, com o aplicativo Microsoft Authenticator. Esse valor também indica o uso de um JWT autoassinado com um certificado X509 de propriedade do serviço na autenticação.
otp	Uma senha única usando um email ou uma mensagem de texto.
fed	Indica o uso de uma instrução de declaração de autenticação federada (como JWT ou SAML).
wia	Autenticação Integrada do Windows
mfa	Indica o uso da autenticação multifator. Inclui os outros métodos de autenticação quando esta declaração estiver presente.
ngcmfa	Equivalente a mfa, usado para o provisionamento de alguns tipos de credenciais avançadas.
wiaormfa	O usuário utilizou o Windows ou uma credencial MFA para se autenticar.
none	Indica que nenhuma autenticação foi concluída.

Próximas etapas

• Saiba mais sobre os tokens de segurança usados no Microsoft Entra ID.