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

  • Artigo

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. Pode não estar presente em tokens obtidos através do fluxo implícito devido a preocupações com o comprimento do token. 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 apenas associações ao Grupo de Segurança do SecurityGroup Ative Directory e um valor de inclui Grupos de Segurança e Listas de Distribuição do All Microsoft 365.

Consulte o hasgroups pedido para obter detalhes sobre como usar o groups crédito com a subvenção implícita. 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. Usado no lugar da declaração para JWTs em fluxos de concessão implícitos se a reivindicação de grupos completos estendesse o fragmento de URI além dos limites de comprimento de groups URL (atualmente seis ou mais grupos). 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.

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 e apenas 6 se emitido usando o fluxo implícito), 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