Tokens de acesso na plataforma de identidade da Microsoft

  • Artigo

Os tokens de acesso permitem que os clientes chamem APIs da Web protegidas com segurança. As APIs da Web usam tokens de acesso 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 um formato definido. Alguns provedores de identidade (IDPs) usam GUIDs e outros usam blobs criptografados. O formato do token de acesso pode depender da configuração da API que o aceita.

APIs personalizadas registradas por desenvolvedores na plataforma de identidade da Microsoft podem escolher entre dois formatos diferentes de JSON Web Tokens (JWTs) 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 que não podem ser validados podem ser tokens criptografados, JWTs ou JWT especiais.

O conteúdo do token destina-se apenas à API, o que significa que os tokens de acesso devem ser tratados como cadeias de caracteres opacas. Apenas para fins de validação e depuração, os desenvolvedores podem decodificar JWTs usando um site como o jwt.ms. Os tokens que uma API da Microsoft recebe nem sempre podem ser um JWT que pode ser decodificado.

Os clientes devem usar os dados de resposta do token que são retornados com o token de acesso para obter detalhes sobre o que está dentro dele. 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 o tempo de expiração do token de acesso e os escopos para os quais ele é válido. Esses dados permitem que o aplicativo faça cache inteligente de tokens de acesso sem ter que analisar o token de acesso em si.

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

Nota

Toda a documentação nesta página, exceto onde indicado, aplica-se apenas a tokens emitidos para APIs registradas. Ele não se aplica a tokens emitidos para APIs de propriedade da Microsoft, nem esses tokens podem ser usados para validar como a plataforma de identidade da Microsoft emite tokens para uma API registrada.

Formatos de token

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

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

  • v1.0 para aplicações apenas Microsoft Entra. O exemplo a seguir mostra um token v1.0 (as chaves são alteradas e as informações pessoais são removidas, o que impede a validação do token):

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd

  • v2.0 para aplicações que suportam contas de consumidor. O exemplo a seguir mostra um token v2.0 (as chaves são alteradas e as informações pessoais são removidas, o que impede a validação do token):

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt

Defina a versão para aplicativos fornecendo o valor apropriado para a accessTokenAcceptedVersion configuração no manifesto do aplicativo. Os valores de null e 1 resultam em tokens v1.0 e o valor dos 2 resultados em tokens v2.0.

Propriedade do token

Uma solicitação de token de acesso envolve duas partes: o cliente, que solicita o token, e o recurso (API da Web) que aceita o token. O recurso ao qual o token se destina (seu público) é definido na aud declaração em um token. Os clientes usam o token, mas não devem entendê-lo ou tentar analisá-lo. Os recursos aceitam o token.

A plataforma de identidade da Microsoft oferece suporte à emissão de qualquer versão de token a partir de qualquer ponto de extremidade de versão. Por exemplo, quando o valor de é 2, um cliente que chama o ponto de extremidade v1.0 para obter um token para esse recurso recebe um token de accessTokenAcceptedVersion acesso v2.0.

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

Duração do token

O tempo de vida padrão de um token de acesso é variável. Quando emitida, a plataforma de identidade da Microsoft atribui um valor aleatório que varia entre 60 e 90 minutos (75 minutos em média) como o tempo de vida padrão de um token de acesso. A variação melhora a resiliência do serviço ao espalhar a demanda de token de acesso ao longo de um tempo, o que evita picos horários no tráfego para o Microsoft Entra ID.

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 o Microsoft Teams e o Microsoft 365.

Ajuste o tempo de vida de um token de acesso para controlar a frequência com que o aplicativo cliente expira a sessão do aplicativo e com que frequência ele exige que o usuário se autentique novamente (silenciosamente ou interativamente). Para substituir a variação do tempo de vida do token de acesso padrão, use o tempo de vida do token configurável (CTL).

Aplique a variação do tempo de vida do token padrão às organizações que têm a Avaliação de Acesso Contínuo (CAE) habilitada. Aplique a variação de tempo de vida do token padrão mesmo que as organizações usem políticas de CTL. O tempo de vida do token padrão para o tempo de vida do token de longa duração varia de 20 a 28 horas. Quando o token de acesso expira, o cliente deve usar o token de atualização para adquirir silenciosamente um novo token de atualização e token de acesso.

As organizações que usam a frequência de entrada do Acesso Condicional (SIF) para impor a frequência com que os logins ocorrem não podem substituir a variação do tempo de vida do token de acesso padrão. Quando as organizações usam SIF, o tempo entre os prompts 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.

Aqui está um exemplo de como a variação do 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. Quando o token tem tempo de vida variando de 60 a 90 minutos devido à variação do tempo de vida do token, o intervalo de entrada real ocorre entre 1 hora e 2,5 horas.

Se um usuário com um token com um tempo de vida de uma hora executar uma entrada interativa em 59 minutos, não haverá nenhum prompt de credencial porque a entrada está abaixo do limite SIF. Se um novo token tiver uma vida útil de 90 minutos, o usuário não verá um prompt de credencial por mais uma hora e meia. Durante uma tentativa de renovação silenciosa, o Microsoft Entra ID requer um prompt de credencial porque 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 os prompts de credenciais devido ao intervalo SIF e à variação do tempo de vida 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 devem validar os tokens de acesso enviados a elas por um cliente. Eles só devem aceitar tokens contendo um de seus URIs AppId como a aud declaração.
  • Os aplicativos Web devem validar tokens de ID enviados a eles usando o 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 descritos anteriormente se aplicar, não há necessidade de validar o token. Clientes públicos, como aplicativos nativos, de desktop ou de página única, não se beneficiam da validação de tokens de ID porque o aplicativo se comunica diretamente com o IDP, onde a proteção SSL garante que os tokens de ID sejam válidos. Eles não devem validar os tokens de acesso, pois são para a API da Web validar, não para o cliente.

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

Se o aplicativo precisar validar um token de ID ou um token de acesso, ele deve primeiro validar a assinatura do token e do emissor em relação aos valores no documento de descoberta OpenID.

O middleware Microsoft Entra tem recursos internos para validar tokens de acesso, consulte exemplos para encontrar um no idioma apropriado. Há também várias bibliotecas de código aberto de terceiros disponíveis para validação JWT. Para obter mais informações sobre bibliotecas de autenticação e exemplos de código, consulte as bibliotecas de autenticação. Se seu aplicativo Web ou API da Web estiver no ASP.NET ou no ASP.NET Core, use Microsoft.Identity.Web, que lida com a validação para você.

Tokens v1.0 e v2.0

  • Quando seu aplicativo/API da Web está validando um token v1.0 (ver claim ="1.0"), ele precisa ler o documento de metadados do OpenID Connect do ponto de extremidade v1.0 (https://login.microsoftonline.com/{example-tenant-id}/.well-known/openid-configuration), mesmo que a autoridade configurada para sua API da Web seja uma autoridade v2.0.
  • Quando seu aplicativo/API da Web está validando um token v2.0 (ver claim ="2.0"), ele precisa ler o documento de metadados do OpenID Connect do ponto de extremidade v2.0 (https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration), mesmo que a autoridade configurada para sua API da Web seja uma autoridade v1.0.

Os exemplos a seguir supõem que seu aplicativo está validando um token de acesso v2.0 (e, portanto, faça referência às versões v2.0 dos documentos e chaves de metadados OIDC). Basta remover o "/v2.0" no URL se validar tokens v1.0.

Validar o emissor

OpenID Connect Core diz "O identificador do emissor [...] DEVE corresponder exatamente ao valor do Crédito ISS (emitente)." Para aplicativos que usam um ponto de extremidade de metadados específico do locatário (como https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/.well-known/openid-configuration ou https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration), isso é tudo o que é necessário.

O Microsoft Entra ID tem uma versão independente do locatário do documento disponível em https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Este ponto de extremidade retorna um valor https://login.microsoftonline.com/{tenantid}/v2.0de emissor . Os aplicativos podem usar esse ponto de extremidade independente do locatário para validar tokens de cada locatário com as seguintes modificações:

  1. Em vez de esperar que a declaração do emissor no token corresponda exatamente ao valor do emissor dos metadados, o aplicativo deve substituir o {tenantid} valor nos metadados do emissor pelo tenantid que é o destino da solicitação atual e, em seguida, verificar a correspondência exata.

  2. O aplicativo deve usar a issuer propriedade retornada do ponto de extremidade de chaves para restringir o escopo das chaves.

    • As chaves que têm um valor de emissor como https://login.microsoftonline.com/{tenantid}/v2.0 podem ser usadas com qualquer emissor de token correspondente.
    • As chaves que têm um valor de emissor como https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 só devem ser usadas com correspondência exata.

    O ponto de extremidade de chave independente de locatário (https://login.microsoftonline.com/common/discovery/v2.0/keys) do Microsoft Entra retorna um documento como:

    {
  "keys":[
    {"kty":"RSA","use":"sig","kid":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
  ]
}

  3. Os aplicativos que usam uma declaração de tenantid (tid) do Microsoft Entra como um limite de confiança em vez da declaração de emissor padrão devem garantir que a declaração de id de locatário seja um guid e que o emissor e o locatário correspondam.

O uso de metadados independentes do locatário é mais eficiente para aplicativos que aceitam tokens de muitos locatários.

Nota

Com os metadados independentes do locatário do Microsoft Entra, as declarações devem ser interpretadas dentro do locatário, assim como no OpenID Connect padrão, as declarações são interpretadas dentro do emissor. Ou seja, {"sub":"ABC123","iss":"https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0","tid":"aaaabbbb-0000-cccc-1111-dddd2222eeee"} e {"sub":"ABC123","iss":"https://login.microsoftonline.com/bbbbcccc-1111-dddd-2222-eeee3333ffff/v2.0","tid":"bbbbcccc-1111-dddd-2222-eeee3333ffff"} descrever usuários diferentes, mesmo que o sub seja o mesmo, porque declarações como sub são interpretadas dentro do contexto do emissor/locatário.

Validar a assinatura

Um JWT contém três segmentos separados pelo . caractere. O primeiro segmento é o cabeçalho, o segundo é o corpo e o terceiro é a assinatura. Use o segmento de assinatura para avaliar a autenticidade do token.

O Microsoft Entra ID emite tokens assinados usando os algoritmos de criptografia assimétrica padrão do setor, como RS256. O cabeçalho do JWT contém informações sobre a chave e o método de criptografia usados para assinar o token:

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

A alg declaração indica o algoritmo usado para assinar o token, enquanto a kid declaração indica a chave pública específica que foi usada para validar o token.

A qualquer momento, o Microsoft Entra ID pode assinar um token de ID usando qualquer um de um determinado conjunto de pares de chaves público-privado. O Microsoft Entra ID gira o possível conjunto de chaves periodicamente, portanto, escreva o aplicativo para lidar com essas alterações de chave automaticamente. Uma frequência razoável para verificar se há atualizações para as chaves públicas usadas pelo Microsoft Entra ID é a cada 24 horas.

Adquira os dados da 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

Gorjeta

Tente isso em um navegador: URL

As informações a seguir 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 fazer 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. A chave da Web JSON (JWK) localizada no jwks_uri contém todas as informações de chave pública em uso naquele momento específico. RFC 7517 descreve o formato JWK. O aplicativo pode usar a kid declaração no cabeçalho JWT para selecionar a chave pública, a partir deste documento, que corresponde à chave privada que foi usada para assinar um token específico. Em seguida, ele pode fazer a validação da assinatura usando a chave pública correta e o algoritmo indicado.

Nota

Use a kid declaração para validar o token. Embora os tokens v1.0 contenham as declarações e kid , os x5t tokens v2.0 contenham apenas a kid declaração.

Fazer a validação da assinatura está fora do escopo deste documento. Há muitas bibliotecas de código aberto disponíveis para ajudar na validação de assinaturas, 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 de mapeamento de declarações, acrescente um appid parâmetro de consulta que contenha a ID do aplicativo. Para validação, use jwks_uri isso que aponta para as informações da chave de assinatura do aplicativo. Por exemplo: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=00001111-aaaa-2222-bbbb-3333cccc4444 contém um jwks_uri de https://login.microsoftonline.com/{tenant}/discovery/keys?appid=00001111-aaaa-2222-bbbb-3333cccc4444.

Validar o emissor

Os aplicativos Web que validam tokens de ID e as APIs Web que validam tokens de acesso precisam validar o emissor do token (iss declaração) contra:

  1. o emissor disponível no documento de metadados OpenID connect associado à configuração do aplicativo (autoridade). O documento de metadados a verificar depende:
    • A versão do token
    • as contas suportadas pela sua aplicação.
  2. o ID do locatário (tid declaração) do token,
  3. o emissor da chave de assinatura.

Aplicativos de locatário único

OpenID Connect Core diz "O identificador do emissor [...] DEVE corresponder exatamente ao valor da iss Reclamação (do emitente)." Para aplicativos que usam um ponto de extremidade de metadados específico do locatário, como https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration ou https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration.

Aplicativos de locatário único são aplicativos que suportam:

  • Contas em um diretório organizacional (somente example-tenant-id ): https://login.microsoftonline.com/{example-tenant-id}
  • Apenas contas pessoais da Microsoft: https://login.microsoftonline.com/consumers (consumidores sendo um apelido para o locatário 9188040d-6c67-4c5b-b112-36a304b66dad)

Aplicações multi-inquilino

O Microsoft Entra ID também suporta aplicativos multilocatário. Estas aplicações suportam:

  • Contas em qualquer diretório organizacional (qualquer diretório do Microsoft Entra): https://login.microsoftonline.com/organizations
  • Contas em qualquer diretório organizacional (qualquer diretório do Microsoft Entra) e contas pessoais da Microsoft (por exemplo, Skype, XBox): https://login.microsoftonline.com/common

Para esses aplicativos, o Microsoft Entra ID expõe versões independentes do locatário do documento OIDC em https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration e https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration respectivamente. Esses pontos de extremidade retornam um valor de emissor, que é um modelo parametrizado pelo tenantid: https://login.microsoftonline.com/{tenantid}/v2.0. Os aplicativos podem usar esses pontos de extremidade independentes do locatário para validar tokens de cada locatário com as seguintes estipulações:

  • Validar o emissor da chave de assinatura
  • Em vez de esperar que a declaração do emissor no token corresponda exatamente ao valor do emissor dos metadados, o aplicativo deve substituir o {tenantid} valor nos metadados do emissor pelo ID do locatário que é o destino da solicitação atual e, em seguida, verificar a correspondência exata (tid reivindicação do token).
  • Valide se a tid declaração é um GUID e se a iss reivindicação é do formato https://login.microsoftonline.com/{tid}/v2.0 onde {tid} está a reivindicação exata tid . Essa validação vincula o locatário de volta ao emissor e de volta ao escopo da chave de assinatura, criando uma cadeia de confiança.
  • Use tid a reivindicação quando localizar dados associados ao assunto da reclamação. Em outras palavras, a tid reivindicação deve fazer parte da chave usada para acessar os dados do usuário.

Validar o emissor da chave de assinatura

Os aplicativos que usam os metadados independentes do locatário v2.0 precisam validar o emissor da chave de assinatura.

Documento de chaves e emissor de chaves de assinatura

Conforme discutido, a partir do documento OpenID Connect, seu aplicativo acessa as chaves usadas para assinar os tokens. Ele obtém o documento de chaves correspondente acessando a URL exposta na propriedade jwks_uri do documento OpenIdConnect.

 "jwks_uri": "https://login.microsoftonline.com/{example-tenant-id}/discovery/v2.0/keys",

O {example-tenant-id} valor pode ser substituído por um GUID, um nome de domínio ou organizações e consumidores comuns

Os keys documentos expostos pelo Azure AD v2.0 contém, para cada chave, o emissor que usa essa chave de assinatura. Por exemplo, o ponto de extremidade https://login.microsoftonline.com/common/discovery/v2.0/keys de chave "comum" independente do locatário retorna um documento como:

{
  "keys":[
    {"kty":"RSA","use":"sig","kid":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
  ]
}

Validação do emissor da chave de assinatura

O aplicativo deve usar a issuer propriedade do documento de chaves, associada à chave usada para assinar o token, a fim de restringir o escopo de chaves:

  • As chaves que têm um valor de emissor com um GUID como https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 só devem ser usadas quando a iss declaração no token corresponder exatamente ao valor.
  • As chaves que têm um valor de emissor de modelo como https://login.microsoftonline.com/{tenantid}/v2.0 só devem ser usadas quando a iss declaração no token corresponder a esse valor depois de substituir a tid declaração no token pelo {tenantid} espaço reservado.

O uso de metadados independentes do locatário é mais eficiente para aplicativos que aceitam tokens de muitos locatários.

Nota

Com os metadados independentes do locatário do Microsoft Entra, as declarações devem ser interpretadas dentro do locatário, assim como no OpenID Connect padrão, as declarações são interpretadas dentro do emissor. Ou seja, {"sub":"ABC123","iss":"https://login.microsoftonline.com/{example-tenant-id}/v2.0","tid":"{example-tenant-id}"} e {"sub":"ABC123","iss":"https://login.microsoftonline.com/{another-tenand-id}/v2.0","tid":"{another-tenant-id}"} descrever usuários diferentes, mesmo que o sub seja o mesmo, porque declarações como sub são interpretadas dentro do contexto do emissor/locatário.

Recapitulação

Aqui está um pseudo código que recapitula como validar o emissor e o emissor da chave de assinatura:

  1. Buscar chaves da URL de metadados configurada
  2. Verifique o token se assinado com uma das chaves publicadas, falhe se não
  3. Identifique a chave nos metadados com base no cabeçalho kid. Verifique a propriedade "emissor" anexada à chave no documento de metadados: 
    var issuer = metadata["kid"].issuer;
if (issuer.contains("{tenantId}", CaseInvariant)) issuer = issuer.Replace("{tenantid}", token["tid"], CaseInvariant);
if (issuer != token["iss"]) throw validationException;
if (configuration.allowedIssuer != "*" && configuration.allowedIssuer != issuer) throw validationException;
var issUri = new Uri(token["iss"]);
if (issUri.Segments.Count < 1) throw validationException;
if (issUri.Segments[1] != token["tid"]) throw validationException;

Consulte também

Próximos passos