Tokens de ID da plataforma de identidade da Microsoft
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:
- Protocolos do OAuth 2.0 e do OpenID Connect na plataforma de identidade da Microsoft
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 idp pode 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 email declaraçã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
, eexp
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
- Examine o fluxo de OpenID Connect, que define os protocolos que emitem um token de ID.
- Saiba mais sobre tokens de acesso
- Personalize as declarações JWT no token de ID usando declarações opcionais.