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

Os tokens de acesso são JSON web tokens (JWT). Os JWTs contêm as seguintes peças:

• Cabeçalho - Fornece informações sobre como validar o token, incluindo informações sobre o tipo de token e seu método de assinatura.
• Carga útil - Contém todos os dados importantes sobre o usuário ou aplicativo que está tentando chamar o serviço.
• Assinatura - É a matéria-prima utilizada para validar o token.

Cada peça é separada por um ponto (.) e codificada separadamente a Base 64.

As reivindicações só estão presentes se existir um valor para preenchê-las. Um aplicativo não deve depender da presença de uma reivindicação. Os exemplos incluem pwd_exp (nem todo locatário requer senhas para expirar) e family_name (os fluxos de credenciais do cliente estão em nome de 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 usa algumas declarações para ajudar a proteger tokens para reutilização. A descrição destas Opaque alegações não se destina a consumo público. Essas declarações podem ou não aparecer em um token, e novas podem ser adicionadas sem aviso prévio.

Declarações de cabeçalho

Afirmação	Formato	Description
typ	String - 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 para a chave pública usada para validar a assinatura do token. Emitido em 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 apenas em tokens de acesso v1.0 para fins de compatibilidade.

Declarações de carga útil

Afirmação	Formato	Description	Considerações sobre autorização
acrs	Matriz JSON de cadeias de caracteres	Indica os IDs de contexto de autenticação das operações que o portador está qualificado para executar. Os IDs de contexto de autenticação podem ser usados para disparar uma demanda de autenticação step-up de dentro de seu aplicativo e serviços. Muitas vezes usado junto com a xms_cc reivindicação.
aud	String, um URI ou GUID de ID de Aplicativo	Identifica o público-alvo do token. Em tokens v2.0, esse valor é sempre o ID do cliente da API. Em tokens v1.0, pode ser o 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, rejeitar o token se o valor não corresponder ao público-alvo.
iss	String, um URI de serviço de token de segurança (STS)	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 ver declaração), o URI terminará em /v2.0. O GUID que indica que o usuário é um usuário consumidor de uma conta da Microsoft é 9188040d-6c67-4c5b-b112-36a304b66dad.	O aplicativo pode usar a parte GUID da declaração para restringir o conjunto de locatários que podem entrar no aplicativo, se aplicável.
idp	String, geralmente um URI STS	Regista o fornecedor de identidade que autenticou o requerente do token. Esse valor é idêntico ao valor da declaração do Emissor, a menos que a conta do usuário não esteja no mesmo locatário que o emissor, como convidados. Use o valor de iss se a reivindicação não estiver presente. Para contas pessoais que estão sendo usadas em um contexto organizacional (por exemplo, uma conta pessoal convidada para um locatário do Microsoft Entra), a idp declaração pode ser 'live.com' ou um URI STS contendo o locatário 9188040d-6c67-4c5b-b112-36a304b66dadda conta da Microsoft.
iat	int, um carimbo de data/hora Unix	Especifica quando ocorreu a autenticação para esse 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 período. A rejeição pode ocorrer por uma alteração necessária na autenticação ou quando um token é revogado.
aio	Corda opaca	Uma declaração interna usada pelo Microsoft Entra ID para registrar dados para reutilização de token. Os recursos não devem usar essa afirmação.
acr	String, a 0 ou 1, presente apenas em tokens v1.0	Um valor de para a declaração "Classe de contexto de autenticação" indica que a autenticação do 0 usuário final não atendeu aos requisitos da ISO/IEC 29115.
amr	Matriz JSON de cadeias de caracteres, presente apenas em tokens v1.0	Identifica o método de autenticação do assunto do token.
appid	String, um GUID, presente apenas em tokens v1.0	O ID do aplicativo do cliente usando o token. O aplicativo pode agir como ele mesmo ou em nome de um usuário. A ID do aplicativo normalmente representa um objeto de aplicativo, mas também pode representar um objeto principal de serviço na ID do Microsoft Entra.	appid podem ser utilizados em decisões de autorização.
azp	String, um GUID, presente apenas em tokens v2.0	Um substituto para appid. O ID do aplicativo do cliente usando o token. O aplicativo pode agir como ele mesmo ou em nome de um usuário. A ID do aplicativo normalmente representa um objeto de aplicativo, mas também pode representar um objeto principal de serviço na ID do Microsoft Entra.	azp podem ser utilizados em decisões de autorização.
appidacr	String, a 0, 1ou 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ê usa um certificado de cliente para autenticação, o valor é 2.
azpacr	String, a 0, 1ou 2, presente apenas em tokens v2.0	Um substituto 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ê usa um certificado de cliente para autenticação, o valor é 2.
preferred_username	String, presente apenas em tokens v2.0.	O nome de usuário principal que representa o usuário. O valor pode ser um endereço de e-mail, número de telefone ou um nome de usuário genérico sem um formato especificado. Use 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, use o profile escopo.	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 o assunto do token. O valor pode variar, é mutável e é apenas para fins de exibição. Para receber essa declaração, use o profile escopo.	Não use esse valor para tomar decisões de autorização.
scp	String, uma lista de escopos separados por espaço	O conjunto de escopos expostos pelo aplicativo para o qual o aplicativo cliente solicitou (e recebeu) consentimento. Incluído apenas para tokens de usuário.	O aplicativo deve verificar se esses escopos são válidos expostos pelo aplicativo e tomar decisões de autorização com base no 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 usuário solicitante recebeu permissão para chamar. O fluxo de credenciais do cliente usa esse conjunto de permissões no lugar de escopos de usuário para tokens de aplicativo. Para tokens de usuário, esse conjunto de valores contém as funções atribuídas do usuário no aplicativo de destino.	Esses valores podem ser usados para gerenciar o acesso, como impor autorização para acessar um recurso.
wids	Matriz de GUIDs RoleTemplateID	Indica as funções de todo o locatário atribuídas a esse usuário, na seção de funções presentes nas funções internas do Microsoft Entra. A groupMembershipClaims propriedade do manifesto do aplicativo configura essa declaração por aplicativo. Defina a reivindicação como All ou DirectoryRole.	Esses valores podem ser usados para gerenciar o acesso, como impor autorização para acessar um recurso.
groups	Matriz JSON de GUIDs	Fornece IDs de objeto que representam as associações de grupo do assunto. A groupMembershipClaims propriedade do manifesto do aplicativo configura a declaração de grupos por aplicativo. Um valor de null exclui todos os grupos, um valor de inclui funções de SecurityGroup diretório e associações ao Grupo de Segurança do Ative Directory e um valor de inclui Grupos de Segurança e Listas de Distribuição do All Microsoft 365. Para outros fluxos, se o número de grupos em que o usuário está for superior a 150 para SAML e 200 para JWT, o Microsoft Entra ID adicionará uma declaração de excesso às fontes de declaração. As origens da afirmação indicam que o ponto final do Microsoft Graph contém a lista de grupos do utilizador.	Esses valores podem ser usados para gerenciar o acesso, como impor autorização para acessar um recurso.
hasgroups	Boolean	Se presente, sempre true, indica se o usuário está em pelo menos um grupo. Indica que o cliente deve usar a API do Microsoft Graph para determinar os grupos (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects) do usuário.
groups:src1	Objeto JSON	Inclui um link para a lista completa de grupos para o usuário quando as solicitações de token são muito grandes para o token. Para JWTs como uma reivindicação distribuída, para SAML como uma nova reivindicação no lugar da groups reivindicação. Exemplo de valor 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. Este valor é imutável, não reatribua nem reutilize. O assunto é um identificador de pares que é exclusivo para um ID de aplicativo específico. 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 de assunto. O uso dos dois valores diferentes depende da arquitetura e dos requisitos de privacidade. Veja também a oid reivindicação, 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, como quando o token é usado para acessar um recurso, e pode ser usado como uma chave em tabelas de banco de dados.
oid	String, um GUID	O identificador imutável para o solicitante, que é a identidade verificada do usuário ou da entidade de serviço. Esse ID identifica exclusivamente o solicitante entre aplicativos. Dois aplicativos diferentes que entram no mesmo usuário recebem o mesmo valor na oid declaração. O oid pode ser usado ao fazer consultas aos serviços online da Microsoft, como o Microsoft Graph. O Microsoft Graph retorna essa ID como a id propriedade de uma determinada conta de usuário. Como o oid permite que vários aplicativos correlacionem entidades de segurança, para receber essa declaração para os usuários use o profile escopo. Se existir um único usuário em vários locatários, o usuário conterá uma ID de objeto diferente em cada locatário. Embora o usuário faça login em cada conta com as mesmas credenciais, as contas são diferentes.	Esse valor pode ser usado para executar verificações de autorização, como quando o token é usado para acessar um recurso, e pode ser usado como uma chave em tabelas de banco de dados.
tid	String, um GUID	Representa o locatário no qual o usuário está entrando. Para contas corporativas e de estudante, o GUID é a ID de locatário imutável da organização na qual o usuário está entrando. Para iniciar sessão no inquilino pessoal da conta Microsoft (serviços como Xbox, Teams for Life ou Outlook), o valor é 9188040d-6c67-4c5b-b112-36a304b66dad. Para receber esta reivindicação, o pedido deve solicitar o profile escopo.	Este valor deve ser considerado em combinação com outras reivindicações nas decisões de autorização.
unique_name	String, presente apenas em tokens v1.0	Fornece um valor legível por humanos que identifica o requerente do token.	Esse valor pode ser diferente dentro de um locatário e usá-lo apenas para fins de exibição.
uti	String	Declaração de identificador de token, equivalente à jti especificação JWT. Identificador exclusivo por token que diferencia maiúsculas de minúsculas.
rh	Corda opaca	Uma declaração interna usada pelo Azure para revalidar tokens. Os recursos não devem usar essa afirmação.
ver	String, ou 1.02.0	Indica a versão do token de acesso.
xms_cc	Matriz JSON de cadeias de caracteres	Indica se o aplicativo cliente que adquiriu o token é capaz de lidar com desafios de declarações. É frequentemente usado juntamente com a reivindicação acrs. Essa declaração é comumente usada em cenários de Acesso Condicional e Avaliação de Acesso Contínuo. O servidor de recursos ou aplicativo de serviço para o qual o token é emitido controla a presença dessa declaração em um token. Um valor de no token de acesso é a maneira autoritativa de identificar que um aplicativo cliente é capaz de lidar com um desafio de cp1 declarações. Para obter mais informações, consulte Desafios de declarações, solicitações de declarações e recursos do cliente.

Nota

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

Reivindicação de excesso de idade de grupos

O Microsoft Entra ID limita o número de IDs de objeto que inclui nos grupos que afirmam permanecer dentro do limite de tamanho do cabeçalho HTTP. Se um usuário for membro de mais grupos do que o limite de ultrapassagem (150 para tokens SAML, 200 para tokens JWT), o Microsoft Entra ID não emitirá a declaração de grupos no token. Em vez disso, ele inclui uma declaração de excesso no token que indica ao aplicativo para consultar a API do Microsoft Graph para 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 aplicativos para ajudar a testar cenários de excesso.

Nota

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

v1.0 reivindicações básicas

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 as solicita usando declarações opcionais.

Afirmação	Formato	Description
ipaddr	String	O endereço IP a partir do qual o usuário se autenticou.
onprem_sid	String, no formato SID	Nos casos em que o usuário tem uma autenticação local, essa declaração fornece seu SID. Use esta 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	Um URL onde os utilizadores podem repor a palavra-passe.
in_corp	boolean	Sinaliza se o cliente está entrando na rede corporativa.
nickname	String	Outro nome para o usuário, separado do nome ou sobrenome.
family_name	String	Fornece o sobrenome, sobrenome ou nome de família do usuário, conforme definido no objeto de usuário.
given_name	String	Fornece o nome próprio ou próprio 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, endereço de e-mail ou cadeia de caracteres não formatada. Use apenas para fins de exibição e fornecendo dicas de nome de usuário em cenários de reautenticação.

Reivindicação de RAM

As identidades podem ser autenticadas de diferentes maneiras, o que pode ser relevante para o aplicativo. A amr declaração é 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	Description
pwd	Autenticação de senha, a senha da Microsoft de um usuário ou um segredo de cliente de um aplicativo.
rsa	A autenticação foi baseada 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	Senha única usando um e-mail ou uma mensagem de texto.
fed	Indica o uso de uma asserçã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 essa declaração está presente.
ngcmfa	Equivalente a mfa, usado para provisionamento de determinados tipos avançados de credenciais.
wiaormfa	O usuário usou o Windows ou uma credencial MFA para autenticar.
none	Indica que não há autenticação concluída.

Próximos passos

• Saiba mais sobre os tokens de acesso usados no Microsoft Entra ID.