Tokens de acesso da plataforma de identidade da Microsoft

  • Artigo

Os tokens de acesso permitem que os clientes chamem APIs Web protegidas com segurança. As APIs da Web utilizam 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 formato definido. Alguns IDPs (provedores de identidade) usam GUIDs; 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 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 que não podem ser validados podem ser tokens criptografados, JWTs ou semelhantes a JWT especiais.

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

Os clientes devem usar os dados de resposta do token 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 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 Microsoft Entra. O exemplo a seguir mostra um token v1.0 (as chaves são alteradas e as informações pessoais são removidas, impedindo a validação do token):

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd

  • v2.0 para aplicativos que dão suporte a 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, impedindo a validação do token):

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt

Defina a versão dos aplicativos fornecendo o valor apropriado para a configuração accessTokenAcceptedVersionno 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

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 para o qual o token se destina (seu público-alvo) está definido na declaração aud em um token. 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 suporta a emissão de qualquer versão de token a partir de qualquer ponto de extremidade de versão. Por exemplo, quando o valor de accessTokenAcceptedVersion é 2, um cliente chamando 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.

Tempo de vida do Token

O tempo de vida padrão de um token de acesso é variável. Quando emitido, 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, distribuindo a demanda de token de acesso por um tempo, o que impede picos de hora no tráfego para o Microsoft Entra ID.

Os locatários que não usam o Acesso Condicional têm o tempo de vida padrão do token de acesso 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 faça a nova autenticação (silenciosa ou interativa). Para substituir a variação do tempo de vida do token de acesso padrão, utilize Tempo de Vida do Token Configurável (CTL).

Aplicar a variação padrão do tempo de vida útil do token às organizações que tenham a Avaliação Contínua de Acesso (CAE) habilitada. Aplicar variação de tempo de vida do token padrão, 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. Quando o token tem um tempo de vida variando de 60 a 90 minutos devido à variação do tempo de vida do token, o intervalo de entrada real ocorre em qualquer lugar entre 1 hora e 2,5 horas.

Se um usuário com um token com tempo de vida de uma hora realizar uma entrada interativa aos 59 minutos, não haverá nenhum prompt de credencial porque a entrada está abaixo do limite de SIF. Se um novo token tiver um tempo de vida de 90 minutos, o usuário não verá uma solicitação de credencial por mais uma hora e meia. Durante uma tentativa de renovação silenciosa, o Microsoft Entra ID exige uma solicitação 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 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. Eles só devem aceitar tokens que contenham um de seus URIs de AppId como a declaração aud.
  • Os aplicativos Web 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.

Caso nenhum dos cenários descritos anteriormente esteja presente, não será necessário 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, no qual a proteção SSL garante que os tokens de ID sejam válidos. Eles não devem validar os tokens de acesso, pois eles devem ser validados pela API da Web, não pelo cliente.

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, você não pode validar tokens para o Microsoft Graph 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.

O middleware do Microsoft Entra 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, confira Bibliotecas de autenticação. Se o seu aplicativo da Web ou API da Web estiver no ASP.NET ou 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 Web está validando um token v1.0 (declaração ver ="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 Web seja uma autoridade v2.0.
  • Quando seu aplicativo/API Web está validando um token v2.0 (declaração ver ="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 Web seja uma autoridade v1.0.

Os exemplos abaixo supõem que seu aplicativo esteja validando um token de acesso v2.0 (e, portanto, referencie as versões v2.0 dos documentos e chaves de metadados do OpenID Connect). Basta remover o "/v2.0" na URL se você valida tokens v1.0.

Validar o emissor

O OpenID Connect Core diz "O identificador do emissor [...] DEVE corresponder exatamente ao valor da declaração iss (emissor)". 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 possui uma versão independente de locatário do documento para aplicativos multilocatário disponível em https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Esse ponto de extremidade retorna um valor de emissor https://login.microsoftonline.com/{tenantid}/v2.0. Os aplicativos podem usar esse ponto de extremidade independente de 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 valor {tenantid} nos metadados do emissor pela ID do locatário que é o destino da solicitação atual e, em seguida, marcar a correspondência exata.

  2. O aplicativo deve usar a propriedade issuer 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 do Microsoft Entra (https://login.microsoftonline.com/common/discovery/v2.0/keys) 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 a declaração de ID de locatário do Microsoft Entra (tid) como um limite de confiança em vez da declaração do emissor padrão devem garantir que a declaração de ID do locatário seja um GUID e que o emissor e a ID do locatário correspondam.

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

Observação

Com metadados independentes de 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"} descrevem 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. Utilize 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 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 específica usada para validar o token.

Em qualquer momento, o Microsoft Entra ID pode assinar um token de ID usando qualquer conjunto de pares de chaves públicas-privadas de um determinado conjunto. O Microsoft Entra ID gira o possível conjunto de chaves periodicamente, portanto, grave 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 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 RFC 7517 descreve o formato JWK. 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 validação, use jwks_uri 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 uma jwks_uri de https://login.microsoftonline.com/{tenant}/discovery/keys?appid=00001111-aaaa-2222-bbbb-3333cccc4444.

Validar o emissor

Aplicativos Web validando tokens de ID e APIs Web validando tokens de acesso precisam validar o emissor do token (declaração iss) em relação a:

  1. o emissor disponível no documento de metadados do OpenID Connect associado à configuração do aplicativo (autoridade). O documento de metadados para verificação depende de:
    • versão do token
    • contas compatíveis com seu aplicativo.
  2. ID do locatário (declaração tid) do token,
  3. o emissor da chave de autenticação.

Aplicativos de locatário único

O OpenID Connect Core diz "O identificador do emissor [...] DEVE corresponder exatamente ao valor da declaração iss (emissor)". 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 dão suporte a:

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

Aplicativos multilocatários

O Microsoft Entra ID também é compatível com aplicativos multilocatários. Esses aplicativos são compatíveis com:

  • 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 de 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 terminais independentes de locatário para validar tokens de cada locatário com as seguintes estipulações:

  • Validar o emissor da chave de autenticação
  • 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 valor {tenantid} nos metadados do emissor pela ID do locatário que é o destino da solicitação atual e, em seguida, verificar a correspondência exata (declaração tid do token).
  • Validar se a declaração tid é um GUID e a declaração iss é do formulário https://login.microsoftonline.com/{tid}/v2.0 em que {tid} é exatamente a declaração tid. Isso vincula o locatário de volta ao emissor e de volta ao escopo da chave de assinatura criando uma cadeia de confiança.
  • Use a declaração tid quando localizarem dados associados ao assunto da declaração. Em outras palavras, a declaração tid deve fazer parte da chave usada para acessar os dados do usuário.

Validar o emissor da chave de autenticação

Aplicativos que usam os metadados v2.0 independentes do locatário precisam validar o emissor da chave de autenticação.

Documento de chaves e emissor de chave de autenticação

Conforme discutido, no documento do OpenID Connect, seu aplicativo acessa as chaves usadas para autenticar 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 valor {example-tenant-id} pode ser substituído por um GUID, um nome de domínio ou comum, organizações e consumidores

Os documentos de keys expostos pelo Azure AD v2.0 contêm, para cada chave, o emissor que usa essa chave de autenticação. Por exemplo, o ponto de extremidade https://login.microsoftonline.com/common/discovery/v2.0/keys de chave "comum" e independente de 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 autenticação

O aplicativo deve usar a propriedade issuer do documento de chaves, associada à chave usada para autenticar o token, a fim de restringir o escopo das 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 declaração iss no token corresponde exatamente ao valor.
  • Chaves que têm um valor de emissor modelado como https://login.microsoftonline.com/{tenantid}/v2.0 só devem ser usadas quando a declaração iss no token corresponder a esse valor depois de substituir a declaração tid no token pelo espaço reservado {tenantid}.

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

Observação

Com metadados independentes de 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}"} descrevem 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

Eis um pseudocódigo que recapitula como validar o emissor e o emissor da chave de autenticação:

  1. Buscar chaves da URL de metadados configurada
  2. Verificar o token se autenticado com uma das chaves publicadas, caso contrário, falhará
  3. Identificar a chave nos metadados com base no cabeçalho secundário. 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;

Confira também

Próximas etapas