OpenID Connect na plataforma de identidade da Microsoft

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

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

Fluxo de protocolo: Entrada

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

Ativar 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 ele.

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

1. Inicie sessão no centro de administração do Microsoft Entra.
2. Navegue até Aplicativos de identidade>>O aplicativo registra><sua autenticação de aplicativo.>>
3. Em Configurações da plataforma, selecione Adicionar uma plataforma.
4. No painel que se abre, selecione a plataforma apropriada para o seu aplicativo. Por exemplo, selecione Web para um aplicativo Web.
5. Em Redirecionar URIs, adicione o URI de redirecionamento do seu aplicativo. Por exemplo, https://localhost:8080/.
6. Em Concessão implícita e fluxos híbridos, marque a caixa de seleção Tokens de ID (usados para fluxos implícitos e híbridos).

Ou:

1. Selecione Identity>Applications>App registra seu manifesto<> de aplicativo.>>
2. Defina oauth2AllowIdTokenImplicitFlow como true no manifesto do aplicativo de registro do 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 unsupported_response erro semelhante a:

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

Solicitar um token de ID especificando um response_type de é explicado em Enviar a solicitação de id_token entrada mais adiante 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 publicamente contendo os pontos de extremidade OIDC do provedor, declarações suportadas e outros metadados. Os aplicativos cliente podem usar os metadados para descobrir as URLs a serem usadas para autenticação e as chaves de assinatura públicas do serviço de autenticação.

As bibliotecas de autenticação são os consumidores mais comuns do documento de configuração OpenID, que eles usam para descobrir URLs de autenticação, chaves de assinatura públicas 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 solicitações e respostas do ponto de extremidade do documento de configuração OpenID.

Encontre o URI do documento de configuração OpenID do seu aplicativo

Cada registro de aplicativo no Microsoft Entra ID é fornecido um ponto de extremidade acessível publicamente que serve seu documento de configuração OpenID. Para determinar o URI do ponto de extremidade do documento de configuração para seu aplicativo, acrescente o caminho de configuração OpenID conhecido à URL de autoridade do registro do aplicativo.

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

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

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

1. Navegue até Identity>Applications>App registra><seus endpoints de aplicativo.>>
2. Localize o URI em Documento de metadados do OpenID Connect.

Pedido de amostra

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

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

Resposta da amostra

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 em detalhes 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 o pedido de início de sessão

Para autenticar um usuário e solicitar um token de ID para uso em seu aplicativo, direcione seu agente de usuário para o ponto de extremidade /authorize da plataforma de identidade da Microsoft. A solicitação é semelhante à primeira etapa do fluxo do código de autorização OAuth 2.0, mas com estas distinções:

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

Exemplo de pedido de início de sessão (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

Neste ponto, o usuário é solicitado a inserir suas credenciais e concluir a autenticação. A plataforma de identidade da Microsoft verifica se o usuário consentiu com as permissões indicadas no scope parâmetro de consulta. Se o usuário não tiver consentido com nenhuma dessas permissões, a plataforma de identidade da Microsoft solicitará que o usuário consinta com as permissões necessárias. Você pode ler mais sobre permissões, consentimento e aplicativos multilocatário.

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

Resposta com êxito

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 erro também podem ser enviadas para o URI de redirecionamento para que o aplicativo possa manipulá-las, 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 error códigos de erro que podem ser retornados no parâmetro da resposta de erro:

Validar o token de ID

Receber um token de ID em seu aplicativo nem sempre é suficiente para autenticar totalmente o usuário. Também pode ser necessário validar a assinatura do token de ID e verificar suas declarações de acordo com os requisitos do seu aplicativo. Como todos os provedores OpenID, os tokens de ID da plataforma de identidade da Microsoft são JSON Web Tokens (JWTs) assinados usando criptografia de chave pública.

Aplicativos Web e APIs da Web que usam tokens de ID para autorização devem validá-los porque esses aplicativos têm acesso aos dados. No entanto, outros tipos de aplicativo podem não se beneficiar da validação do token de ID. Aplicativos nativos e de página única (SPA), por exemplo, raramente se beneficiam da validação de token de ID porque qualquer entidade com acesso físico ao dispositivo ou navegador pode potencialmente 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 passar por cima da lógica de validação durante a execução do programa.

Se você validar tokens de ID em seu 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 das linguagens de desenvolvimento, estruturas e plataformas.

O que validar em um token de ID

Além de validar a assinatura do token de ID, você deve validar várias de suas declarações, conforme descrito em Validando um token de ID. Consulte também Informações importantes sobre como assinar a substituiçã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 se inscreveu no aplicativo.
• Garantir que o usuário tenha autorização/privilégios adequados
• Garantir que ocorreu uma certa força de autenticação, como a 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, exibição ou armazenamento de dados do aplicativo.

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 da Web, em nome do usuário. Este cenário combina o OpenID Connect para 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 tokens do OpenID Connect é semelhante a este diagrama:

Obter um token de acesso para o ponto de extremidade UserInfo

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

Para obter um token de acesso para o ponto de extremidade OIDC UserInfo, 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 de código de autorização, o fluxo de código de dispositivo ou um token de atualização no lugar de para obter um token de response_type=token acesso para seu aplicativo.

Resposta de token bem-sucedida

Uma resposta bem-sucedida do uso response_mode=form_postde :

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 para o URI de redirecionamento para que o aplicativo possa manipulá-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 de possíveis códigos de erro e respostas recomendadas do cliente, consulte Códigos de erro para erros de ponto de extremidade de autorização.

Quando você tem um código de autorização e um token de ID, você pode entrar no usuário e obter tokens de acesso em seu nome. Para entrar o usuário, você deve validar o token de ID conforme descrito nos tokens de validação. Para obter tokens de acesso, siga as etapas descritas na documentação de fluxo de código OAuth.

Chamando o ponto de extremidade UserInfo

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

Enviar uma solicitação de saída

Para sair de um usuário, execute as duas operações a seguir:

1. Redirecionar o user-agent do usuário para o URI de logout da plataforma de identidade da Microsoft.
2. Limpe os cookies do seu aplicativo ou encerre a sessão do usuário em seu aplicativo.

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

Redirecione o user-agent para o end_session_endpoint conforme mostrado no documento de configuração do OpenID Connect. O end_session_endpoint suporta 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

Fim de sessão ú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 ainda pode estar conectado a outros aplicativos que usam as mesmas contas da Microsoft para autenticação.

Quando um usuário entra em vários aplicativos Web ou SPA registrados nesse diretório (também conhecido como locatário), a saída única permite que esse usuário saia de todos os aplicativos instantaneamente saindo em qualquer um dos aplicativos.

Para habilitar o logon ú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 logout. Quando o usuário efetua logout de um aplicativo, a plataforma de identidade da Microsoft envia uma solicitação HTTP GET para a URL de logout do canal frontal 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 a saída única seja bem-sucedida:

1. Limpe qualquer sessão que identifique o usuário.
2. Os aplicativos devem responder a essa solicitação limpando qualquer sessão que identifique o usuário e retornando uma 200 resposta.

O que é um URL de logout do canal frontal?

Uma URL de logout do canal frontal é onde seu aplicativo Web ou SPA recebe a solicitação de saída do servidor de autenticação Entra e executa a funcionalidade de saída única. Cada aplicativo tem um URL de logout do canal frontal.

Quando você deve definir um URL de logout do canal frontal?

Se você ou seu desenvolvedor determinou que o logon único é necessário para um aplicativo, você deve definir a URL de logout do canal frontal para o registro do aplicativo deste aplicativo. Depois que a URL de logout do canal frontal é definida para o registro do aplicativo deste aplicativo, a plataforma de identidade da Microsoft envia uma solicitação HTTP GET para a URL de logout do canal frontal deste aplicativo quando o usuário conectado tiver saído de outro aplicativo.

Como configurar o logon único usando o recurso de logout do canal frontal

Para usar o recurso de logout do canal frontal para um conjunto de aplicativos, você deve concluir as duas tarefas a seguir:

• Defina a URL de logout do canal frontal 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 logout de canal frontal dedicada.
• Edite o código dos aplicativos para que eles escutem uma solicitação HTTP GET enviada pela plataforma de identidade da Microsoft para a URL de logout do canal frontal 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 logout do canal frontal

O URL de logout do canal frontal deve ser um 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 um URL de logout de canal frontal podem ser, mas não estão limitados a, o seguinte:

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

Próximos passos

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