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

  • Artigo

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