Tokens de ID da plataforma de identidade da Microsoft

  • Artigo
  • 13 minutos para o fim da leitura

O token de ID é a extensão principal do OpenID Connect para o OAuth 2.0. Os tokens de ID são emitidos pelo servidor de autorização e contêm declarações que carregam informações sobre o usuário. Eles podem ser enviados junto ou no lugar de um token de acesso. As informações nos Tokens de ID permitem que o cliente verifique se um usuário é quem ele diz ser. Os tokens de ID devem ser compreendidos por aplicativos de terceiros. Os tokens de ID não devem ser usados para fins de autorização. Tokens de acesso são usados para autorização. As declarações fornecidas pelos tokens de ID podem ser usadas para a experiência do usuário dentro de seu aplicativo, como chaves em um banco de dados e fornecendo acesso ao aplicativo cliente.

Pré-requisitos

O seguinte artigo será útil antes de seguir adiante neste artigo:

Declarações em um token de ID

Os tokens de ID são JWT (tokens de Web JSON). Esses tokens de ID consistem em um cabeçalho, um conteúdo e uma assinatura. O cabeçalho e a assinatura são usados para verificar a autenticidade do token, enquanto o conteúdo tem informações sobre o usuário solicitado pelo cliente. Os tokens de ID v1.0 e v2.0 têm diferenças nas informações que eles carregam. A versão é baseada no ponto de extremidade da solicitação. Embora os aplicativos existentes provavelmente usem o ponto de extremidade do Azure AD (v1.0), os novos aplicativos devem usar o ponto de extremidade "plataforma de identidade da Microsoft" (v2.0).

  • v1.0: ponto de extremidade do Azure Active Directory: https://login.microsoftonline.com/common/oauth2/authorize
  • v2.0: ponto de extremidade da plataforma de identidade da Microsoft: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Token de ID v1.0 de exemplo

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjdfWnVmMXR2a3dMeFlhSFMzcTZsVWpVWUlHdyIsImtpZCI6IjdfWnVmMXR2a3dMeFlhSFMzcTZsVWpVWUlHdyJ9.eyJhdWQiOiJiMTRhNzUwNS05NmU5LTQ5MjctOTFlOC0wNjAxZDBmYzljYWEiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkvIiwiaWF0IjoxNTM2Mjc1MTI0LCJuYmYiOjE1MzYyNzUxMjQsImV4cCI6MTUzNjI3OTAyNCwiYWlvIjoiQVhRQWkvOElBQUFBcXhzdUIrUjREMnJGUXFPRVRPNFlkWGJMRDlrWjh4ZlhhZGVBTTBRMk5rTlQ1aXpmZzN1d2JXU1hodVNTajZVVDVoeTJENldxQXBCNWpLQTZaZ1o5ay9TVTI3dVY5Y2V0WGZMT3RwTnR0Z2s1RGNCdGsrTExzdHovSmcrZ1lSbXY5YlVVNFhscGhUYzZDODZKbWoxRkN3PT0iLCJhbXIiOlsicnNhIl0sImVtYWlsIjoiYWJlbGlAbWljcm9zb2Z0LmNvbSIsImZhbWlseV9uYW1lIjoiTGluY29sbiIsImdpdmVuX25hbWUiOiJBYmUiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMWRiNDcvIiwiaXBhZGRyIjoiMTMxLjEwNy4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJub25jZSI6IjEyMzUyMyIsIm9pZCI6IjA1ODMzYjZiLWFhMWQtNDJkNC05ZWMwLTFiMmJiOTE5NDQzOCIsInJoIjoiSSIsInN1YiI6IjVfSjlyU3NzOC1qdnRfSWN1NnVlUk5MOHhYYjhMRjRGc2dfS29vQzJSSlEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6IkFiZUxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJMeGVfNDZHcVRrT3BHU2ZUbG40RUFBIiwidmVyIjoiMS4wIn0=.UJQrCA6qn2bXq57qzGX_-D3HcPHqBMOKDPx4su1yKRLNErVD8xkxJLNLVRdASHqEcpyDctbdHccu6DPpkq5f0ibcaQFhejQNcABidJCTz0Bb2AbdUCTqAzdt9pdgQvMBnVH1xk3SCM6d4BbT4BkLLj10ZLasX7vRknaSjE_C5DI7Fg4WrZPwOhII1dB0HEZ_qpNaYXEiy-o94UJ94zCr07GgrqMsfYQqFR7kn-mn68AjvLcgwSfZvyR_yIK75S_K37vC3QryQ7cNoafDe9upql_6pB2ybMVlgWPs_DmbJ8g0om-sPlwyn74Cc1tW3ze-Xptw_2uVdPgWyqfuWAfq6Q

Exiba esse token de exemplo de v1.0 em jwt.ms.

Token de ID v2.0 de exemplo

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjFMVE16YWtpaGlSbGFfOHoyQkVKVlhlV01xbyJ9.eyJ2ZXIiOiIyLjAiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vOTEyMjA0MGQtNmM2Ny00YzViLWIxMTItMzZhMzA0YjY2ZGFkL3YyLjAiLCJzdWIiOiJBQUFBQUFBQUFBQUFBQUFBQUFBQUFJa3pxRlZyU2FTYUZIeTc4MmJidGFRIiwiYXVkIjoiNmNiMDQwMTgtYTNmNS00NmE3LWI5OTUtOTQwYzc4ZjVhZWYzIiwiZXhwIjoxNTM2MzYxNDExLCJpYXQiOjE1MzYyNzQ3MTEsIm5iZiI6MTUzNjI3NDcxMSwibmFtZSI6IkFiZSBMaW5jb2xuIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiQWJlTGlAbWljcm9zb2Z0LmNvbSIsIm9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC02NmYzLTMzMzJlY2E3ZWE4MSIsInRpZCI6IjkxMjIwNDBkLTZjNjctNGM1Yi1iMTEyLTM2YTMwNGI2NmRhZCIsIm5vbmNlIjoiMTIzNTIzIiwiYWlvIjoiRGYyVVZYTDFpeCFsTUNXTVNPSkJjRmF0emNHZnZGR2hqS3Y4cTVnMHg3MzJkUjVNQjVCaXN2R1FPN1lXQnlqZDhpUURMcSFlR2JJRGFreXA1bW5PcmNkcUhlWVNubHRlcFFtUnA2QUlaOGpZIn0.1AFWW-Ck5nROwSlltm7GzZvDwUkqvhSQpm55TQsmVo9Y59cLhRXpvB8n-55HCr9Z6G_31_UbeUkoz612I2j_Sm9FFShSDDjoaLQr54CreGIJvjtmS3EkK9a7SJBbcpL1MpUtlfygow39tFjY7EVNW9plWUvRrTgVk7lYLprvfzw-CIqw3gHC-T7IK_m_xkr08INERBtaecwhTeN4chPC4W3jdmw_lIxzC48YoQ0dB1L9-ImX98Egypfrlbm0IBL5spFzL6JDZIRRJOu8vecJvj1mq-IUhGt0MacxX8jdxYLP-KUu2d9MbNKpCKJuZ7p8gwTL5B7NlUdh_dmSviPWrw

Exiba esse token de exemplo de v2.0 em jwt.ms.

Todas as declarações JWT listadas abaixo aparecem nos tokens v1.0 e v2.0, a menos que seja indicado o contrário.

Declarações de cabeçalho

A tabela a seguir mostra declarações de cabeçalho presentes em tokens de ID.

Declaração Formatar Descrição
typ Cadeia de caracteres – sempre "JWT" Indica que o token é um token JWT.
alg String Indica o algoritmo que foi usado para assinar o token. Exemplo: "RS256"
kid String Especifica a impressão digital da chave pública que pode ser usada para validar a assinatura desse token. Emitido nos tokens de ID v1.0 e v2.0.
x5t String Funciona da mesma forma (em uso e valor) que kid. x5t é uma declaração herdada emitida somente em tokens de ID da v1.0 para fins de compatibilidade.

Declarações de conteúdo

A tabela abaixo mostra as declarações que estão na maioria dos tokens de ID por padrão (exceto quando indicado). No entanto, o aplicativo pode usar declarações opcionais para solicitar mais declarações token de ID. As declarações opcionais podem ser desde uma declaração groups até informações sobre o nome de usuário.

Declaração Formatar Descrição
aud Cadeia de caracteres, um GUID da ID do Aplicativo Identifica o destinatário pretendido do token. Em id_tokens, o público-alvo é a ID de Aplicativo de seu aplicativo, atribuída a ele no portal do Azure. Este valor deve ser validado. O token deverá ser rejeitado se não corresponder à ID de Aplicativo do seu aplicativo.
iss Cadeia de caracteres, um URI do emissor Identifica o emissor ou o "servidor de autorização" que constrói e retorna o token. Também identifica o locatário do Azure AD para o qual o usuário foi autenticado. Se o token tiver sido emitido pelo ponto de extremidade v2.0, o URI terminará com /v2.0. O GUID que indica que o usuário é um consumidor da conta da Microsoft é 9188040d-6c67-4c5b-b112-36a304b66dad. O aplicativo deve usar a parte do GUID da declaração para restringir o conjunto de locatários que podem entrar no aplicativo, se aplicável.
iat int, um carimbo de data/hora Unix "Emitido em" indica quando ocorreu a autenticação desse token.
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 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, isso significará que 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.
nbf int, um carimbo de data/hora Unix A declaração "nbf" (não antes) identifica a hora antes da qual o JWT NÃO DEVE ser aceito para processamento.
exp int, um carimbo de data/hora Unix A declaração "exp" (hora de expiração) identifica a hora de expiração ou a hora após ela na qual o JWT não deve ser aceito para processamento. É importante observar que, em determinadas circunstâncias, um recurso pode rejeitar o token antes dessa hora. Por exemplo, se for necessária uma alteração na autenticação ou se uma revogação de token tiver sido detectada.
c_hash String O hash de código é incluído em tokens de ID apenas quando eles são emitidos com um código de autorização OAuth 2.0. Ele pode ser usado para validar a autenticidade de um código de autorização. Para entender como fazer essa validação, confira a especificação do OpenID Connect.
at_hash String O hash do token de acesso é incluído em tokens de ID apenas quando eles são emitidos do ponto de extremidade /authorize com um token de acesso OAuth 2.0. Ele pode ser usado para validar a autenticidade de um token de acesso. Para entender como fazer essa validação, confira a especificação do OpenID Connect. Isso não é retornado nos tokens de ID do ponto de extremidade /token.
aio Cadeia de caracteres opaca Uma declaração interna usada pelo Azure AD para registrar os dados para reutilização de token. Deve ser ignorado.
preferred_username String O nome de usuário principal que representa o usuário. Ele pode ser um endereço de email, número de telefone ou 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 é mutável, esse valor não deve ser usado para tomar decisões de autorização. No entanto, ele pode ser usado para dicas de nome de usuário e na interface do usuário legível como um nome de usuário. O escopo profile é necessário para receber essa declaração. Presente apenas em tokens v 2.0.
email String O email declaração está presente por padrão para contas de convidados que possuem um endereço de email. O aplicativo pode solicitar a declaração de email para usuários gerenciados (aquelas do mesmo locatário do recurso) usando o emaildeclaração opcional. No ponto de extremidade v 2.0, seu aplicativo também pode solicitar o email escopo da OpenID Connect - você não precisa solicitar a declaração opcional e o escopo para obter a declaração.
name String A declaração name fornece um valor legível por humanos que identifica o assunto do token. Não há garantia de que o valor seja exclusivo. Ele pode ser alterado e foi projetado para ser usado apenas para fins de exibição. O escopo profile é necessário para receber essa declaração.
nonce String O nonce corresponde ao parâmetro incluído na solicitação original /authorize para o IDP. Se esses itens não corresponderem, seu aplicativo deverá rejeitar o token.
oid Cadeia de caracteres, um GUID O identificador imutável de um objeto do sistema de identidade da Microsoft, nesse caso, uma conta de usuário. Essa ID identifica exclusivamente o usuário entre os aplicativos - dois aplicativos diferentes autenticando o mesmo usuário receberão o mesmo valor na declaração oid. 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 usuários, o escopo profile é necessário para receber essa declaração. Observe que, se um único usuário existir em vários locatários, o usuário conterá um ID de objeto diferente em cada locatário. Elas são consideradas contas diferentes, mesmo que o usuário faça logon em cada uma delas com as mesmas credenciais. A declaração oid é um GUID e não pode ser reutilizada.
roles Matriz de cadeia de caracteres O conjunto de funções que foram atribuídas ao usuário que está fazendo logon.
rh Cadeia de caracteres opaca Uma declaração interna usada pelo Azure para revalidar tokens. Deve ser ignorado.
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. O assunto é um identificador de paridade e é exclusivo a uma ID de aplicativo específica. Se um único usuário entra em dois aplicativos diferentes usando dois IDs de cliente diferentes, esses aplicativos receberão dois valores diferentes para a declaração do assunto. Isso pode ou não ser desejável, dependendo dos requisitos de arquitetura e de privacidade.
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 String Presente apenas em tokens da 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.
ver Cadeia de caracteres, 1.0 ou 2.0 Indica a versão do id_token.
hasgroups Boolean Se houver algum, sempre verdadeiro, indicando que o usuário pertence a pelo menos um grupo. Usado no lugar da declaração de grupos de JWTs em fluxos de concessão implícita se a declaração completa de grupos ultrapassar o fragmento de URI para além dos limites de extensão da URL (atualmente, 6 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 (confira hasgroups acima), mas ainda muito grandes para o token, será incluído um link para a lista completa de grupos do usuário. 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" }

Para obter mais informações, confira Declaração de excedente de grupos.

Usar declarações para identificar um usuário de forma confiável (ID de objeto e assunto)

Ao identificar um usuário (como ao procurar em um banco de dados ou decidir quais permissões ele tem), é essencial usar informações que permanecerão constantes e exclusivas ao longo do tempo. Os aplicativos herdados às vezes usam campos como o endereço de email, um número de telefone ou o UPN. Ao longo do tempo, todos eles podem mudar e também podem ser reutilizados. Por exemplo, quando um funcionário altera seu nome ou recebe um endereço de email que corresponde ao de um funcionário anterior, ele não representa mais o funcionário. Portanto, é essencial que o aplicativo não use dados que podem ser lidos por pessoas para identificar um usuário. Isso significaria que alguém poderia ler e mudar os dados. Em vez disso, use as declarações fornecidas pelo padrão OIDC ou as declarações de extensão fornecidas pela Microsoft (declarações sub e oid).

Para armazenar corretamente as informações por usuário, use apenas sub ou oid (que são exclusivas como GUIDs), utilizando tid para roteamento ou fragmentação, se necessário. Se você precisar compartilhar dados entre serviços, oid+tid é o melhor, pois todos os aplicativos recebem as mesmas declarações oid e tid de um dado usuário agindo em um determinado locatário. A declaração sub na Plataforma de identidade da Microsoft é "emparelhada". Ela é exclusiva com base em uma combinação do destinatário, do locatário e do usuário do token. Portanto, dois aplicativos que solicitam tokens de ID para um determinado usuário receberão declarações sub diferentes, mas as mesmas declarações oid.

Observação

Não use a declaração idp para armazenar informações sobre um usuário para tentar correlacionar usuários entre locatários. Ela não funcionará, pois as declarações oid e sub de um usuário mudam entre locatários, por design, para garantir que os aplicativos não possam rastrear os usuários entre locatários.

Os cenários de convidado, onde um usuário é hospedado em um locatário e são autenticados em outro, devem tratar os usuários como se fossem totalmente novos para o serviço. Seus documentos e privilégios no locatário da Contoso não devem ser aplicados ao locatário da Fabrikam. Isso é importante para evitar a perda acidental de dados entre locatários e a imposição de ciclos de vida de dados. A remoção de um convidado de um locatário também deve remover o acesso aos dados criados nesse locatário.

Declaração de excedente de grupos

Para garantir que o tamanho do token não exceda os limites de tamanho do cabeçalho HTTP, o Azure AD limita o número de IDs de objeto que ele inclui na declaração groups. Se um usuário for membro de mais grupos do que o limite excedente (150 para tokens SAML, 200 para tokens JWT), 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 consultar a API do Microsoft Graph para recuperar a associação de grupo do usuário.

{
  ...
  "_claim_names": {
   "groups": "src1"
    },
    {
  "_claim_sources": {
    "src1": {
        "endpoint":"[Url to get this user's group membership from]"
        }
       }
     }
  ...
}

Tempos de vida do token de ID

Por padrão, um token de ID é válido por uma hora. Depois de uma hora, o cliente deve adquirir um novo token de ID.

Ajuste o tempo de vida de um token de ID para controlar com que frequência o aplicativo cliente expira a sessão do aplicativo, com que frequência exige que o usuário seja reautenticado de forma silenciosa ou interativa. Para obter mais informações, leia Tempos de vida configuráveis.

Validação de um token de ID

A validação de um token de ID é semelhante à primeira etapa da validação de um token de acesso. O cliente pode verificar se houve alterações no token. Ele também pode validar o emissor para garantir que o emissor correto enviou o token de volta. Como os tokens de ID sempre são JWT, há muitas bibliotecas para validar esses tokens. Recomendamos usar uma delas em vez de fazer isso por conta própria. Observe que somente clientes confidenciais (aqueles com um segredo) devem validar tokens de ID. Aplicativos públicos (o código executado inteiramente em um dispositivo ou rede que você não controla, por exemplo, o navegador de um usuário ou uma rede doméstica) não se beneficiam da validação do token de ID. Isso ocorre porque um usuário mal-intencionado pode interceptar e editar as chaves usadas para validação do token.

Para validar o token manualmente, consulte os detalhes das etapas em validar um token de acesso. As seguintes declarações JWT devem ser validadas no token de ID depois de validar a assinatura no token. Essas declarações também podem ser validadas pela biblioteca de validação de token:

  • Carimbos de data/hora: os carimbos de data/hora iat, nbf, e exp devem estar todos antes ou depois da hora atual, conforme apropriado.
  • Público-alvo: a declaração aud deve corresponder à ID do aplicativo do seu aplicativo.
  • Nonce: a declaração nonce no conteúdo deve corresponder ao parâmetro nonce passado para o ponto de extremidade /authorize durante a solicitação inicial.

Próximas etapas