Tokens de acesso da plataforma de identidade da Microsoft

Os tokens de acesso permitem que os clientes chamem APIs Web protegidas com segurança. Os tokens de acesso são usados por APIs Web para executar autenticação e autorização.

De acordo com a especificação OAuth, os tokens de acesso são cadeias de caracteres opacas sem formato definido. Alguns IDPs (provedores de identidade) usam GUIDs; outros usam blobs criptografados. O formato do token de acesso pode depender de como a API que aceita o token está configurada.

APIs personalizadas registradas por desenvolvedores na plataforma de identidade da Microsoft podem escolher entre dois formatos diferentes de JWTs (JSON Web Tokens) chamados v1.0 e v2.0. APIs desenvolvidas pela Microsoft, como o Microsoft Graph ou APIs no Azure, têm outros formatos de token proprietários. Esses formatos proprietários podem ser tokens criptografados, JWTs ou tokens especiais semelhantes ao JWT que não serão validados.

Os clientes precisam tratar os tokens de acesso como cadeias de caracteres opacas porque o conteúdo do token se destina apenas à API. Para fins de validação e depuração, apenas os desenvolvedores podem decodificar JWTs usando um site como jwt.ms. Os tokens recebidos para uma API da Microsoft podem nem sempre ser um JWT e nem sempre podem ser decodificados.

Para obter informações sobre o conteúdo do token de acesso, os clientes devem usar os dados de resposta do token retornados com o token de acesso para o cliente. Quando o cliente solicita um token de acesso, a plataforma de identidade da Microsoft também retorna alguns metadados sobre o token de acesso para o consumo do aplicativo. Essas informações incluem a data de expiração do token de acesso e os escopos para os quais ele é válido. Esses dados permitem ao aplicativo realizar o cache inteligente dos tokens de acesso sem precisar analisar o token de acesso em si.

Confira as seções a seguir para saber como sua API pode validar e usar as declarações dentro de um token de acesso.

Observação

Toda a documentação nesta página, exceto onde observado, aplica-se apenas a tokens emitidos para APIs que você registrou. Ela não se aplica a tokens emitidos para APIs de propriedade da Microsoft, e esses tokens não podem ser usados para validar como a plataforma de identidade da Microsoft emitirá tokens para uma API registrada.

Formatos de Token

Há duas versões de tokens de acesso disponíveis na plataforma de identidade da Microsoft: v 1.0 e v 2.0. Essas versões determinam as declarações que estão no token e garantem que uma API Web possa controlar o conteúdo do token.

As APIs Web têm uma das seguintes versões selecionadas como padrão durante o registro:

  • v1.0 para aplicativos somente do Azure AD. O exemplo a seguir mostra um token v1.0 (esse exemplo de token não será validado porque as chaves foram giradas antes da publicação, e as informações pessoais foram removidas):

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd
    
  • v2.0 para aplicativos que dão suporte a contas de consumidor. O exemplo a seguir mostra um token v1.0 (esse exemplo de token não será validado porque as chaves foram giradas antes da publicação, e as informações pessoais foram removidas):

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt
    

A versão pode ser definida para aplicativos fornecendo o valor apropriado para a configuração accessTokenAcceptedVersion no manifesto do aplicativo. Os valores de null e 1 resultam em tokens v1.0, e o valor 2 resulta em tokens v2.0.

Propriedade de token

Há duas partes envolvidas na solicitação de token de acesso: o cliente, quem solicita o token, e o recurso (a API Web) que aceita o token. A declaração aud em um token indica o recurso para o qual o token se destina (seu público). Os clientes usam o token, mas não devem entender nem tentar analisá-lo. Os recursos aceitam o token.

A plataforma de identidade da Microsoft permite a emissão de qualquer versão de token por meio de qualquer ponto de extremidade de versão: elas não estão relacionadas. Quando accessTokenAcceptedVersion é configurado como 2, um cliente que chama o ponto de extremidade v1.0 para obter um token para esse recurso recebe um token de acesso v2.0.

Os recursos sempre possuem tokens usando a declaração aud e são os únicos aplicativos que podem mudar os detalhes de token.

Declarações em tokens de acesso

Os JWTs são divididos em três partes:

  • Cabeçalho – fornece informações sobre como validar o token, incluindo informações sobre o tipo de token e como ele foi assinado.
  • 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 parte é separada por um ponto (.) e codificada em Base64 separadamente.

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). As declarações usadas para validação do token de acesso sempre estão presentes.

Algumas declarações são usadas para ajudar o plataforma de identidade da Microsoft a proteger tokens para reutilização. Elas são marcadas como não sendo para consumo público na descrição como Opaque. 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 que foi usado para assinar o token, por exemplo, RS256.
kid String Especifica a impressão digital da chave pública que pode ser 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
aud Cadeia de caracteres, um URI da ID do aplicativo ou GUID Especifica o público-alvo destinado do token. A API deve validar esse valor e rejeitar o token, caso o valor não seja correspondente. 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.
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 Azure AD no qual o usuário foi 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. Se a declaração não estiver presente, o valor de iss poderá ser usado. Para as contas pessoais usadas em um contexto organizacional (por exemplo, uma conta pessoal convidada para um locatário do Azure AD), a declaração idppode ser 'live.com' ou um URI de STS que contém o locatário da conta Microsoft9188040d-6c67-4c5b-b112-36a304b66dad.
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 horário antes do qual o JWT não deve ser aceito para processamento.
exp int, um carimbo de data/hora Unix Especifica o horário de expiração ou o horário após o qual o JWT não deve ser aceito para processamento. Um recurso também pode rejeitar o token antes desse horário também. A rejeição pode ocorrer quando uma alteração na autenticação é necessária ou uma revogação de token foi detectada.
aio Cadeia de caracteres opaca Uma declaração interna usada pelo Azure AD 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 como o assunto do token foi autenticado.
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 AD do Azure.
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 AD do Azure.
appidacr Cadeia de caracteres, um 0, 1 ou 2, presente apenas em tokens v1.0 Indica como o cliente foi autenticado. Para um cliente público, o valor é 0. Se a ID do cliente e o segredo do cliente são usados, o valor é 1. Se um certificado do cliente foi usado para autenticação, o valor será 2.
azpacr Cadeia de caracteres, um 0, 1 ou 2, presente apenas em tokens v2.0 Uma substituição para appidacr. Indica como o cliente foi autenticado. Para um cliente público, o valor é 0. Se a ID do cliente e o segredo do cliente são usados, o valor é 1. Se um certificado do cliente foi usado para autenticação, o valor será 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. Seu valor é mutável e pode ser alterado ao longo do tempo. Uma vez que o valor é mutável, ele não deve ser usado para tomar decisões de autorização. O valor pode ser usado para dicas de nome de usuário, no entanto, e na interface do usuário legível como um nome de usuário. O escopo profile é necessário para receber essa declaração.
name String Fornece um valor legível por humanos que identifica a entidade do token. Não há garantia de que o valor seja exclusivo. Ele é mutável e é usado apenas para fins de exibição. O escopo profile é necessário para receber essa declaraçã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. 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. Incluído apenas para tokens de usuário.
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. Para tokens de aplicativo, esse conjunto de permissões é usado durante o fluxo de credenciais do cliente no lugar dos escopos do usuário. Para tokens de usuário, esse conjunto de valores é preenchido com as funções às quais o usuário foi atribuído no aplicativo de destino.
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 Azure AD. Esta declaração é configurada por aplicativo, por meio da propriedade groupMembershipClaims do manifesto do aplicativo. Defini-la como All ou DirectoryRole é necessário. Pode não estar presente em tokens obtidos por meio do fluxo implícito devido a problemas de comprimento do token.
groups Matriz JSON de GUIDs Fornece IDs do objeto que representam as associações do grupo do assunto. Esses valores são exclusivos e podem ser usados com segurança para gerenciar o acesso, como impor a autorização para acessar um recurso. Os grupos incluídos na declaração dos grupos são configurados por aplicativo, por meio da propriedade groupMembershipClaims do manifesto do aplicativo. Um valor de null exclui todos os grupos, um valor de SecurityGroup inclui apenas associações do Grupo de Segurança do Active Directory, e um valor de All inclui Grupos de Segurança e Listas de Distribuição do Microsoft 365.

Consulte a declaração hasgroups para obter detalhes de como usar a declaração groups com a concessão implícita. Para outros fluxos, se o número de grupos em que o usuário está passar de 150 para SAML e 200 para JWT, o Azure AD adicionará uma declaração excedente à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.
hasgroups Booliano Se houver algum, sempre true, indicará que o usuário pertence a pelo menos um grupo. Usado no lugar da declaração groups de JWTs em fluxos de concessão implícitos se a declaração completa de grupos ultrapassar o fragmento de URI para além dos limites de extensão da URL (atualmente, seis ou mais grupos). 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 Para solicitações de token sem limite de tamanho (consulte hasgroups), mas ainda muito grandes para o token, um link para a lista completa de grupos do usuário será incluído. 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 O item mais importante sobre o qual o token declara informações, como o usuário de um aplicativo. Esse valor é imutável e não pode ser reatribuído nem reutilizado. Pode ser usado para executar verificações de autorização de forma segura, por exemplo, quando o token é usado para acessar um recurso, e pode ser usado como uma chave nas tabelas de banco de dados. Como o assunto está sempre presente nos tokens emitidos pelo Azure AD, use esse valor em um sistema de autorização de uso geral. O assunto é, no entanto, um identificador de paridade que é exclusivo a uma ID de aplicativo específica. 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. Dois valores diferentes podem ou não ser desejados, dependendo dos requisitos de arquitetura e de privacidade. Confira também a declaração de oid (que permanece a mesma em aplicativos dentro de um locatário).
oid Cadeia de caracteres, um GUID O identificador imutável do solicitante, que é o usuário ou a entidade de serviço que teve a identidade verificada. Também pode ser usada para realizar verificações de autorização com segurança e como uma chave em tabelas de banco de dados. 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 entidades de segurança, o escopo profile é necessário para receber essa declaração dos usuários. Se um usuário único existir em vários locatários, o usuário conterá uma ID de objeto diferente em cada locatário. As contas são consideradas diferentes, embora o usuário faça logon em cada conta com as mesmas credenciais.
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.
unique_name Cadeia de caracteres, presente apenas em tokens v1.0 Fornece um valor legível que identifica a entidade do token. Não há garantia de que esse valor seja exclusivo dentro de um locatário, e ele deve ser usado 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.

Declaração de excedente de grupos

O Azure AD 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 e apenas 6 se emitido pelo fluxo implícito), o Azure AD não emitirá 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.

Declarações básicas v1.0

As declarações a seguir são incluídas nos tokens v1.0, se aplicável, mas não nos 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 para a qual os usuários podem ser enviados para redefinir suas senhas.
in_corp booleano Indica se o cliente está se conectando por meio da rede corporativa. Se não estiver, a declaração não será incluída.
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. Deve ser usado apenas para fins de exibição e para 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. O valor também indica se a autenticação foi realizada por um JWT autoassinado com um certificado X509 de propriedade do serviço.
otp Uma senha única usando um email ou uma mensagem de texto.
fed Uma declaração de autenticação federada (por exemplo, JWT ou SAML) foi usada.
wia Autenticação Integrada do Windows
mfa A autenticação multifator foi usada. Quando essa declaração estiver presente, os outros métodos de autenticação também serão incluídos.
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 Nenhuma autenticação foi realizada.

Tempo de vida do token de acesso

O tempo de vida padrão de um token de acesso é variável. Quando emitido, o tempo de vida padrão de um token de acesso é atribuído a um valor aleatório que varia entre 60-90 minutos (75 minutos em média). A variação melhora a resiliência do serviço, distribuindo a demanda de token de acesso por um tempo, o que impede picos de hora no tráfego para o Azure AD.

Os locatários que não usam o Acesso Condicional têm um tempo de vida de token de acesso padrão de duas horas para clientes como Microsoft Teams e Microsoft 365.

O tempo de vida de um token de acesso pode ser ajustado para controlar com que frequência o aplicativo cliente expira a sessão do aplicativo e com que frequência exige que o usuário seja reautenticado (de forma silenciosa ou interativa). Para substituir a variação de tempo de vida do token de acesso padrão, configure um tempo de vida de token de acesso padrão estático usando CTL (tempo de vida de token configurável).

A variação de tempo de vida do token padrão é aplicada a organizações que têm a CAE (Avaliação contínua de acesso) habilitada. A variação de tempo de vida do token padrão é aplicada mesmo que as organizações usem políticas CTL. O tempo de vida do token padrão para tempos de vida de token de vida útil longa varia de 20 a 28 horas. Quando o token de acesso expira, o cliente precisa usar o token de atualização para adquirir um novo token de atualização e um token de acesso silenciosamente.

As organizações que usam a SIF (frequência de entrada) de Acesso Condicional para impor a frequência de entradas não podem substituir a variação de tempo de vida do token de acesso padrão. Quando as organizações usam a SIF, o tempo entre as solicitações de credenciais para um cliente é o tempo de vida do token que varia de 60 a 90 minutos mais o intervalo de frequência de entrada.

Veja um exemplo de como a variação de tempo de vida do token padrão funciona com a frequência de entrada. Digamos que uma organização defina a frequência de entrada para ocorrer a cada hora. O intervalo de entrada real ocorrerá em qualquer lugar entre 1 hora e 2,5 horas, porque o token é emitido com tempo de vida variando de 60-90 minutos (devido à variação de tempo de vida do token).

Se um usuário com um token com um tempo de vida de uma hora executar uma entrada interativa em 59 minutos (logo antes de a frequência de entrada ser excedida), não haverá nenhuma solicitação de credencial porque a entrada está abaixo do limite de SIF. Se um novo token for emitido com um tempo de vida de 90 minutos, o usuário não verá uma solicitação de credencial por mais uma hora e meia. Quando for feita uma tentativa de renovação silenciosa do tempo de vida do token de 90 minutos, o Azure AD exigirá uma solicitação de credencial, pois a duração total da sessão excedeu a configuração de frequência de entrada de 1 hora. Neste exemplo, a diferença de tempo entre as solicitações de credencial devido ao intervalo do SIF e à variação da vida útil do token seria de 2,5 horas.

Validar tokens

Nem todos os aplicativos devem validar tokens. Somente em cenários específicos, os aplicativos devem validar um token:

  • As APIs da Web precisam validar tokens de acesso recebidos de um cliente. Elas devem aceitar somente tokens que contenham a declaração aud delas.
  • Aplicativos Web confidenciais, como ASP.NET Core, precisam validar tokens de ID que receberam do navegador do usuário no fluxo híbrido, antes de permitir o acesso aos dados de um usuário ou estabelecer uma sessão.

Se nenhum dos cenários acima for aplicável, o aplicativo não se beneficiará da validação do token e poderá apresentar um risco de segurança e confiabilidade se as decisões forem tomadas com base na validade do token. Clientes públicos, como aplicativos nativos ou aplicativos de página única, não se beneficiam da validação de tokens porque o aplicativo se comunica diretamente com o IDP, no qual a proteção SSL garante que os tokens sejam válidos.

APIs e aplicativos Web só devem validar tokens que tenham uma declaração aud que corresponda ao aplicativo. Outros recursos podem ter regras de validação de token personalizadas. Por exemplo, os tokens do Microsoft Graph não serão validados de acordo com essas regras devido ao formato proprietário. Validar e aceitar tokens destinados a outro recurso é um exemplo do problema de confused deputy.

Se seu aplicativo precisar validar um token de ID ou um token de acesso, ele deverá primeiro validar a assinatura e o emissor do token em relação aos valores no documento de descoberta do OpenID. Por exemplo, a versão independente de locatário do documento está localizada em https://login.microsoftonline.com/common/.well-known/openid-configuration.

O middleware do Azure AD tem funcionalidades internas para validar os tokens de acesso, consulte as amostras para encontrar uma na linguagem apropriada. Também há várias bibliotecas de código aberto de terceiros disponíveis para validação de JWT. Para obter mais informações sobre bibliotecas de autenticação e exemplos de código do Azure AD, confira Bibliotecas de autenticação.

Validação da assinatura

Um JWT contém três segmentos, que são separados pelo caractere . . O primeiro segmento é conhecido como o cabeçalho, o segundo como o corpo e o terceiro como a assinatura. O segmento de assinatura pode ser usado para validar a autenticidade do token, de modo que seu aplicativo possa confiar nele.

Os tokens emitidos pelo Azure AD são assinados usando algoritmos de criptografia assimétrica padrão do setor, como o RS256. O cabeçalho do JWT contém informações sobre o método de criptografia e a chave usados para assinar o token:

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk",
  "kid": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk"
}

A declaração alg indica o algoritmo usado para assinar o token, enquanto a declaração kid indica a chave pública privada usada para validar o token.

Em qualquer momento, o Azure AD pode assinar um token de ID usando qualquer conjunto de pares de chaves públicas-privadas de um determinado conjunto. O Azure AD gira o possível conjunto de chaves em intervalos periódicos, de modo que o aplicativo deve ser escrito para tratar essas mudanças de chave automaticamente. Uma frequência razoável para verificar se há atualizações para as chaves públicas usadas pelo Azure AD é a cada 24 horas.

Adquira os dados de chave de assinatura necessários para validar a assinatura usando o documento de metadados do OpenID Connect localizado em:

https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

Dica

Tente isso em um navegador: URL

As seguintes informações descrevem o documento de metadados:

  • É um objeto JSON que contém várias informações úteis, como o local dos vários pontos de extremidade necessários para realizar a autenticação do OpenID Connect.
  • Inclui um jwks_uri, que fornece a localização do conjunto de chaves públicas que correspondem às chaves privadas usadas para assinar tokens. O JWK (Chave da Web JSON) localizado no jwks_uri contém todas as informações de chave pública em uso naquele momento específico. O formato JWK é descrito em RFC 7517. O aplicativo pode usar a declaração kid no cabeçalho do JWT para selecionar a chave pública neste documento, que corresponde à chave privada usada para assinar um token específico. Assim, ele pode realizar a validação da assinatura usando a chave pública correta e o algoritmo indicado.

Observação

Use a declaração kid para validar o token. Enquanto os tokens v1.0 contêm as declarações x5t e kid, os tokens v2.0 contêm apenas a declaração kid.

Executar a validação de assinatura está fora do escopo deste documento. Há muitas bibliotecas de código aberto disponíveis para ajudar na validação de assinatura, se necessário. No entanto, a plataforma de identidade da Microsoft tem uma extensão de assinatura de token para os padrões, que são chaves de assinatura personalizadas.

Se o aplicativo tiver chaves de assinatura personalizadas como resultado do uso do recurso claims-mapping, acrescente um parâmetro de consulta appid que contenha a ID do aplicativo para obter um jwks_uri que aponte para as informações de chave de assinatura do aplicativo, que devem ser usadas para validação. Por exemplo: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e contém uma jwks_uri de https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

Autorização baseada em declarações

A lógica de negócios do aplicativo determina a autorização baseada em declarações. Alguns métodos de autorização comuns são listados abaixo.

Validar o token

Use a declaração aud para verificar se o usuário pretendia chamar o aplicativo. Se o identificador do recurso não estiver na declaração aud, rejeite-o.

Validar a permissão do usuário

Use as declarações roles e wids para validar se o usuário tem autorização para chamar a API. Por exemplo, um administrador pode ter permissão para gravar na API, mas não um usuário normal. Verifique se o tid dentro do token corresponde à ID de locatário usada para armazenar os dados na API.

Quando um usuário armazena dados na API de um locatário, ele deve entrar nesse locatário novamente para acessar esses dados. Nunca permita que dados em um locatário sejam acessados de outro locatário.

Use a declaração amr para verificar se o usuário realizou a MFA. A imposição da MFA é feita usando o Acesso Condicional. Se você tiver solicitado as declarações roles ou groups no token de acesso, verifique se o usuário está no grupo com permissão para executar essa ação.

Para os tokens recuperados usando o fluxo implícito, consulte esses dados no Microsoft Graph, pois eles costumam ser muito grandes para se ajustarem ao token.

Não use os valores de declaração email ou upn para determinar se o usuário em um token de acesso deve ter acesso aos dados. Valores mutáveis de declaração como esses podem mudar ao longo do tempo, tornando-os inseguros e não confiáveis para autorização.

Use valores de declaração imutáveis tid e sub ou oid como uma chave combinada para identificar exclusivamente os dados da API e determinar se um usuário deve receber acesso a esses dados.

  • Bom: tid + sub
  • Melhor: tid + oid – o oid é consistente entre aplicativos, de modo que um ecossistema de aplicativos pode auditar o acesso do usuário aos dados.

Não use identificadores mutáveis e legíveis como email ou upn para identificar dados exclusivamente.

Validar a entrada do aplicativo

  • Use a declaração scp para validar se o usuário concedeu a permissão de aplicativo de chamada para chamar sua API.
  • Verifique se o cliente da chamada tem permissão para chamar sua API usando a declaração appid (para tokens v1.0) ou a declaração azp (para tokens v2.0).
    • Você só precisará validar essas declarações (appid, azp) se quiser restringir sua API Web para ser chamada apenas por aplicativos predeterminados (por exemplo, aplicativos de linha de negócios ou APIs Web chamados por front-ends conhecidos). As APIs destinadas a permitir o acesso de qualquer aplicativo de chamada não precisam validar essas declarações.

Tokens de usuário e aplicativo

Um aplicativo pode receber tokens para um usuário ou diretamente de um aplicativo por meio do fluxo de credenciais do cliente. Esses tokens somente de aplicativo indicam que essa chamada é proveniente de um aplicativo e não tem nenhum usuário dando suporte a ela. Esses tokens são tratados de forma muito parecida:

  • Use roles para ver as permissões concedidas ao assunto do token.
  • Use oid ou sub para validar que a entidade de serviço de chamada é a esperada.

Se seu aplicativo precisar distinguir entre tokens de acesso somente de aplicativo e tokens de acesso para usuários, use a idtypdeclaração opcional. Para detectar tokens de acesso somente no aplicativo, adicione a declaração idtyp ao campo accessToken e verifique o valor app. Tokens de ID e tokens de acesso de usuários não terão a declaração idtyp incluída.

Revogação de token

Os tokens de atualização podem ser invalidados ou revogados a qualquer momento por motivos diferentes. Os motivos se enquadram nas categorias de tempos limite e revogações.

Tempos limite de token

Quando uma organização usa a configuração de tempo de vida do token, o tempo de vida dos tokens de atualização pode ser alterado. Espera-se que alguns tokens possam ficar sem uso. Por exemplo, o usuário não abre o aplicativo por três meses e, em seguida, o token expira. Os aplicativos podem encontrar cenários em que o servidor de logon rejeita um token de atualização devido à sua idade.

  • MaxInactiveTime: se o token de atualização não tiver sido usado no tempo determinado pelo MaxInactiveTime, o token de atualização não será mais válido.
  • MaxSessionAge: se MaxAgeSessionMultiFactor ou MaxAgeSessionSingleFactor tiver sido definido como algo diferente do padrão (até revogado), será necessária a reautenticação depois de decorrido o tempo definido em MaxAgeSession*. Exemplos:
    • O locatário tem uma MaxInactiveTime de cinco dias e o usuário entrou em férias por uma semana. Então, o Azure AD não obteve uma nova solicitação de token do usuário em sete dias. Na próxima vez que o usuário solicitar um novo token, ele descobrirá que o token de atualização foi revogado e deverá inserir suas credenciais novamente.
    • Um aplicativo confidencial tem um MaxAgeSessionSingleFactor de um dia. Se um usuário fizer logon na segunda-feira e na terça-feira (após decorridas 25 horas), ele deverá se autenticar novamente.

Revogações de token

Os tokens de atualização podem ser revogados pelo servidor devido a uma alteração nas credenciais, ao uso ou à ação do administrador. Os tokens de atualização estão nas classes de clientes confidenciais e clientes públicos.

Alteração Cookie baseado em senha Token baseado em senha Cookie não baseado em senha Token não baseados em senha Token de cliente confidencial
A senha expira Permanece ativo Permanece ativo Permanece ativo Permanece ativo Permanece ativo
Senha alterada pelo usuário Revogado Revogado Permanece ativo Permanece ativo Permanece ativo
Usuário faz SSPR Revogado Revogado Permanece ativo Permanece ativo Permanece ativo
Administrador redefine senha Revogado Revogado Permanece ativo Permanece ativo Permanece ativo
O usuário revoga seus tokens de atualização usando o PowerShell Revogado Revogado Revogado Revogado Revogado
O administrador revoga todos os tokens de atualização de um usuário usando o PowerShell Revogado Revogado Revogado Revogado Revogado
Logoff único na Web Revogado Permanece ativo Revogado Permanece ativo Permanece ativo

Não baseado em senha

Um logon não baseado em senha é um logon em que o usuário não digita uma senha para entrar. Entre os exemplos de logon não baseado em senha estão:

  • Usar o rosto com o Windows Hello
  • Chave FIDO2
  • SMS
  • Voz
  • PIN

Para saber mais, confira Tokens de Atualização Primários.

Próximas etapas