OpenID Connect na plataforma de identidade da Microsoft

O OIDC (OpenID Connect) estende o protocolo de autorização do OAuth 2.0 a ser usado como outro protocolo de autenticação. Você pode usar o OIDC para habilitar o SSO (logon único) entre os aplicativos habilitados para OAuth usando um token de segurança chamado token de ID.

A especificação completa do OIDC está disponível no site da OpenID Foundation em Especificação do OpenID Connect Core 1.0.

Fluxo de protocolo: entrada

O diagrama a seguir mostra o fluxo de entrada básico do OpenID Connect. As etapas no fluxo são descritas em mais detalhes nas seções posteriores do artigo.

Habilitar tokens de ID

O token de ID introduzido pelo OpenID Connect é emitido pelo servidor de autorização, a plataforma de identidade da Microsoft, quando o aplicativo cliente solicita um durante a autenticação do usuário. O token de ID permite que um aplicativo cliente verifique a identidade do usuário e obtenha outras informações (declarações) sobre eles.

Os tokens de ID não são emitidos por padrão para um aplicativo registrado com a plataforma de identidade da Microsoft. Os tokens de ID de um aplicativo são habilitados usando um dos seguintes métodos:

1. Entre no Centro de administração do Microsoft Entra.
2. Navegue até Identidade>Aplicativos>Registros de aplicativo><seu aplicativo>>Autenticação.
3. Em Configurações da plataforma, selecione Adicionar uma plataforma.
4. No painel que é aberto, selecione a plataforma apropriada para seu aplicativo. Por exemplo, selecione Web para um aplicativo Web.
5. Em URIs de Redirecionamento, adicione o URI de redirecionamento do seu aplicativo. Por exemplo, https://localhost:8080/.
6. Na seção Concessão implícita e fluxos híbridos, selecione a caixa de seleção Tokens de ID (usados para fluxos implícitos e híbridos).

Ou:

1. Selecione Identidade>Aplicativos>Registros de aplicativo><seu aplicativo>>Manifesto.
2. Defina oauth2AllowIdTokenImplicitFlow como true no manifesto do aplicativo do registro de aplicativo.

Se os tokens de ID não estiverem habilitados para seu aplicativo e um for solicitado, a plataforma de identidade da Microsoft retornará um erro unsupported_response semelhante a:

O valor fornecido para o parâmetro de entrada 'response_type' não é permitido para este cliente. O valor esperado é "code".

A solicitação de um token de ID especificando um response_type do id_token é explicada em Enviar a solicitação de entrada posteriormente no artigo.

Buscar o documento de configuração do OpenID

Os provedores OpenID, como a plataforma de identidade da Microsoft, fornecem um Documento de configuração do provedor OpenID em um ponto de extremidade acessível ao público contendo os pontos de extremidade OIDC do provedor, declarações compatíveis e outros metadados. Os aplicativos cliente podem usar os metadados para descobrir os URLs a serem usados para autenticação e as chaves públicas de assinatura do serviço de autenticação.

As bibliotecas de autenticação são os consumidores mais comuns do documento de configuração do OpenID, que eles usam para descoberta de URLs de autenticação, chaves de assinatura pública do provedor e outros metadados de serviço. Se uma biblioteca de autenticação for usada em seu aplicativo, você provavelmente não precisará codificar manualmente as solicitações e as respostas do ponto de extremidade do documento de configuração do OpenID.

Localizar o URI do documento de configuração do OpenID do aplicativo

Cada registro de aplicativo no Microsoft Entra ID recebe um ponto de extremidade acessível publicamente que atende ao documento de configuração do OpenID. Para determinar o URI do ponto de extremidade do documento de configuração para o aplicativo, acrescente o caminho de configuração OpenID bem conhecido ao URL de autoridade do registro de aplicativo.

• Caminho do documento de configuração bem conhecido: /.well-known/openid-configuration
• URL de autoridade: https://login.microsoftonline.com/{tenant}/v2.0

O valor de {tenant} varia acordo com o público-alvo de entrada do aplicativo, conforme mostrado na tabela a seguir. A URL de autoridade também varia de acordo com a instância de nuvem.

Para localizar o documento de configuração do OIDC no centro de administração do Microsoft Entra, entre no centro de administração do Microsoft Entra e, em seguida:

1. Navegue até Identidade>Aplicativos>Registros de aplicativo><seu aplicativo>>Pontos de extremidade.
2. Localize o URI no documento de metadados do OpenID Connect.

Solicitação de exemplo

A solicitação a seguir obtém os metadados de configuração do OpenID do ponto de extremidade do documento de configuração do OpenID da autoridade common na nuvem pública do Azure:

GET /common/v2.0/.well-known/openid-configuration
Host: login.microsoftonline.com

Resposta de exemplo

Os metadados de configuração são retornados no formato JSON, conforme mostrado no exemplo a seguir (truncado para brevidade). Os metadados retornados na resposta JSON são descritos detalhadamente na especificação de descoberta do OpenID Connect 1.0.

{
  "authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize",
  "token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "private_key_jwt"
  ],
  "jwks_uri": "https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys",
  "userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo",
  "subject_types_supported": [
      "pairwise"
  ],
  ...
}

Enviar a solicitação de conexão

Para autenticar um usuário e solicitar um token de ID para uso no aplicativo, direcione o agente de usuário para o ponto de extremidade /authorize da plataforma de identidade da Microsoft. A solicitação é semelhante ao primeiro segmento do Fluxo de código de autorização do OAuth 2.0, mas com estas diferenças:

• Inclua o escopo openid no parâmetro scope.
• Especifique id_token no response_type parâmetro.
• Inclua o parâmetro nonce.

Solicitação de entrada de exemplo (quebras de linha incluídas apenas para legibilidade):

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=form_post
&scope=openid
&state=12345
&nonce=678910

Nesse ponto, será solicitado que o usuário insira suas credenciais e conclua a autenticação. A plataforma de identidade da Microsoft verifica se o usuário consentiu com as permissões indicadas no parâmetro de consulta scope. Se o usuário não tiver dado nenhuma dessas permissões, a plataforma de identidade da Microsoft solicitará que o usuário dê as permissões necessárias. Você pode ler mais sobre aplicativos multilocatários, autorização e permissões.

Depois que o usuário se autentica e dá consentimento, a plataforma de identidade da Microsoft retorna uma resposta ao aplicativo no URI de redirecionamento indicado usando o método especificado no parâmetro response_mode.

Resposta bem-sucedida

Uma resposta bem-sucedida quando você usa response_mode=form_post é semelhante a:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345

Resposta de erro

As respostas de erros também podem ser enviadas para o URI de redirecionamento para que o aplicativo possa lidar com elas, por exemplo:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication

Códigos de erro para erros de ponto de extremidade de autorização

A tabela a seguir descreve os códigos de erro que podem ser retornados no parâmetro error da resposta de erro:

Validar o token de ID

Receber um token de ID no aplicativo nem sempre é suficiente para autenticar totalmente o usuário. Talvez também seja necessário validar a assinatura do token de ID e verificar as declarações de acordo com os requisitos do aplicativo. Assim como todos os provedores OpenID, os tokens de ID da plataforma de identidade da Microsoft são JWTs (Tokens Web JSON) assinados usando criptografia por chave pública.

Os aplicativos Web e as APIs Web que usam tokens de ID para autorização devem validá-los porque esses aplicativos obtêm acesso aos dados. No entanto, outros tipos de aplicativo podem não se beneficiar da validação do token de ID. SPAs (aplicativos de página única) e aplicativos nativos, por exemplo, raramente se beneficiam da validação do token de ID, pois qualquer entidade com acesso físico ao dispositivo ou navegador pode ignorar a validação.

Dois exemplos de bypass de validação de token são:

• Fornecer tokens ou chaves falsos modificando o tráfego de rede para o dispositivo
• Depurar o aplicativo e substituir a lógica de validação durante a execução do programa.

Se você validar tokens de ID no aplicativo, recomendamos não fazê-lo manualmente. Em vez disso, use uma biblioteca de validação de token para analisar e validar tokens. As bibliotecas de validação de token estão disponíveis para a maioria dos idiomas, estruturas e plataformas de desenvolvimento.

O que validar em um token de ID

Além de validar a assinatura do token de ID, você deve validar diversas de suas declarações, conforme descrito em Validação de um token de ID. Confira também Informações importantes sobre como assinar a distribuição de chaves.

Várias outras validações são comuns e variam de acordo com o cenário do aplicativo, incluindo:

• Garantir que o usuário/organização tenha assinado para usar o aplicativo.
• Garantir que o usuário tenha autorização/privilégios adequados.
• Garantir uma certa força de autenticação ocorreu, como autenticação multifator.

Depois de validar o token de ID, você pode iniciar uma sessão com o usuário e usar as informações nas declarações do token para personalização do aplicativo, exibição ou armazenamento de dados.

Diagrama de protocolo: aquisição de token de acesso

Muitos aplicativos precisam não apenas entrar em um usuário, mas também acessar um recurso protegido, como uma API Web em nome do usuário. Esse cenário combina o OpenID Connect com o objetivo de obter um token de ID para autenticar o usuário e o OAuth 2.0 para obter um token de acesso para um recurso protegido.

O fluxo completo de entrada e aquisição de token do OpenID Connect é semelhante a este diagrama:

Obter um token de acesso para o ponto de extremidade de UserInfo

Além do token de ID, as informações do usuário autenticado também são disponibilizadas no ponto de extremidade de UserInfo do OIDC.

Para obter um token de acesso para o ponto de extremidade de UserInfo do OIDC, modifique a solicitação de entrada conforme descrito aqui:

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444        // Your app registration's Application (client) ID
&response_type=id_token%20token                       // Requests both an ID token and access token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F       // Your application's redirect URI (URL-encoded)
&response_mode=form_post                              // 'form_post' or 'fragment'
&scope=openid+profile+email                           // 'openid' is required; 'profile' and 'email' provide information in the UserInfo endpoint as they do in an ID token. 
&state=12345                                          // Any value - provided by your app
&nonce=678910                                         // Any value - provided by your app

Você pode usar o fluxo do código de autorização, o fluxo de código do dispositivo ou um token de atualização no lugar do response_type=token para obter um token de acesso para o aplicativo.

Resposta de token bem-sucedida

Uma resposta bem-sucedida usando response_mode=form_post:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
 access_token=eyJ0eXAiOiJKV1QiLCJub25jZSI6I....
 &token_type=Bearer
 &expires_in=3598
 &scope=email+openid+profile
 &id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI....
 &state=12345

Os parâmetros de resposta significam a mesma coisa, independentemente do fluxo usado para adquiri-los.

Resposta de erro

As respostas de erro também podem ser enviadas ao URI de redirecionamento para que o aplicativo possa tratá-las adequadamente:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication

Para obter uma descrição dos possíveis códigos de erro e as respostas recomendadas do cliente, veja Códigos de erro para erros de ponto de extremidade de autorização.

Quando você tiver um código de autorização e um token de ID, poderá conectar o usuário e obter tokens de acesso em seu nome. Para conectar o usuário, você deve validar o token de ID, conforme descrito em validar tokens. Para obter tokens de acesso, siga as etapas descritas na documentação do fluxo de código OAuth.

Chamar o ponto de extremidade UserInfo

Revise a documentação de UserInfo para ver como chamar o ponto de extremidade de UserInfo com esse token.

Enviar uma solicitação de saída

Para desconectar um usuário, execute ambas as seguintes operações:

1. Redirecione o agente de usuário do usuário para o URI de logoff da plataforma de identidade da Microsoft.
2. Limpe os cookies do aplicativo ou encerre a sessão do usuário em seu aplicativo.

Se você não executar nenhuma dessas operações, o usuário poderá permanecer autenticado e não será solicitado a entrar na próxima vez que usar o aplicativo.

Redirecione o usuário-agente para end_session_endpoint conforme mostrado no documento de configuração do OpenID Connect. O end_session_endpoint é compatível com solicitações HTTP GET e POST.

GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F

Logout único

Quando você redireciona o usuário para o end_session_endpoint em um aplicativo, a plataforma de identidade da Microsoft encerra a sessão do usuário para esse aplicativo. No entanto, o usuário pode ainda entrar em outros aplicativos que usam contas da Microsoft para autenticação.

Quando um usuário entra em vários aplicativos Web ou SPA registrados neste diretório (também chamado de locatário), o logout único permite que esse usuário saia de todos os aplicativos instantaneamente ao sair em qualquer um dos aplicativos.

Para habilitar o logoff único para seu aplicativo Entra, você deve usar o recurso de logout do canal frontal do OpenID Connect. Esse recurso permite que um aplicativo notifique outros aplicativos de que o usuário fez logoff. Quando o usuário faz logoff de um aplicativo, a plataforma de identidade da Microsoft envia uma solicitação HTTP GET para a URL de logoff de front-channel de cada aplicativo no qual o usuário está conectado no momento.

Esses aplicativos devem responder a essa solicitação executando as duas ações a seguir para que o logoff único seja bem-sucedido:

1. Limpar qualquer sessão que identifique o usuário.
2. Os aplicativos devem responder a essa solicitação, limpando as sessões que identificam o usuário e retornando uma resposta 200.

O que é uma URL de logoff do front channel?

Um URL de logoff do front channel é onde seu aplicativo Web ou SPA recebe a solicitação de saída do servidor de autenticação do Entra e executa a funcionalidade de logoff único. Cada aplicativo tem uma URL de logoff do front channel.

Quando você deve definir uma URL de logoff do front channel?

Se você ou seu desenvolvedor determinou que o logoff único é necessário para um aplicativo, você deve definir o URL de logoff do front-channel para o registro desse aplicativo. Depois que a URL de logoff do front channel é definida para o registro do aplicativo desse aplicativo, a plataforma de identidade da Microsoft envia uma solicitação HTTP GET para a URL de logoff de front-channel desse aplicativo quando o usuário conectado sai de outro aplicativo.

Como configurar o logoff único usando o recurso de logoff do front channel

Para usar o recurso de logoff do front channel para um conjunto de aplicativos, você deve concluir as duas tarefas a seguir:

• Defina a URL de logoff do front channel no centro de administração do Microsoft Entra para todos os aplicativos que devem ser desconectados simultaneamente. Cada aplicativo normalmente tem sua própria URL de logoff do front channel dedicada.
• Edite o código dos aplicativos para que eles ouçam uma solicitação HTTP GET enviada pela plataforma de identidade da Microsoft para a URL de logoff do front channel e respondam a essa solicitação limpando qualquer sessão que identifique o usuário e retornando uma resposta 200.

Como escolher um URL de logoff do front channel

A URL de logoff do front channel deve ser uma URL capaz de receber e responder a solicitações HTTP GET e deve ser capaz de limpar qualquer sessão que identifique o usuário. Exemplos de uma URL de logoff do front channel podem ser, mas não estão limitados a, os seguintes:

• https://example.com/frontchannel_loout
• https://example.com/signout
• https://example.com/logout

Próximas etapas

• Examine a documentação do ponto de extremidade de UserInfo.
• Preencha valores de declaração em um token com os dados de sistemas locais.
• Inclua as próprias declarações em tokens.