Ponto de extremidade UserInfo da plataforma de identidade da Microsoft

Como parte do padrão OpenID Connect (OIDC), o ponto de extremidade UserInfo retorna informações sobre um usuário autenticado.

Encontre o ponto de extremidade de configuração .well-known

Você pode encontrar o ponto de extremidade UserInfo programaticamente lendo o userinfo_endpoint campo do documento de configuração OpenID em https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Não recomendamos codificar o ponto de extremidade UserInfo em seus aplicativos. Em vez disso, use o documento de configuração OIDC para localizar o ponto de extremidade em tempo de execução.

O ponto de extremidade UserInfo normalmente é chamado automaticamente por bibliotecas compatíveis com OIDC para obter informações sobre o usuário. A partir da lista de declarações identificadas no padrão OIDC, a plataforma de identidade da Microsoft produz as declarações de nome, declaração de assunto e e-mail quando disponíveis e consentidas.

Em vez disso, considere usar um token de ID

As informações em um token de ID são um superconjunto das informações disponíveis no ponto de extremidade UserInfo. Como você pode obter um token de ID ao mesmo tempo em que recebe um token para chamar o ponto de extremidade UserInfo, sugerimos obter as informações do usuário do token em vez de chamar o ponto de extremidade UserInfo. Usar o token de ID em vez de chamar o ponto de extremidade UserInfo elimina até duas solicitações de rede, reduzindo a latência em seu aplicativo.

Se você precisar de mais detalhes sobre o usuário, como gerente ou cargo, chame a API do Microsoft Graph/user. Você também pode usar declarações opcionais para incluir informações adicionais do usuário em seu ID e tokens de acesso.

Chamando o ponto de extremidade UserInfo

UserInfo é uma API de token de portador OAuth padrão hospedada pelo Microsoft Graph. Chame o ponto de extremidade UserInfo como você chamaria qualquer API do Microsoft Graph usando o token de acesso que seu aplicativo recebeu quando solicitou acesso ao Microsoft Graph. O ponto de extremidade UserInfo retorna uma resposta JSON contendo declarações sobre o usuário.

Permissões

Use as seguintes permissões OIDC para chamar a API UserInfo. A openid reivindicação é necessária, e os escopos profile e email garantem que informações adicionais sejam fornecidas na resposta.

O Microsoft Graph usa um padrão de emissão de token especial que pode afetar a capacidade do seu aplicativo de lê-lo ou validá-lo. Como com qualquer outro token do Microsoft Graph, o token que você recebe aqui pode não ser um JWT e seu aplicativo deve considerá-lo opaco. Se você entrou em um usuário de conta da Microsoft, será um formato de token criptografado. Nenhum desses fatores, no entanto, afeta a capacidade do seu aplicativo de usar o token de acesso em uma solicitação para o ponto de extremidade UserInfo.

Chamando a API

A API UserInfo suporta solicitações GET e POST.

GET or POST /oidc/userinfo HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJub25jZSI6Il…

Resposta UserInfo

{
    "sub": "OLu859SGc2Sr9ZsqbkG-QbeLgJlb41KcdiPoLYNpSFA",
    "name": "Mikah Ollenburg", // all names require the “profile” scope.
    "family_name": " Ollenburg",
    "given_name": "Mikah",
    "picture": "https://graph.microsoft.com/v1.0/me/photo/$value",
    "email": "mikoll@contoso.com" // requires the “email” scope.
}

As declarações mostradas na resposta são todas aquelas que o ponto de extremidade UserInfo pode retornar. Esses valores são os mesmos valores incluídos em um token de ID.

Notas e advertências sobre o ponto de extremidade UserInfo

Não é possível adicionar ou personalizar as informações retornadas pelo ponto de extremidade UserInfo.

Para personalizar as informações retornadas pela plataforma de identidade durante a autenticação e autorização, use o mapeamento de declarações e declarações opcionais para modificar a configuração do token de segurança.

Próximos passos

• Revise o conteúdo dos tokens de ID.
• Personalize o conteúdo de um token de ID usando declarações opcionais.
• Solicite um token de acesso e um token de ID usando o protocolo OAuth 2.