Compartilhar via


Ponto de extremidade UserInfo da plataforma de identidade da Microsoft

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

Encontrar o ponto de extremidade de configuração conhecido

Você pode encontrar o ponto de extremidade UserInfo programaticamente lendo o campo userinfo_endpoint 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 nos seus aplicativos. Em vez disso, use o documento de configuração do OIDC para localizar o ponto de extremidade no runtime.

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

Considere usar um token de ID em vez disso

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 que obtém 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 no seu aplicativo.

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

Chamar 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 faria com qualquer API do Microsoft Graph usando o token de acesso que o aplicativo recebeu quando ele solicitou acesso ao Microsoft Graph. O ponto de extremidade UserInfo retorna uma resposta JSON que contém declarações sobre o usuário.

Permissões

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

Tipo de permissão Permissões
Delegada (conta corporativa ou de estudante) openid (obrigatório), profile, email
Delegada (conta pessoal da Microsoft) openid (obrigatório), profile, email
Aplicativo Não aplicável

Dica

Copie essa URL no navegador para obter um token de acesso para o ponto de extremidade UserInfo e um token de ID. Substitua a ID do cliente e o URI de redirecionamento por valores de um registro de aplicativo.

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=<yourClientID>&response_type=token+id_token&redirect_uri=<YourRedirectUri>&scope=user.read+openid+profile+email&response_mode=fragment&state=12345&nonce=678910

Você pode usar o token de acesso retornado na consulta na próxima seção.

O Microsoft Graph usa um padrão de emissão de token especial que pode afetar a capacidade do aplicativo de lê-lo ou validá-lo. Assim como com qualquer outro token do Microsoft Graph, o token recebido aqui pode não ser um JWT e o seu aplicativo deve considerá-lo opaco. Se você entrar em um conta Microsoft, ele 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 é compatível com solicitações GET e POST.

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

Resposta do 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.

Observações e advertências sobre o ponto de extremidade UserInfo

Você não pode adicionar nem 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 a autorização, use mapeamento de declarações e declarações opcionais para modificar a configuração do token de segurança.

Próximas etapas