Plataforma Microsoft Identity e o protocolo OpenID ConnectMicrosoft identity platform and OpenID Connect protocol

O OpenID Connect é um protocolo de autenticação baseado no OAuth 2.0 que você pode usar para assinar com segurança em um usuário a um aplicativo Web.OpenID Connect is an authentication protocol built on OAuth 2.0 that you can use to securely sign in a user to a web application. Quando você usa a implementação do ponto de extremidade da plataforma de identidade da Microsoft do OpenID Connect, você pode adicionar entrada e acesso à API para seus aplicativos baseados na Web.When you use the Microsoft identity platform endpoint's implementation of OpenID Connect, you can add sign-in and API access to your web-based apps. Este artigo mostra como fazer isso independentemente da linguagem e descreve como enviar e receber mensagens HTTP em usar nenhuma das bibliotecas de software livre da Microsoft.This article shows how to do this independent of language and describes how to send and receive HTTP messages without using any Microsoft open-source libraries.

Observação

O ponto de extremidade da plataforma de identidade da Microsoft não dá suporte a todos os cenários e recursos do Azure Active Directory (Azure AD).The Microsoft identity platform endpoint does not support all Azure Active Directory (Azure AD) scenarios and features. Para determinar se você deve usar o ponto de extremidade da plataforma de identidade da Microsoft, leia sobre as limitações da plataforma de identidade da Microsoft.To determine whether you should use the Microsoft identity platform endpoint, read about Microsoft identity platform limitations.

O OpenID Connect estende o protocolo de autorização do OAuth 2.0 para uso como um protocolo de autenticação, o que permite executar o logon único usando o OAuth.OpenID Connect extends the OAuth 2.0 authorization protocol to use as an authentication protocol, so that you can do single sign-on using OAuth. O OpenID Connect apresenta o conceito de um token de ID, que é um token de segurança que permite ao cliente verificar a identidade do usuário.OpenID Connect introduces the concept of an ID token, which is a security token that allows the client to verify the identity of the user. O token de ID também obtém informações de perfil básico sobre o usuário.The ID token also gets basic profile information about the user. Como o OpenID Connect estende o OAuth 2.0, os aplicativos podem adquirir access_tokens com segurança, os quais podem ser usados para acessar os recursos protegidos por um servidor de autorização.Because OpenID Connect extends OAuth 2.0, apps can securely acquire access tokens, which can be used to access resources that are secured by an authorization server. O ponto de extremidade da plataforma Microsoft Identity também permite que aplicativos de terceiros registrados no Azure AD emitam tokens de acesso para recursos protegidos, como APIs Web.The Microsoft identity platform endpoint also allows third-party apps that are registered with Azure AD to issue access tokens for secured resources such as Web APIs. Para obter mais informações sobre como configurar um aplicativo para emitir tokens de acesso, consulte como registrar um aplicativo com o ponto de extremidade da plataforma de identidade da Microsoft.For more information about how to set up an application to issue access tokens, see How to register an app with the Microsoft identity platform endpoint. É recomendável que você use o OpenID Connect se estiver criando um aplicativo Web que fica hospedado em um servidor e é acessado por meio de um navegador.We recommend that you use OpenID Connect if you are building a web application that is hosted on a server and accessed via a browser.

Diagrama de protocolo: ConexãoProtocol diagram: Sign-in

O fluxo de entrada mais básico tem as etapas mostradas no diagrama seguinte.The most basic sign-in flow has the steps shown in the next diagram. Cada etapa é descrita detalhadamente neste artigo.Each step is described in detail in this article.

Protocolo OpenID Connect: Conexão

Obter o documento de metadados do OpenID ConnectFetch the OpenID Connect metadata document

O OpenID Connect descreve um documento de metadados que contém a maioria das informações necessárias para que um aplicativo faça logon.OpenID Connect describes a metadata document that contains most of the information required for an app to do sign-in. Isso inclui informações como as URLs a serem usadas e o local das chaves de assinatura públicas do serviço.This includes information such as the URLs to use and the location of the service's public signing keys. Para o ponto de extremidade da plataforma de identidade da Microsoft, este é o documento de metadados do OpenID Connect que você deve usar:For the Microsoft identity platform endpoint, this is the OpenID Connect metadata document you should use:

https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration

Dica

Experimente.Try it! Clique em https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration para ver o common configuração locatários.Click https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration to see the common tenants configuration.

O {tenant} pode ter um de quatro valores:The {tenant} can take one of four values:

ValorValue DescriçãoDescription
common Os usuários com um conta Microsoft pessoal e uma conta corporativa ou de estudante do Azure AD podem entrar no aplicativo.Users with both a personal Microsoft account and a work or school account from Azure AD can sign in to the application.
organizations Somente os usuários com contas corporativas ou de estudante do Azure AD podem se conectar ao aplicativo.Only users with work or school accounts from Azure AD can sign in to the application.
consumers Somente os usuários com uma conta pessoal da Microsoft podem entrar no aplicativo.Only users with a personal Microsoft account can sign in to the application.
8eaef023-2b34-4da1-9baa-8bc8c9d6a490 ou contoso.onmicrosoft.com8eaef023-2b34-4da1-9baa-8bc8c9d6a490 or contoso.onmicrosoft.com Somente os usuários de um locatário específico do Azure AD (sejam eles Membros no diretório com uma conta corporativa ou de estudante ou convidados no diretório com um conta Microsoft pessoal) podem entrar no aplicativo.Only users from a specific Azure AD tenant (whether they are members in the directory with a work or school account, or they are guests in the directory with a personal Microsoft account) can sign in to the application. É possível usar o nome de domínio amigável do locatário do Azure AD ou o identificador GUID de locatário.Either the friendly domain name of the Azure AD tenant or the tenant's GUID identifier can be used. Você também pode usar o locatário do consumidor 9188040d-6c67-4c5b-b112-36a304b66dad, no lugar consumers do locatário.You can also use the consumer tenant, 9188040d-6c67-4c5b-b112-36a304b66dad, in place of the consumers tenant.

Os metadados são um documento JSON (JavaScript Object Notation) simples.The metadata is a simple JavaScript Object Notation (JSON) document. Veja o snippet a seguir para obter um exemplo.See the following snippet for an example. O conteúdo do snippet é totalmente descrito na especificação do OpenID Connect.The snippet's contents are fully described in the OpenID Connect specification.

{
  "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",

  ...

}

Se seu aplicativo tiver chaves de assinatura personalizadas como resultado do uso do recurso de mapeamento de declarações , você deverá acrescentar appid um parâmetro de consulta que contém a ID do aplicativo para jwks_uri começar a apontar para as informações de chave de assinatura do aplicativo.If your app has custom signing keys as a result of using the claims-mapping feature, you must append an appid query parameter containing the app ID in order to get a jwks_uri pointing to your app's signing key information. Por exemplo: https://login.microsoftonline.com/{tenant}/.well-known/v2.0/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e contém um jwks_uri de https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.For example: https://login.microsoftonline.com/{tenant}/.well-known/v2.0/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e contains a jwks_uri of https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

Normalmente, você usaria este documento de metadados para configurar uma biblioteca do OpenID Connect ou o SDK. A biblioteca usaria os metadados para fazer seu trabalho.Typically, you would use this metadata document to configure an OpenID Connect library or SDK; the library would use the metadata to do its work. No entanto, se você não estiver usando uma biblioteca pré-criada do OpenID Connect, poderá seguir as etapas no restante deste artigo para fazer logon em um aplicativo Web usando o ponto de extremidade da plataforma Microsoft Identity.However, if you're not using a pre-built OpenID Connect library, you can follow the steps in the remainder of this article to do sign-in in a web app by using the Microsoft identity platform endpoint.

Enviar a solicitação de conexãoSend the sign-in request

Quando o aplicativo Web precisa autenticar o usuário, ele pode direcionar o usuário para o ponto de extremidade /authorize .When your web app needs to authenticate the user, it can direct the user to the /authorize endpoint. Essa solicitação é semelhante ao primeiro segmento do Fluxo de código de autorização do OAuth 2.0, com estas diferenças importantes:This request is similar to the first leg of the OAuth 2.0 authorization code flow, with these important distinctions:

  • A solicitação deve incluir o escopo openid no parâmetro scope.The request must include the openid scope in the scope parameter.
  • O parâmetro response_type deve incluir id_token.The response_type parameter must include id_token.
  • A solicitação deve incluir o parâmetro nonce .The request must include the nonce parameter.

Importante

Para solicitar com êxito um token de ID do ponto de extremidade/Authorization, o registro do aplicativo no portal de registro deve ter a concessão implícita de id_tokens habilitada na guia Autenticação (que define oauth2AllowIdTokenImplicitFlow o sinalizador no manifesto do aplicativo truepara).In order to successfully request an ID token from the /authorization endpoint, the app registration in the registration portal must have the implicit grant of id_tokens enabled in the Authentication tab (which sets the oauth2AllowIdTokenImplicitFlow flag in the application manifest to true). Se não estiver habilitado, um unsupported_response erro será retornado: "O valor fornecido para o parâmetro de entrada ' response_type ' não é permitido para este cliente.If it isn't enabled, an unsupported_response error will be returned: "The provided value for the input parameter 'response_type' isn't allowed for this client. O valor esperado é 'code' "Expected value is 'code'"

Por exemplo:For example:

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=form_post
&scope=openid
&state=12345
&nonce=678910

Dica

Clique no link a seguir para executar essa solicitação.Click the following link to execute this request. Depois de entrar, seu navegador será redirecionado para https://localhost/myapp/, com um token de ID na barra de endereços.After you sign in, your browser will be redirected to https://localhost/myapp/, with an ID token in the address bar. Observe que esta solicitação usa response_mode=fragment (somente para fins de demonstração).Note that this request uses response_mode=fragment (for demonstration purposes only). É recomendável usar o response_mode=form_post.We recommend that you use response_mode=form_post. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

ParâmetroParameter CondiçãoCondition DescriçãoDescription
tenant NecessárioRequired Você pode usar o valor {tenant} no caminho da solicitação para controlar quem pode entrar no aplicativo.You can use the {tenant} value in the path of the request to control who can sign in to the application. Os valores permitidos são common, organizations, consumers e identificadores de locatário.The allowed values are common, organizations, consumers, and tenant identifiers. Para saber mais, veja noções básicas de protocolo.For more information, see protocol basics.
client_id NecessárioRequired A ID do aplicativo (cliente) que a portal do Azure – registros de aplicativo experiência atribuída ao seu aplicativo.The Application (client) ID that the Azure portal – App registrations experience assigned to your app.
response_type NecessárioRequired Deve incluir id_token para conexão do OpenID Connect.Must include id_token for OpenID Connect sign-in. Ele também pode incluir outros response_type valores, como code.It might also include other response_type values, such as code.
redirect_uri RecomendadoRecommended O URI de redirecionamento do seu aplicativo, onde as respostas de autenticação podem ser enviadas e recebidas pelo aplicativo.The redirect URI of your app, where authentication responses can be sent and received by your app. Ele deve corresponder exatamente a um dos URIs de redirecionamento que você registrou no portal, com exceção de que ele deve ser codificado por URL.It must exactly match one of the redirect URIs you registered in the portal, except that it must be URL encoded. Se não estiver presente, o ponto de extremidade selecionará um redirect_uri registrado aleatoriamente para enviar o usuário de volta para o.If not present, the endpoint will pick one registered redirect_uri at random to send the user back to.
scope NecessárioRequired Uma lista de escopos separados por espaços.A space-separated list of scopes. Para o OpenID Connect, é necessário incluir o escopo openid, que é traduzido para a permissão "Fazer seu logon" na interface do usuário de consentimento.For OpenID Connect, it must include the scope openid, which translates to the "Sign you in" permission in the consent UI. Você também pode incluir outros escopos nesta solicitação para solicitar o consentimento.You might also include other scopes in this request for requesting consent.
nonce NecessárioRequired Um valor incluído na solicitação, gerado pelo aplicativo, que será incluído no valor do id_token resultante como uma declaração.A value included in the request, generated by the app, that will be included in the resulting id_token value as a claim. O aplicativo pode verificar esse valor para reduzir os ataques de reprodução de token.The app can verify this value to mitigate token replay attacks. Normalmente, o valor é uma cadeia de caracteres aleatória e exclusiva que pode ser usada para identificar a origem da solicitação.The value typically is a randomized, unique string that can be used to identify the origin of the request.
response_mode RecomendadoRecommended Especifica o método que deve ser usado para enviar o authorization_code resultante de volta ao aplicativo.Specifies the method that should be used to send the resulting authorization code back to your app. Pode ser form_post ou fragment.Can be form_post or fragment. Para aplicativos Web, é recomendável usar response_mode=form_post para garantir a transferência mais segura de tokens para seu aplicativo.For web applications, we recommend using response_mode=form_post, to ensure the most secure transfer of tokens to your application.
state RecomendadoRecommended Um valor incluído na solicitação também será retornado na resposta do token.A value included in the request that also will be returned in the token response. Pode ser uma cadeia de caracteres de qualquer conteúdo desejado.It can be a string of any content you want. Um valor exclusivo gerado aleatoriamente que normalmente é usado para impedir ataques de solicitação entre sites forjada.A randomly generated unique value typically is used to prevent cross-site request forgery attacks. O estado também é usado para codificar as informações sobre o estado do usuário no aplicativo antes da solicitação de autenticação ocorrida, como a página ou exibição em que ele estava.The state also is used to encode information about the user's state in the app before the authentication request occurred, such as the page or view the user was on.
prompt OpcionalOptional Indica o tipo de interação do usuário que é necessário.Indicates the type of user interaction that is required. Os únicos valores válidos no momento são login, none, e consent.The only valid values at this time are login, none, and consent. A declaração prompt=login força o usuário a digitar suas credenciais na solicitação, o que nega o logon único.The prompt=login claim forces the user to enter their credentials on that request, which negates single sign-on. A declaração prompt=none é o oposto.The prompt=none claim is the opposite. Essa declaração garante que o usuário não seja apresentado a nenhum prompt interativo em.This claim ensures that the user isn't presented with any interactive prompt at. Se a solicitação não puder ser concluída silenciosamente por meio do logon único, o ponto de extremidade da plataforma de identidade da Microsoft retornará um erro.If the request can't be completed silently via single sign-on, the Microsoft identity platform endpoint returns an error. A declaração prompt=consent aciona a caixa de diálogo de consentimento de OAuth depois que o usuário faz logon.The prompt=consent claim triggers the OAuth consent dialog after the user signs in. A caixa de diálogo pede ao usuário para conceder permissões para o aplicativo.The dialog asks the user to grant permissions to the app.
login_hint OpcionalOptional Você pode usar esse parâmetro para preencher previamente o campo de nome de usuário/endereço de email da página de entrada do usuário, se você souber o nome de usuário com antecedência.You can use this parameter to pre-fill the username and email address field of the sign-in page for the user, if you know the username ahead of time. Muitas vezes, os aplicativos usam esse parâmetro durante a reautenticação, depois de já terem extraído o nome de usuário de uma entrada anterior usando a declaração preferred_username.Often, apps use this parameter during reauthentication, after already extracting the username from an earlier sign-in by using the preferred_username claim.
domain_hint OpcionalOptional O realm do usuário em um diretório federado.The realm of the user in a federated directory. Isso ignora o processo de descoberta baseado em email que o usuário passa na página de entrada, para uma experiência de usuário um pouco mais simplificada.This skips the email-based discovery process that the user goes through on the sign-in page, for a slightly more streamlined user experience. Para locatários federados por meio de um diretório local como AD FS, isso geralmente resulta em uma entrada direta devido à sessão de logon existente.For tenants that are federated through an on-premises directory like AD FS, this often results in a seamless sign-in because of the existing login session.

Nesse ponto, será solicitado que o usuário insira suas credenciais e conclua a autenticação.At this point, the user is prompted to enter their credentials and complete the authentication. O ponto de extremidade da plataforma de identidade da Microsoft verifica se o usuário consentiu nas permissões indicadas no parâmetro de scope consulta.The Microsoft identity platform endpoint verifies that the user has consented to the permissions indicated in the scope query parameter. Se o usuário não tiver consentido nenhuma dessas permissões, o ponto de extremidade da plataforma de identidade da Microsoft solicitará que o usuário consentisse nas permissões necessárias.If the user hasn't consented to any of those permissions, the Microsoft identity platform endpoint prompts the user to consent to the required permissions. Você pode ler mais sobre permissões, consentimento e aplicativos de vários locatários.You can read more about permissions, consent, and multi-tenant apps.

Depois que o usuário é autenticado e concede consentimento, o ponto de extremidade da 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.After the user authenticates and grants consent, the Microsoft identity platform endpoint returns a response to your app at the indicated redirect URI by using the method specified in the response_mode parameter.

Resposta bem-sucedidaSuccessful response

Uma resposta bem-sucedida ao usar response_mode=form_post tem esta aparência:A successful response when you use response_mode=form_post looks like this:

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

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345
ParâmetroParameter DescriçãoDescription
id_token O token de ID que o aplicativo solicitou.The ID token that the app requested. Você pode usar o parâmetro id_token para verificar a identidade do usuário e iniciar uma sessão com o usuário.You can use the id_token parameter to verify the user's identity and begin a session with the user. Para obter mais informações sobre tokens de identificação e seus conteúdos, consulte a referência do id_tokens.For more information about ID tokens and their contents, see the id_tokens reference.
state Se um parâmetro state estiver incluído na solicitação, o mesmo valor deverá aparecer na resposta.If a state parameter is included in the request, the same value should appear in the response. O aplicativo deve verificar se os valores de estado na solicitação e na resposta são idênticos.The app should verify that the state values in the request and response are identical.

Resposta de erroError response

As respostas de erros também podem ser enviadas para o URI de redirecionamento para que o aplicativo possa lidar com elas.Error responses might also be sent to the redirect URI so that the app can handle them. Uma resposta de erro tem esta aparência:An error response looks like this:

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

error=access_denied&error_description=the+user+canceled+the+authentication
ParâmetroParameter DescriçãoDescription
error Uma cadeia de caracteres de códigos de erro que você pode usar para classificar tipos de erro que ocorrem e para responder aos erros.An error code string that you can use to classify types of errors that occur, and to react to errors.
error_description Uma mensagem de erro específica que pode ajudar você a identificar a causa raiz de um erro de autenticação.A specific error message that can help you identify the root cause of an authentication error.

Códigos de erro para erros de ponto de extremidade de autorizaçãoError codes for authorization endpoint errors

A tabela a seguir descreve os códigos de erro que podem ser retornados no parâmetro error da resposta de erro:The following table describes error codes that can be returned in the error parameter of the error response:

Código de erroError code DescriçãoDescription Ação do clienteClient action
invalid_request Erro de protocolo, como um parâmetro obrigatório ausente.Protocol error, such as a missing, required parameter. Corrija e reenvie a solicitação.Fix and resubmit the request. Esse é um erro de desenvolvimento normalmente identificado durante os testes iniciais.This is a development error that typically is caught during initial testing.
unauthorized_client O aplicativo cliente não pode solicitar um código de autorização.The client application can't request an authorization code. Isso geralmente ocorre quando o aplicativo cliente não está registrado no Azure AD ou não é adicionado ao locatário do Azure AD do usuário.This usually occurs when the client application isn't registered in Azure AD or isn't added to the user's Azure AD tenant. O aplicativo pode solicitar que o usuário instale o aplicativo e o adicione ao Azure AD.The application can prompt the user with instructions to install the application and add it to Azure AD.
access_denied O consentimento negado pelo proprietário do recurso.The resource owner denied consent. O aplicativo cliente pode notificar o usuário de que ele não pode continuar, a menos que o usuário consentisse.The client application can notify the user that it can't proceed unless the user consents.
unsupported_response_type O servidor de autorização não dá suporta ao tipo de resposta na solicitação.The authorization server does not support the response type in the request. Corrija e reenvie a solicitação.Fix and resubmit the request. Esse é um erro de desenvolvimento normalmente identificado durante os testes iniciais.This is a development error that typically is caught during initial testing.
server_error O servidor encontrou um erro inesperado.The server encountered an unexpected error. Tente novamente a solicitação.Retry the request. Esses erros podem resultar de condições temporárias.These errors can result from temporary conditions. O aplicativo cliente pode explicar ao usuário que sua resposta está atrasada devido a um erro temporário.The client application might explain to the user that its response is delayed because of a temporary error.
temporarily_unavailable O servidor está temporariamente muito ocupado para tratar da solicitação.The server is temporarily too busy to handle the request. Tente novamente a solicitação.Retry the request. O aplicativo cliente pode explicar ao usuário que sua resposta está atrasada devido a uma condição temporária.The client application might explain to the user that its response is delayed because of a temporary condition.
invalid_resource O recurso de destino é inválido porque não existe, o Azure AD não consegue encontrá-lo ou não está configurado corretamente.The target resource is invalid because either it does not exist, Azure AD can't find it, or it isn't correctly configured. Isso indica que o recurso, se ele existe, não foi configurado no locatário.This indicates that the resource, if it exists, hasn't been configured in the tenant. O aplicativo pode solicitar que o usuário instale o aplicativo e o adicione ao Azure AD.The application can prompt the user with instructions for installing the application and adding it to Azure AD.

Validar o token de IDValidate the ID token

Apenas receber um id_token não é suficiente para autenticar o usuário; Você deve validar a assinatura id_token's e verificar as declarações no token de acordo com os requisitos do aplicativo.Just receiving an id_token isn't sufficient to authenticate the user; you must validate the id_token's signature and verify the claims in the token per your app's requirements. O ponto de extremidade da plataforma de identidade da Microsoft usa JWTs (tokens Web JSON) e criptografia de chave pública para assinar tokens e verificar se eles são válidos.The Microsoft identity platform endpoint uses JSON Web Tokens (JWTs) and public key cryptography to sign tokens and verify that they're valid.

Você pode optar por validar o id_token no código do cliente, mas uma prática comum é enviar o id_token para um servidor de back-end e fazer a validação lá.You can choose to validate the id_token in client code, but a common practice is to send the id_token to a backend server and do the validation there. Depois de validar a assinatura do id_token, há algumas declarações que serão necessárias para verificar.Once you've validated the signature of the id_token, there are a few claims you'll be required to verify. Consulte a referência do id_token para obter mais informações, incluindo Validação de tokens e Informações importantes sobre substituição de chave de assinatura.See the id_token reference for more information, including Validating Tokens and Important Information About Signing Key Rollover. Há, pelo menos, uma disponível para a maioria das linguagens e plataformas.We recommend making use of a library for parsing and validating tokens - there is at least one available for most languages and platforms.

Talvez você também queira validar declarações adicionais, dependendo do cenário.You may also wish to validate additional claims depending on your scenario. Algumas validações comuns incluem:Some common validations include:

  • Garantir que o usuário/organização tenha assinado para usar o aplicativo.Ensuring the user/organization has signed up for the app.
  • Garantir que o usuário tenha autorização/privilégios adequados.Ensuring the user has proper authorization/privileges
  • Garantir que uma determinada intensidade de autenticação tenha ocorrido, como autenticação multifator.Ensuring a certain strength of authentication has occurred, such as multi-factor authentication.

Depois de validar o id_token, você pode iniciar uma sessão com o usuário e usar as declarações no id_token para obter informações sobre o usuário em seu aplicativo.Once you have validated the id_token, you can begin a session with the user and use the claims in the id_token to obtain information about the user in your app. Essas informações podem ser usadas para exibição, registros, personalização etc.This information can be used for display, records, personalization, etc.

Enviar uma solicitação de saídaSend a sign-out request

Quando você deseja desconectar o usuário do aplicativo, não é suficiente limpar os cookies do aplicativo ou encerrar a sessão do usuário.When you want to sign out the user from your app, it isn't sufficient to clear your app's cookies or otherwise end the user's session. Você também deve redirecionar o usuário para o ponto de extremidade da plataforma de identidade da Microsoft para sair. Se você não fizer isso, o usuário se reautenticará em seu aplicativo sem inserir suas credenciais novamente, pois ele terá uma sessão de logon único válida com o ponto de extremidade da plataforma de identidade da Microsoft.You must also redirect the user to the Microsoft identity platform endpoint to sign out. If you don't do this, the user reauthenticates to your app without entering their credentials again, because they will have a valid single sign-in session with the Microsoft identity platform endpoint.

Você pode redirecionar o usuário para o end_session_endpoint listado no documento de metadados do OpenID Connect:You can redirect the user to the end_session_endpoint listed in the OpenID Connect metadata document:

GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
ParâmetroParameter CondiçãoCondition DescriçãoDescription
post_logout_redirect_uri RecomendadoRecommended A URL para a qual o usuário é redirecionado após o logout bem-sucedido. Se o parâmetro não estiver incluído, o usuário será mostrado uma mensagem genérica gerada pelo ponto de extremidade da plataforma Microsoft Identity.The URL that the user is redirected to after successfully signing out. If the parameter isn't included, the user is shown a generic message that's generated by the Microsoft identity platform endpoint. Esta URL deve corresponder exatamente a um redirecionamento de URIs registrado para seu aplicativo no portal de registro de aplicativo.This URL must match one of the redirect URIs registered for your application in the app registration portal.

Logout únicoSingle sign-out

Quando você redireciona o usuário para o end_session_endpoint, o ponto de extremidade da plataforma de identidade da Microsoft limpa a sessão do usuário no navegador.When you redirect the user to the end_session_endpoint, the Microsoft identity platform endpoint clears the user's session from the browser. No entanto, o usuário pode ainda entrar em outros aplicativos que usam contas da Microsoft para autenticação.However, the user may still be signed in to other applications that use Microsoft accounts for authentication. Para permitir que esses aplicativos desconectem o usuário simultaneamente, o ponto de extremidade da plataforma de identidade da Microsoft envia uma LogoutUrl solicitação HTTP Get para o registrado de todos os aplicativos aos quais o usuário está conectado no momento.To enable those applications to sign the user out simultaneously, the Microsoft identity platform endpoint sends an HTTP GET request to the registered LogoutUrl of all the applications that the user is currently signed in to. Os aplicativos devem responder a essa solicitação, limpando as sessões que identificam o usuário e retornando uma resposta 200.Applications must respond to this request by clearing any session that identifies the user and returning a 200 response. Se você deseja dar suporte um logout único em seu aplicativo, deve implementar um LogoutUrl no código do aplicativo.If you wish to support single sign-out in your application, you must implement such a LogoutUrl in your application's code. Você pode configurar a LogoutUrl no portal de registro do aplicativo.You can set the LogoutUrl from the app registration portal.

Diagrama de protocolo: aquisição de token de acessoProtocol diagram: Access token acquisition

Muitos aplicativos Web precisam não apenas conectar o usuário, mas acessar um serviço Web em nome desse usuário usando o OAuth.Many web apps need to not only sign the user in, but also to access a web service on behalf of the user by using OAuth. Esse cenário combina o OpenID Connect para autenticação de usuário enquanto obtém simultaneamente um código de autorização que pode ser usado para obter tokens de acesso se você estiver usando o fluxo do código de autorização do OAuth.This scenario combines OpenID Connect for user authentication while simultaneously getting an authorization code that you can use to get access tokens if you are using the OAuth authorization code flow.

O fluxo total de entrada e de aquisição de token do OpenID Connect é similar ao próximo diagrama.The full OpenID Connect sign-in and token acquisition flow looks similar to the next diagram. Descrevemos cada etapa detalhadamente nas próximas seções do artigo.We describe each step in detail in the next sections of the article.

Protocolo OpenID Connect: aquisição de token

Obter tokens de acessoGet access tokens

Para obter tokens de acesso, modifique a solicitação de entrada:To acquire access tokens, modify the sign-in request:

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e        // Your registered Application ID
&response_type=id_token%20code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F       // Your registered redirect URI, URL encoded
&response_mode=form_post                              // 'form_post' or 'fragment'
&scope=openid%20                                      // Include both 'openid' and scopes that your app needs  
offline_access%20                                         
https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&state=12345                                          // Any value, provided by your app
&nonce=678910                                         // Any value, provided by your app

Dica

Clique no link a seguir para executar essa solicitação.Click the following link to execute this request. Depois de entrar, seu navegador será redirecionado para https://localhost/myapp/, com um token de ID e um código na barra de endereços.After you sign in, your browser is redirected to https://localhost/myapp/, with an ID token and a code in the address bar. Observe que esta solicitação usa response_mode=fragment somente para fins de demonstração.Note that this request uses response_mode=fragment for demonstration purposes only. É recomendável usar o response_mode=form_post.We recommend that you use response_mode=form_post. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

Ao incluir escopos de permissão na solicitação e usando response_type=id_token code, o ponto de extremidade da plataforma de identidade da Microsoft garante que o usuário tenha consentido as permissões scope indicadas no parâmetro de consulta.By including permission scopes in the request and by using response_type=id_token code, the Microsoft identity platform endpoint ensures that the user has consented to the permissions indicated in the scope query parameter. Ele retorna um código de autorização para seu aplicativo para o exchange para um token de acesso.It returns an authorization code to your app to exchange for an access token.

Resposta bem-sucedidaSuccessful response

Uma resposta bem-sucedida do uso do response_mode=form_post tem a seguinte aparência:A successful response from using response_mode=form_post looks like this:

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

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...&state=12345
ParâmetroParameter DescriçãoDescription
id_token O token de ID que o aplicativo solicitou.The ID token that the app requested. Você pode usar o token de ID para verificar a identidade do usuário e iniciar uma sessão com o usuário.You can use the ID token to verify the user's identity and begin a session with the user. Você encontrará mais detalhes sobre tokens de ID e seu conteúdo na referência do id_tokens.You'll find more details about ID tokens and their contents in the id_tokens reference.
code O código de autorização que o aplicativo solicitou.The authorization code that the app requested. O aplicativo pode usar o código de autorização para solicitar um token de acesso para o recurso de destino.The app can use the authorization code to request an access token for the target resource. Um código de autorização é de curta duração.An authorization code is short-lived. Normalmente, um código de autorização expira em cerca de 10 minutos.Typically, an authorization code expires in about 10 minutes.
state Se um parâmetro de estado estiver incluído na solicitação, o mesmo valor deverá aparecer na resposta.If a state parameter is included in the request, the same value should appear in the response. O aplicativo deve verificar se os valores de estado na solicitação e na resposta são idênticos.The app should verify that the state values in the request and response are identical.

Resposta de erroError response

As respostas de erro também podem ser enviadas ao URI de redirecionamento para que o aplicativo possa tratá-las adequadamente.Error responses might also be sent to the redirect URI so that the app can handle them appropriately. Uma resposta de erro tem esta aparência:An error response looks like this:

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

error=access_denied&error_description=the+user+canceled+the+authentication
ParâmetroParameter DescriçãoDescription
error Uma cadeia de caracteres de códigos de erro que você pode usar para classificar tipos de erro que ocorrem e para responder aos erros.An error code string that you can use to classify types of errors that occur, and to react to errors.
error_description Uma mensagem de erro específica que pode ajudar você a identificar a causa raiz de um erro de autenticação.A specific error message that can help you identify the root cause of an authentication error.

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.For a description of possible error codes and recommended client responses, see Error codes for authorization endpoint errors.

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.When you have an authorization code and an ID token, you can sign the user in and get access tokens on their behalf. Para conectar o usuário, você deve validar o token de ID exatamente como descrito .To sign the user in, you must validate the ID token exactly as described. Para obter tokens de acesso, siga as etapas descritas na documentação do fluxo de código OAuth.To get access tokens, follow the steps described in OAuth code flow documentation.