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

Parâmetro	Obrigatório/opcional	Description
tenant	obrigatório	O {tenant} valor no caminho da solicitação pode ser usado para controlar quem pode entrar no aplicativo. Os valores válidos são common, organizations, consumerse identificadores de locatário. Para cenários de convidado em que você assina um usuário de um locatário para outro locatário, você deve fornecer o identificador de locatário para conectá-lo ao locatário de recurso. Para obter mais informações, consulte Pontos de extremidade.
client_id	obrigatório	A ID do Aplicativo (cliente) que o Centro de administração do Microsoft Entra – Registros de aplicativo experiência atribuída ao seu aplicativo.
response_type	obrigatório	Deve incluir code para o fluxo de código de autorização. Também pode incluir id_token ou token se usar o fluxo híbrido.
redirect_uri	obrigatório	O redirect_uri do seu aplicativo, onde as respostas de autenticação podem ser enviadas e recebidas pelo seu aplicativo. Ele deve corresponder exatamente a um dos URIs de redirecionamento registrados no centro de administração do Microsoft Entra, exceto que deve ser codificado por URL. Para aplicativos nativos e móveis, use um dos valores recomendados: https://login.microsoftonline.com/common/oauth2/nativeclient para aplicativos que usam navegadores incorporados ou http://localhost para aplicativos que usam navegadores do sistema.
scope	obrigatório	Uma lista separada por espaços de escopos para os quais você deseja que o usuário consinta. Para a /authorize parte da solicitação, esse parâmetro pode abranger vários recursos. Esse valor permite que seu aplicativo obtenha consentimento para várias APIs da Web que você deseja chamar.
response_mode	recomendado	Especifica como a plataforma de identidade deve retornar o token solicitado ao seu aplicativo. Valores suportados: - query: Padrão ao solicitar um token de acesso. Fornece o código como um parâmetro de cadeia de caracteres de consulta no URI de redirecionamento. O query parâmetro não é suportado ao solicitar um token de ID usando o fluxo implícito. - fragment: Padrão ao solicitar um token de ID usando o fluxo implícito. Também suportado se solicitar apenas um código. - form_post: Executa um POST contendo o código para o seu URI de redirecionamento. Suporte ao solicitar um código.
state	recomendado	Um valor incluído na solicitação que também é retornado na resposta do token. Pode ser uma sequência de qualquer conteúdo que desejar. Um valor exclusivo gerado aleatoriamente é normalmente usado para evitar ataques de falsificação de solicitação entre sites. O valor também pode codificar informações sobre o estado do usuário no aplicativo antes da solicitação de autenticação ocorrer. Por exemplo, ele poderia codificar a página ou exibir em que eles estavam.
prompt	opcional	Indica o tipo de interação do usuário necessária. Os valores válidos são login, none, consent, e select_account. - prompt=login força o usuário a inserir suas credenciais nessa solicitação, negando o logon único. - prompt=none é o contrário. Ele garante que o usuário não seja apresentado a nenhum prompt interativo. Se a solicitação não puder ser concluída silenciosamente usando o logon único, a plataforma de identidade da Microsoft retornará um interaction_required erro. - prompt=consent aciona a caixa de diálogo de consentimento OAuth depois que o usuário entra, solicitando que o usuário conceda permissões ao aplicativo. - prompt=select_account interrompe o logon único fornecendo experiência de seleção de conta listando todas as contas em sessão ou qualquer conta lembrada ou uma opção para optar por usar uma conta completamente diferente.
login_hint	opcional	Você pode usar esse parâmetro para preencher previamente o campo de nome de usuário e endereço de e-mail da página de entrada do usuário. Os aplicativos podem usar esse parâmetro durante a reautenticação, depois de já extrair a login_hint declaração opcional de uma entrada anterior.
domain_hint	opcional	Se incluído, o aplicativo ignora o processo de descoberta baseado em email pelo qual o usuário passa na página de login, levando a uma experiência de usuário um pouco mais simplificada. Por exemplo, enviá-los para seu provedor de identidade federada. Os aplicativos podem usar esse parâmetro durante a reautenticação, extraindo o tid de uma entrada anterior.
code_challenge	recomendado / obrigatório	Usado para proteger concessões de código de autorização usando a Chave de Prova para Troca de Código (PKCE). Obrigatório se code_challenge_method estiver incluído. Para obter mais informações, consulte a RFC PKCE. Esse parâmetro agora é recomendado para todos os tipos de aplicativos, clientes públicos e confidenciais, e exigido pela plataforma de identidade da Microsoft para aplicativos de página única usando o fluxo de código de autorização.
code_challenge_method	recomendado / obrigatório	O método usado para codificar o code_verifier para o code_challenge parâmetro. Isso DEVE ser S256, mas a especificação permite o uso de plain se o cliente não pode suportar SHA256. Se excluído, code_challenge presume-se que é texto simples se code_challenge for incluído. A plataforma de identidade da Microsoft suporta ambos e plain S256. Para obter mais informações, consulte a RFC PKCE. Esse parâmetro é necessário para aplicativos de página única que usam o fluxo de código de autorização.

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

Parâmetro	Description
code	O authorization_code que o aplicativo solicitou. O aplicativo pode usar o código de autorização para solicitar um token de acesso para o recurso de destino. Os códigos de autorização são de curta duração. Normalmente, expiram após cerca de 10 minutos.
state	Se um state parâmetro for incluído na solicitação, o mesmo valor deverá aparecer na resposta. O aplicativo deve verificar se os valores de estado na solicitação e na resposta são idênticos.

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

Parâmetro	Description
error	Uma cadeia de caracteres de código de erro que pode ser usada para classificar tipos de erros e reagir a erros. Essa parte do erro é fornecida para que o aplicativo possa reagir adequadamente ao erro, mas não explica em profundidade por que um erro ocorreu.
error_description	Uma mensagem de erro específica que pode ajudar um desenvolvedor a identificar a causa de um erro de autenticação. Esta parte do erro contém a maioria das informações úteis sobre por que o erro ocorreu.

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.

Código de Erro	Description	Ação do Cliente
invalid_request	Erro de protocolo, como um parâmetro necessário ausente.	Corrija e reenvie a solicitação. Este erro é um erro de desenvolvimento normalmente detetado durante o teste inicial.
unauthorized_client	O aplicativo cliente não tem permissão para solicitar um código de autorização.	Esse erro geralmente ocorre quando o aplicativo cliente não está registrado na ID do Microsoft Entra ou não é adicionado ao locatário do Microsoft Entra do usuário. O aplicativo pode solicitar ao usuário instruções para instalar o aplicativo e adicioná-lo ao Microsoft Entra ID.
access_denied	O consentimento negado pelo proprietário do recurso	O aplicativo cliente pode notificar o usuário de que não pode continuar a menos que o usuário consinta.
unsupported_response_type	O servidor de autorização não suporta o tipo de resposta na solicitação.	Corrija e reenvie a solicitação. Este erro é um erro de desenvolvimento normalmente detetado durante o teste inicial. No fluxo híbrido, esse erro sinaliza que você deve habilitar a configuração de concessão implícita do token de ID no registro do aplicativo cliente.
server_error	O servidor encontrou um erro inesperado.	Repita o pedido. Estes erros podem resultar de condições temporárias. O aplicativo cliente pode explicar ao usuário que sua resposta está atrasada para um erro temporário.
temporarily_unavailable	O servidor está temporariamente muito ocupado para lidar com a solicitação.	Repita o pedido. O aplicativo cliente pode explicar ao usuário que sua resposta está atrasada devido a uma condição temporária.
invalid_resource	O recurso de destino é inválido porque não existe, o ID do Microsoft Entra não consegue encontrá-lo ou não está configurado corretamente.	Esse erro indica que o recurso, se existir, não foi configurado no locatário. O aplicativo pode solicitar ao usuário instruções para instalar o aplicativo e adicioná-lo ao Microsoft Entra ID.
login_required	Muitos ou nenhum usuário encontrado.	O cliente solicitou autenticação silenciosa (prompt=none), mas não foi possível encontrar um único usuário. Este erro pode significar que há vários usuários ativos na sessão ou nenhum usuário. Este erro tem em conta o inquilino escolhido. Por exemplo, se houver duas contas do Microsoft Entra ativas e uma conta da Microsoft, e consumers for escolhida, a autenticação silenciosa funcionará.
interaction_required	A solicitação requer interação do usuário.	É necessária outra etapa de autenticação ou consentimento. Repita a solicitação sem prompt=none.

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

Parâmetro atualizado	Obrigatório/opcional	Description
response_type	obrigatório	A adição de indica ao servidor que o aplicativo gostaria de um token de id_token ID na resposta do /authorize ponto de extremidade.
scope	obrigatório	Para tokens de ID, esse parâmetro deve ser atualizado para incluir os escopos de token de ID: e, openid opcionalmente profile , e email.
nonce	obrigatório	Um valor incluído na solicitação, gerado pelo aplicativo, que é incluído no resultado id_token como uma declaração. O aplicativo pode verificar esse valor para mitigar ataques de repetição de token. O valor é normalmente uma cadeia de caracteres aleatória e exclusiva que pode ser usada para identificar a origem da solicitação.
response_mode	recomendado	Especifica o método que deve ser usado para enviar o token resultante de volta para seu aplicativo. O valor padrão é query apenas para um código de autorização, mas fragment se a solicitação incluir um id_token response_type conforme especificado na especificação OpenID. Recomendamos que os aplicativos usem form_posto , especialmente ao usar http://localhost como um URI de redirecionamento.

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

Parâmetro	Description
code	O código de autorização que o aplicativo solicitou. O aplicativo pode usar o código de autorização para solicitar um token de acesso para o recurso de destino. Os códigos de autorização são de curta duração, normalmente expirando após cerca de 10 minutos.
id_token	Um token de ID para o usuário, emitido usando a concessão implícita. Contém uma afirmação c_hash especial que é o hash do code mesmo pedido.
state	Se um state parâmetro for incluído na solicitação, o mesmo valor deverá aparecer na resposta. O aplicativo deve verificar se os valores de estado na solicitação e na resposta são idênticos.

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.

Parâmetro	Obrigatório/opcional	Description
tenant	obrigatório	O {tenant} valor no caminho da solicitação pode ser usado para controlar quem pode entrar no aplicativo. Os valores válidos são common, organizations, consumerse identificadores de locatário. Para obter mais informações, consulte Pontos de extremidade.
client_id	obrigatório	A ID do Aplicativo (cliente) que a página Centro de administração do Microsoft Entra – Registros de aplicativos atribuiu ao seu aplicativo.
scope	opcional	Uma lista de escopos separados por espaços. Todos os escopos devem ser de um único recurso, juntamente com os escopos OIDC (profile, openidemail, ). Para obter mais informações, consulte Permissões e consentimento na plataforma de identidade da Microsoft. Este parâmetro é uma extensão da Microsoft para o fluxo de código de autorização, destinado a permitir que os aplicativos declarem o recurso para o qual desejam o token durante o resgate do token.
code	obrigatório	O authorization_code que você adquiriu na primeira perna do fluxo.
redirect_uri	obrigatório	O mesmo redirect_uri valor que foi utilizado para adquirir o authorization_code.
grant_type	obrigatório	Deve ser authorization_code para o fluxo de código de autorização.
code_verifier	recomendado	O mesmo code_verifier que foi usado para obter o authorization_code. Necessário se PKCE foi usado na solicitação de concessão de código de autorização. Para obter mais informações, consulte a RFC PKCE.
client_secret	Necessário para aplicações Web confidenciais	O segredo do aplicativo que você criou no portal de registro do aplicativo para seu aplicativo. Não use o segredo do aplicativo em um aplicativo nativo ou aplicativo de página única porque um client_secret não pode ser armazenado de forma confiável em dispositivos ou páginas da Web. É necessário para aplicativos da Web e APIs da Web, que podem armazenar o client_secret com segurança no lado do servidor. Como todos os parâmetros aqui, o segredo do cliente deve ser codificado por URL antes de ser enviado. Esta etapa é feita pelo SDK. Para obter mais informações sobre codificação URI, consulte a especificação de sintaxe genérica de URI. O padrão de autenticação básica de fornecer credenciais no cabeçalho de autorização, de acordo com RFC 6749 , também é suportado.

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

Parâmetro	Obrigatório/opcional	Description
tenant	obrigatório	O {tenant} valor no caminho da solicitação pode ser usado para controlar quem pode entrar no aplicativo. Os valores válidos são common, organizations, consumerse identificadores de locatário. Para obter mais detalhes, consulte Pontos de extremidade.
client_id	obrigatório	A ID do Aplicativo (cliente) que a página Centro de administração do Microsoft Entra – Registros de aplicativos atribuiu ao seu aplicativo.
scope	opcional	Uma lista de escopos separados por espaços. Todos os escopos devem ser de um único recurso, juntamente com os escopos OIDC (profile, openidemail, ). Para obter mais informações, consulte permissões, consentimento e escopos. Este parâmetro é uma extensão da Microsoft para o fluxo de código de autorização. Essa extensão permite que os aplicativos declarem o recurso para o qual desejam o token durante o resgate do token.
code	obrigatório	O authorization_code que você adquiriu na primeira perna do fluxo.
redirect_uri	obrigatório	O mesmo redirect_uri valor que foi utilizado para adquirir o authorization_code.
grant_type	obrigatório	Deve ser authorization_code para o fluxo de código de autorização.
code_verifier	recomendado	O mesmo code_verifier que foi usado para obter o authorization_code. Necessário se PKCE foi usado na solicitação de concessão de código de autorização. Para obter mais informações, consulte a RFC PKCE.
client_assertion_type	Necessário para aplicações Web confidenciais	O valor deve ser definido para urn:ietf:params:oauth:client-assertion-type:jwt-bearer usar uma credencial de certificado.
client_assertion	Necessário para aplicações Web confidenciais	Uma asserção, que é um token da Web JSON (JWT), que você precisa criar e assinar com o certificado registrado como credenciais para seu aplicativo. Leia sobre credenciais de certificado para saber como registrar seu certificado e o formato da declaração.

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..."
}

Parâmetro	Description
access_token	O token de acesso solicitado. O aplicativo pode usar esse token para autenticar o recurso seguro, como uma API da Web.
token_type	Indica o valor do tipo de token. O único tipo que o Microsoft Entra ID suporta é Bearer.
expires_in	Por quanto tempo o token de acesso é válido, em segundos.
scope	Os escopos para os quais o access_token é válido. Opcional. Este parâmetro não é padrão e, se omitido, o token é para os escopos solicitados na etapa inicial do fluxo.
refresh_token	Um token de atualização OAuth 2.0. O aplicativo pode usar esse token para adquirir outros tokens de acesso depois que o token de acesso atual expirar. Os tokens de atualização são de longa duração. Podem manter o acesso aos recursos por períodos prolongados. Para obter mais detalhes sobre como atualizar um token de acesso, consulte Atualizar o token de acesso mais adiante neste artigo. Nota: Apenas fornecido se offline_access o âmbito foi solicitado.
id_token	Um token da Web JSON. O aplicativo pode decodificar os segmentos desse token para solicitar informações sobre o usuário que fez login. O aplicativo pode armazenar os valores em cache e exibi-los, e os clientes confidenciais podem usar esse token para autorização. Para obter mais informações sobre id_tokens, consulte o id_token reference. Nota: Apenas fornecido se openid o âmbito foi solicitado.

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"
}

Parâmetro	Description
error	Uma cadeia de caracteres de código de erro que pode ser usada para classificar tipos de erros e reagir a erros.
error_description	Uma mensagem de erro específica que pode ajudar um desenvolvedor a identificar a causa de um erro de autenticação.
error_codes	Uma lista de códigos de erro específicos do STS que podem ajudar no diagnóstico.
timestamp	A hora em que o erro ocorreu.
trace_id	Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico.
correlation_id	Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico entre componentes.

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

Código de Erro	Description	Ação do Cliente
invalid_request	Erro de protocolo, como um parâmetro necessário ausente.	Corrija a solicitação ou o registro do aplicativo e reenvie a solicitação.
invalid_grant	O código de autorização ou verificador de código PKCE é inválido ou expirou.	Tente uma nova solicitação para o /authorize ponto de extremidade e verifique se o code_verifier parâmetro estava correto.
unauthorized_client	O cliente autenticado não está autorizado a usar esse tipo de concessão de autorização.	Esse erro geralmente ocorre quando o aplicativo cliente não está registrado na ID do Microsoft Entra ou não é adicionado ao locatário do Microsoft Entra do usuário. O aplicativo pode solicitar ao usuário instruções para instalar o aplicativo e adicioná-lo ao Microsoft Entra ID.
invalid_client	Falha na autenticação do cliente.	As credenciais do cliente não são válidas. Para corrigir, o administrador do aplicativo atualiza as credenciais.
unsupported_grant_type	O servidor de autorização não suporta o tipo de concessão de autorização.	Altere o tipo de concessão na solicitação. Este tipo de erro deve ocorrer apenas durante o desenvolvimento e ser detetado durante os testes iniciais.
invalid_resource	O recurso de destino é inválido porque não existe, o ID do Microsoft Entra não consegue encontrá-lo ou não está configurado corretamente.	Esse código indica que o recurso, se existir, não foi configurado no locatário. O aplicativo pode solicitar ao usuário instruções para instalar o aplicativo e adicioná-lo ao Microsoft Entra ID.
interaction_required	Não padrão, pois a especificação OIDC exige esse código apenas no /authorize ponto de extremidade. A solicitação requer interação do usuário. Por exemplo, outra etapa de autenticação é necessária.	Tente novamente a /authorize solicitação com os mesmos escopos.
temporarily_unavailable	O servidor está temporariamente muito ocupado para lidar com a solicitação.	Repita a solicitação após um pequeno atraso. O aplicativo cliente pode explicar ao usuário que sua resposta está atrasada devido a uma condição temporária.
consent_required	O pedido requer o consentimento do utilizador. Este erro não é padrão. Geralmente, ele só é retornado no endpoint de acordo com as /authorize especificações do OIDC. Retornado quando um scope parâmetro foi usado no fluxo de resgate de código que o aplicativo cliente não tem permissão para solicitar.	O cliente deve enviar o usuário de volta ao /authorize ponto de extremidade com o escopo correto para acionar o consentimento.
invalid_scope	O escopo solicitado pelo aplicativo é inválido.	Atualize o scope valor do parâmetro na solicitação de autenticação para um valor válido.

Nota

Os aplicativos de página única podem receber um invalid_request erro indicando que o resgate de token de origem cruzada é permitido apenas para o tipo de cliente 'Aplicativo de página única'. Isso indica que o URI de redirecionamento usado para solicitar o token não foi marcado como um URI de spa redirecionamento. Analise as etapas de registro do aplicativo sobre como habilitar esse fluxo.

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."

Importante

Para tokens de atualização enviados para um URI de redirecionamento registrado como spa, o token de atualização expira após 24 horas. Tokens de atualização adicionais adquiridos usando o token de atualização inicial transportam esse tempo de expiração, portanto, os aplicativos devem estar preparados para executar novamente o fluxo de código de autorização usando uma autenticação interativa para obter um novo token de atualização a cada 24 horas. Os usuários não precisam inserir suas credenciais e, geralmente, nem veem nenhuma experiência do usuário, apenas uma recarga do seu aplicativo. O navegador deve visitar a página de login em um quadro de nível superior para ver a sessão de login. Isso se deve a recursos de privacidade em navegadores que bloqueiam cookies de terceiros.

// 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

Parâmetro	Tipo	Descrição
tenant	obrigatório	O {tenant} valor no caminho da solicitação pode ser usado para controlar quem pode entrar no aplicativo. Os valores válidos são common, organizations, consumerse identificadores de locatário. Para obter mais informações, consulte Pontos de extremidade.
client_id	obrigatório	A ID do Aplicativo (cliente) que o Centro de administração do Microsoft Entra – Registros de aplicativo experiência atribuída ao seu aplicativo.
grant_type	obrigatório	Deve ser refresh_token para esta etapa do fluxo do código de autorização.
scope	opcional	Uma lista de escopos separados por espaços. Os escopos solicitados nesta etapa devem ser equivalentes ou um subconjunto dos escopos solicitados na etapa de solicitação original authorization_code . Se os escopos especificados nessa solicitação abrangerem vários servidores de recursos, a plataforma de identidade da Microsoft retornará um token para o recurso especificado no primeiro escopo. Para obter mais informações, consulte Permissões e consentimento na plataforma de identidade da Microsoft.
refresh_token	obrigatório	O refresh_token que você adquiriu na segunda perna do fluxo.
client_secret	Necessário para aplicativos Web	O segredo do aplicativo que você criou no portal de registro do aplicativo para seu aplicativo. Ele não deve ser usado em um aplicativo nativo, porque um client_secret não pode ser armazenado de forma confiável em dispositivos. É necessário para aplicativos da Web e APIs da Web, que podem armazenar o client_secret com segurança no lado do servidor. Este segredo tem de ser codificado por URL. Para obter mais informações, consulte a especificação de sintaxe genérica de URI.

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..."
}

Parâmetro	Description
access_token	O token de acesso solicitado. O aplicativo pode usar esse token para autenticar o recurso seguro, como uma API da Web.
token_type	Indica o valor do tipo de token. O único tipo que o Microsoft Entra ID suporta é Bearer.
expires_in	Por quanto tempo o token de acesso é válido, em segundos.
scope	Os escopos para os quais o access_token é válido.
refresh_token	Um novo token de atualização OAuth 2.0. Substitua o token de atualização antigo por esse token de atualização recém-adquirido para garantir que seus tokens de atualização permaneçam válidos pelo maior tempo possível. Nota: Apenas fornecido se offline_access o âmbito foi solicitado.
id_token	Um token da Web JSON não assinado. O aplicativo pode decodificar os segmentos desse token para solicitar informações sobre o usuário que fez login. O aplicativo pode armazenar os valores em cache e exibi-los, mas não deve depender deles para quaisquer limites de autorização ou segurança. Para obter mais informações sobre id_tokeno , consulte os tokens de ID da plataforma de identidade da Microsoft. Nota: Apenas fornecido se openid o âmbito foi solicitado.

Aviso

Não tente validar ou ler tokens para qualquer API que você não possua, incluindo os tokens neste exemplo, em seu código. Os tokens para serviços da Microsoft podem usar um formato especial que não será validado como um JWT e também podem ser criptografados para usuários consumidores (conta da Microsoft). Embora a leitura de tokens seja uma ferramenta útil de depuração e aprendizagem, não dependa disso em seu código ou assuma especificidades sobre tokens que não são para uma API que você controla.

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"
}

Parâmetro	Description
error	Uma cadeia de caracteres de código de erro que pode ser usada para classificar tipos de erros e reagir a erros.
error_description	Uma mensagem de erro específica que pode ajudar um desenvolvedor a identificar a causa raiz de um erro de autenticação.
error_codes	Uma lista de códigos de erro específicos do STS que podem ajudar no diagnóstico.
timestamp	A hora em que o erro ocorreu.
trace_id	Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico.
correlation_id	Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico entre componentes.

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.