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

O tipo de concessão de código de autorização OAuth 2.0, ou fluxo de código de autorização, permite que um aplicativo cliente obtenha acesso autorizado a recursos protegidos, como APIs Web. O fluxo de código de autorização requer um agente de usuário que dê 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, área de trabalho 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 nível inferior geralmente necessários somente 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 pela Microsoft e com suporte para obter tokens de segurança e chamar APIs Web protegidas em seus aplicativos.

Aplicativos que dão suporte ao fluxo de código de autorização

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

• SPA (aplicativo Web de página única)
• Aplicativo Web padrão (baseado em servidor)
• Aplicativo móveis e de desktop

Detalhes do protocolo

O fluxo do 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 do 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 exibição de alto nível do fluxo de autenticação:

URIs de redirecionamento para SPAs (aplicativos de página única)

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

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

O tipo de redirecionamento spa é compatível com versões anteriores com o fluxo implícito. Os aplicativos que atualmente usam o fluxo implícito para obter tokens podem mudar para o tipo de URI de redirecionamento spa 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.

Nesse caso, visite o registro do aplicativo e atualize o URI de redirecionamento usar o tipo spa.

Os aplicativos não podem usar um URI de redirecionamento spa com fluxos não SPA, por exemplo, aplicativos nativos ou fluxos de credenciais do 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 URI de redirecionamento spa sem um cabeçalho Origin. Da mesma forma, a plataforma de identidade da Microsoft também impede o uso de credenciais do cliente em todos os fluxos na presença de um cabeçalho Origin, para garantir que os segredos não sejam usados de dentro do navegador.

Solicitar um código de autorização

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

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

A menos que haja outra especificação, não há valores padrão para parâmetros opcionais. No entanto, há um comportamento padrão para uma solicitação que omite parâmetros opcionais. O comportamento padrão é fazer logon unicamente do usuário atual, mostrar o seletor de conta se houver vários usuários ou mostrar a página de logon 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

Nesse ponto, é solicitado que o usuário insira suas credenciais e conclua a autenticação. A plataforma de identidade da Microsoft também garante que o usuário tenha dado as permissões indicadas no parâmetro de consulta scope. Se o usuário não deu nenhuma dessas permissões, será solicitado que ele dê as permissões necessárias. Para obter mais informações, confira Permissões e consentimento na plataforma de identidade da Microsoft.

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

Resposta bem-sucedida

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

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

Também será possível receber um token de ID se você solicitar um e tiver a concessão implícita habilitada no registro de aplicativo. Às vezes, esse comportamento é chamado de fluxo híbrido. Ele é usado por estruturas como ASP.NET.

Resposta de erro

As respostas de erro também podem ser enviadas ao redirect_uri para que o aplicativo possa tratá-las 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 parâmetro error da resposta de erro.

Solicitar um token de ID ou um 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 ao solicitarem o código de autorização. Essa abordagem é chamada de fluxo híbrido porque combina OIDC com o fluxo de código de autorização OAuth2.

O fluxo híbrido normalmente é usado em aplicativos Web para renderizar uma página para um usuário sem bloquear o resgate de código, principalmente no ASP.NET. Os aplicativos de página única e 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 já descrito, 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 parâmetro de consulta nonce.

// 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 fragment como um modo de resposta causa problemas para aplicativos Web que leem o código do redirecionamento. Os navegadores não passam o fragmento ao servidor Web. Nessas situações, os aplicativos devem usar o modo de resposta form_post para garantir que todos os dados sejam enviados ao servidor.

Resposta bem-sucedida

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 do cliente ou credenciais de certificado. Os 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, confira 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. Clientes públicos, que incluem aplicativos nativos e aplicativos de página única, não podem usar segredos nem certificados ao resgatar um código de autorização. Sempre verifique se os URIs de redirecionamento incluem o tipo de aplicativo e se são exclusivos.

Solicitar 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 code para um access_token no recurso. Resgate o code enviando uma solicitação POST para o ponto de extremidade /token:

// 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 os mesmos que a solicitação por segredo compartilhado, exceto que o parâmetro client_secret é substituído por dois parâmetros: client_assertion_type e client_assertion.

Resposta bem-sucedida

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 já adquiriu com êxito um access_token, você pode usar o token em solicitações para APIs Web incluindo-o no cabeçalho Authorization:

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

Atualizar o token de acesso

Os tokens de acesso têm vida curta. Atualize-os depois que expirarem para continuar acessando recursos. Faça isso enviando outra solicitação POST ao ponto de extremidade /token. Forneça o refresh_token em vez do code. Os tokens de atualização são válidos para todas as permissões cujo consentimento o cliente já recebeu. 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 um tempo de vida especificado. Normalmente, os tempos de vida de 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. O aplicativo precisa esperar e tratar os erros retornados pelo ponto de extremidade de emissão de token. Os aplicativos de página única recebem um token com um tempo de vida de 24 horas, exigindo uma nova autenticação todos os dias. Essa ação pode ser feita silenciosamente em um iframe quando há cookies de terceiros habilitados. Isso precisa ser feito em um quadro de nível superior, navegação de página inteira ou 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. De acordo com a especificação OAuth 2.0: “O servidor de autorização PODE emitir um novo token de atualização. Nesse caso, 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 ao 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 bem-sucedida

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 a ação recomendada do cliente, veja Códigos de erro para erros de ponto de extremidade de token.

Próximas etapas

• Percorra os exemplos de MSAL JS para começar a codificação.
• Saiba mais sobre cenários de troca de tokens.