Plataforma de identidades da Microsoft e fluxo de código de autorização OAuth 2.0

O tipo de concessão de código de autorização OAuth 2.0, ou fluxo de código de autenticação, permite que um aplicativo cliente obtenha acesso autorizado a recursos protegidos, como APIs da Web. O fluxo de código de autenticação requer um agente de usuário que ofereça suporte ao redirecionamento do servidor de autorização (a plataforma de identidade da Microsoft) de volta para seu aplicativo. Por exemplo, um navegador da Web, desktop ou aplicativo móvel operado por um usuário para entrar em seu aplicativo e acessar seus dados.

Este artigo descreve os detalhes de protocolo de baixo nível necessários apenas ao criar manualmente e emitir solicitações HTTP brutas para executar o fluxo, o que não recomendamos. Em vez disso, use uma biblioteca de autenticação criada e suportada pela Microsoft para obter tokens de segurança e chamar APIs da Web protegidas em seus aplicativos.

Aplicativos que suportam o fluxo de código de autenticação

Use o fluxo de código de autenticação emparelhado com PKCE (Proof Key for Code Exchange) e OpenID Connect (OIDC) para obter tokens de acesso e tokens de ID nesses tipos de aplicativos:

• Aplicação Web de página única (SPA)
• Aplicação Web padrão (baseada em servidor)
• Aplicações para computadores e dispositivos móveis

Detalhes do protocolo

O fluxo de código de autorização do OAuth 2.0 é descrito na seção 4.1 da especificação do OAuth 2.0. Os aplicativos que usam o fluxo de código de autorização OAuth 2.0 adquirem um access_token para incluir em solicitações para recursos protegidos pela plataforma de identidade da Microsoft (normalmente APIs). Os aplicativos também podem solicitar novos tokens de ID e acesso para entidades autenticadas anteriormente usando um mecanismo de atualização.

Este diagrama mostra uma visão de alto nível do fluxo de autenticação:

URIs de redirecionamento para aplicações de página única (SPAs)

Os URIs de redirecionamento para SPAs que usam o fluxo de código de autenticação exigem configuração especial.

• Adicione um URI de redirecionamento que ofereça suporte ao fluxo de código de autenticação com PKCE e compartilhamento de recursos entre origens (CORS): siga as etapas em URI de redirecionamento: MSAL.js 2.0 com fluxo de código de autenticação.
• Atualizar um URI de redirecionamento: defina os URIs type de redirecionamento para spa usando o editor de manifesto do aplicativo no centro de administração do Microsoft Entra.

O spa tipo de redirecionamento é compatível com o fluxo implícito. Os aplicativos que atualmente usam o fluxo implícito para obter tokens podem se mover para o tipo de URI de spa redirecionamento sem problemas e continuar usando o fluxo implícito. Apesar dessa compatibilidade com versões anteriores, recomendamos que você use o fluxo de código de autenticação com PKCE para SPAs.

Se você tentar usar o fluxo de código de autorização sem configurar o CORS para o URI de redirecionamento, verá este erro no console:

access to XMLHttpRequest at 'https://login.microsoftonline.com/common/v2.0/oauth2/token' from origin 'yourApp.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Em caso afirmativo, visite o registro do aplicativo e atualize o URI de redirecionamento para que seu aplicativo use o spa tipo.

Os aplicativos não podem usar um spa URI de redirecionamento com fluxos que não sejam SPA, por exemplo, aplicativos nativos ou fluxos de credenciais de cliente. Para garantir a segurança e as práticas recomendadas, a plataforma de identidade da Microsoft retornará um erro se você tentar usar um spa URI de redirecionamento sem um Origin cabeçalho. Da mesma forma, a plataforma de identidade da Microsoft também impede o uso de credenciais de cliente em todos os fluxos na presença de um Origin cabeçalho, para garantir que os segredos não sejam usados de dentro do navegador.

Solicitar um código de autorização

O fluxo de código de autorização começa com o cliente direcionando o usuário para o /authorize ponto de extremidade. Neste exemplo de solicitação, o cliente solicita as openidpermissões , offline_accesse https://graph.microsoft.com/mail.read do usuário.

Algumas permissões são restritas ao administrador, por exemplo, gravando dados no diretório de uma organização usando Directory.ReadWrite.Allo . Se seu aplicativo solicitar acesso a uma dessas permissões de um usuário organizacional, o usuário receberá uma mensagem de erro informando que ele não está autorizado a consentir com as permissões do seu aplicativo. Para solicitar acesso a escopos restritos pelo administrador, você deve solicitá-los diretamente a um Administrador Global. Para obter mais informações, consulte Permissões restritas por administrador.

A menos que especificado de outra forma, não há valores padrão para parâmetros opcionais. Há, no entanto, um comportamento padrão para uma solicitação omitindo parâmetros opcionais. O comportamento padrão é entrar no único usuário atual, mostrar o seletor de conta se houver vários usuários ou mostrar a página de login se não houver usuários conectados.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

Neste ponto, o usuário é solicitado a inserir suas credenciais e concluir a autenticação. A plataforma de identidade da Microsoft também garante que o usuário tenha consentido com as permissões indicadas no scope parâmetro query. Se o usuário não consentiu com nenhuma dessas permissões, ele pede que o usuário consinta com as permissões necessárias. Para obter mais informações, consulte Permissões e consentimento na plataforma de identidade da Microsoft.

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

Resposta com êxito

Este exemplo mostra uma resposta bem-sucedida usando response_mode=query:

GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345

Você também pode receber um token de identificação se solicitar um e tiver a concessão implícita habilitada no registro do seu aplicativo. Esse comportamento às vezes é chamado de fluxo híbrido. É usado por frameworks como ASP.NET.

Resposta de erro

As respostas de erro também podem ser enviadas para o para que redirect_uri o aplicativo possa lidar com elas adequadamente:

GET http://localhost?
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 vários códigos de erro que podem ser retornados no error parâmetro da resposta de erro.

Solicite também um token de ID ou fluxo híbrido

Para saber quem é o usuário antes de resgatar um código de autorização, é comum que os aplicativos também solicitem um token de ID quando solicitam o código de autorização. Essa abordagem é chamada de fluxo híbrido porque mistura OIDC com o fluxo de código de autorização OAuth2.

O fluxo híbrido é comumente usado em aplicativos Web para renderizar uma página para um usuário sem bloquear o resgate de código, principalmente em ASP.NET. Tanto os aplicativos de página única quanto os aplicativos Web tradicionais se beneficiam da latência reduzida nesse modelo.

O fluxo híbrido é o mesmo que o fluxo de código de autorização descrito anteriormente, mas com três adições. Todas essas adições são necessárias para solicitar um token de ID: novos escopos, um novo response_type e um novo nonce parâmetro de consulta.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code%20id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=fragment
&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&state=12345
&nonce=abcde
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

O uso de como modo de fragment resposta causa problemas para aplicativos Web que leem o código do redirecionamento. Os navegadores não passam o fragmento para o servidor Web. Nessas situações, os aplicativos devem usar o modo de form_post resposta para garantir que todos os dados sejam enviados para o servidor.

Resposta com êxito

Este exemplo mostra uma resposta bem-sucedida usando response_mode=fragment:

GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345

Resgatar um código para um token de acesso

Todos os clientes confidenciais têm a opção de usar segredos de cliente ou credenciais de certificado. Segredos compartilhados simétricos são gerados pela plataforma de identidade da Microsoft. As credenciais de certificado são chaves assimétricas carregadas pelo desenvolvedor. Para obter mais informações, consulte Credenciais de certificado de autenticação de aplicativo da plataforma de identidade da Microsoft.

Para melhor segurança, recomendamos o uso de credenciais de certificado. Os clientes públicos, que incluem aplicativos nativos e aplicativos de página única, não devem usar segredos ou certificados ao resgatar um código de autorização. Certifique-se sempre de que seus URIs de redirecionamento incluam o tipo de aplicativo e sejam exclusivos.

Solicite um token de acesso com um client_secret

Agora que você adquiriu um authorization_code e recebeu permissão do usuário, você pode resgatar o foro code para o access_token recurso. Resgate o code enviando uma POST solicitação para o /token ponto de extremidade:

// Line breaks for legibility only

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=11112222-bbbb-3333-cccc-4444dddd5555
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong 
&client_secret=sampleCredentia1s    // NOTE: Only required for web apps. This secret needs to be URL-Encoded.

Solicitar um token de acesso com uma credencial de certificado

// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg

Os parâmetros são iguais à solicitação por segredo compartilhado, exceto que o client_secret parâmetro é substituído por dois parâmetros: a client_assertion_type e client_assertion.

Resposta com êxito

Este exemplo mostra uma resposta de token bem-sucedida:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}

Resposta de erro

Este exemplo é uma resposta de erro:

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
  "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

Códigos de erro para erros de ponto de extremidade de token

Usar o token de acesso

Agora que você adquiriu com êxito um access_token, você pode usar o token em solicitações para APIs da Web incluindo-o Authorization no cabeçalho:

GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

Atualizar o token de acesso

Os tokens de acesso são de curta duração. Atualize-os depois que expirarem para continuar acessando recursos. Você pode fazer isso enviando outra POST solicitação para o /token ponto de extremidade. Forneça o refresh_token em vez do code. Os tokens de atualização são válidos para todas as permissões para as quais seu cliente já recebeu consentimento. Por exemplo, um token de atualização emitido em uma solicitação para scope=mail.read pode ser usado para solicitar um novo token de acesso para scope=api://contoso.com/api/UseResource.

Os tokens de atualização para aplicativos Web e aplicativos nativos não têm tempos de vida especificados. Normalmente, os tempos de vida dos tokens de atualização são relativamente longos. No entanto, em alguns casos, os tokens de atualização expiram, são revogados ou não têm privilégios suficientes para a ação. Seu aplicativo precisa esperar e lidar com erros retornados pelo ponto de extremidade de emissão de token. Os aplicativos de página única recebem um token com uma vida útil de 24 horas, exigindo uma nova autenticação todos os dias. Esta ação pode ser feita silenciosamente em um iframe quando os cookies de terceiros estão ativados. Deve ser feito em um quadro de nível superior, seja navegação de página inteira ou uma janela pop-up, em navegadores sem cookies de terceiros, como o Safari.

Os tokens de atualização não são revogados quando usados para adquirir novos tokens de acesso. Espera-se que você descarte o token de atualização antigo. A especificação OAuth 2.0 diz: "O servidor de autorização PODE emitir um novo token de atualização, caso em que o cliente DEVE descartar o token de atualização antigo e substituí-lo pelo novo token de atualização. O servidor de autorização PODE revogar o token de atualização antigo depois de emitir um novo token de atualização para o cliente."

// Line breaks for legibility only

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=sampleCredentia1s    // NOTE: Only required for web apps. This secret needs to be URL-Encoded

Resposta com êxito

Este exemplo mostra uma resposta de token bem-sucedida:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}

Resposta de erro

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
  "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

Para obter uma descrição dos códigos de erro e da ação recomendada do cliente, consulte Códigos de erro para erros de ponto de extremidade de token.

Próximos passos

• Examine as amostras MSAL JS para começar a codificar.
• Saiba mais sobre cenários de troca de tokens.