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
typeparaspausando 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
| Parâmetro | Obrigatório/opcional | Descrição |
|---|---|---|
tenant |
obrigatório | O valor {tenant} no caminho da solicitação pode ser usado para controlar quem pode entrar no aplicativo. Os valores válidos são common, organizations, consumers e identificadores de locatário. Para cenários de convidado em que você conecta um usuário de um locatário a outro locatário, você precisa fornecer o identificador do locatário para que ele se conecte ao locatário do recurso. Para saber mais, confira Pontos de extremidade. |
client_id |
obrigatório | A ID do aplicativo (cliente) que a experiência centro de administração do Microsoft Entra - Registros de aplicativo atribui ao seu aplicativo. |
response_type |
obrigatório | Deve incluir code para o fluxo do código de autorização. Também pode incluir id_token ou token se estiver usando o fluxo híbrido. |
redirect_uri |
necessárias | O redirect_uri de seu aplicativo, em que as respostas de autenticação podem ser enviadas e recebidas pelo seu aplicativo. Ele deve corresponder exatamente a uma das URIs de redirecionamento que você registrou no Centro de administração do Microsoft Entra, exceto que ela deve ser codificada em URL. Para aplicativos nativos e móveis, use um dos valores recomendados: https://login.microsoftonline.com/common/oauth2/nativeclient para aplicativos que usam navegadores inseridos 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 o consentimento do usuário. Para o trecho /authorize da solicitação, esse parâmetro pode abranger vários recursos. Esse valor permite que o aplicativo tenha consentimento para várias APIs Web que você deseja chamar. |
response_mode |
recomendável | Especifica como a plataforma de identidade deve retornar o token solicitado ao seu aplicativo. Valores com suporte: - query: padrão ao solicitar um token de acesso. Fornece o código como um parâmetro da cadeia de caracteres de consulta no URI de redirecionamento. Não há suporte para o parâmetro query 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. Haverá suporte também se solicitar apenas um código.- form_post: executa um POST contendo o código para o URI de redirecionamento. Há suporte ao solicitar um código. |
state |
recomendável | Um valor incluído na solicitação que também retorna na resposta do token. Pode ser uma cadeia de caracteres de qualquer conteúdo desejado. Um valor exclusivo gerado aleatoriamente normalmente é usado para impedir ataques de solicitação intersite forjada. 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 pode codificar a página ou exibição em que o usuário estava. |
prompt |
opcionais | Indica o tipo de interação do usuário que é necessário. Os valores válidos são login, none, consent e select_account.- prompt=login força o usuário a inserir as credenciais na solicitação, negando o logon único.- prompt=none é o oposto. Essa opção garante que o usuário não receba 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 erro interaction_required.- prompt=consent dispara a caixa de diálogo de consentimento do OAuth depois que o usuário se conecta, solicitando que ele conceda permissões ao aplicativo.- prompt=select_account interrompe o logon único, fornecendo a experiência de seleção de conta, listando todas as contas na sessão ou em qualquer conta lembrada ou uma opção para usar uma conta totalmente diferente. |
login_hint |
opcionais | Você pode usar esse parâmetro para preencher previamente os campos de nome de usuário e endereço de email da página de entrada do usuário. Os aplicativos podem usar esse parâmetro durante a reautenticação, depois de extrair a declaração opcional login_hint de um logon anterior. |
domain_hint |
opcionais | Quando incluído, o aplicativo ignora o processo de descoberta baseado em email que o usuário informa na página de entrada, simplificando um pouco mais a experiência de usuário. Por exemplo, o usuário pode ser enviado ao provedor de identidade federado. Os aplicativos podem usar esse parâmetro durante a reautenticação, extraindo tid de um logon anterior. |
code_challenge |
recomendado/obrigatório | Usado para proteger concessões de código de autorização usando a PKCE (Proof Key for Code Exchange). Necessário se code_challenge_method estiver incluído. Para mais informações, consulte PKCE RFC. Esse parâmetro agora é recomendado para todos os tipos de aplicativos, tanto clientes públicos quanto confidenciais e exigido pela plataforma de identidade da Microsoft para aplicativos de página única que usam o fluxo de código de autorização. |
code_challenge_method |
recomendado/obrigatório | O método utilizado para codificar o code_verifier para o parâmetro code_challenge. DEVE ser S256, mas a especificação permitirá o uso de plain se, por algum motivo, o cliente não der suporte a SHA256. Se excluído, code_challenge será considerado texto não criptografado se code_challenge estiver incluído. A plataforma de identidade da Microsoft tem suporte para plain e S256. Para mais informações, consulte PKCE RFC. Esse parâmetro é necessário para aplicativos de página única que usam o fluxo de código de autorização. |
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
| Parâmetro | Descrição |
|---|---|
code |
O authorization_code que o aplicativo solicitou. O aplicativo pode usar o código de autorização para solicitar um token de acesso ao recurso alvo. Os códigos de autorização têm curta duração. Normalmente, eles expiram depois de cerca de 10 minutos. |
state |
Se um parâmetro state 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. |
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
| Parâmetro | Descrição |
|---|---|
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 detalhadamente por que o 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. Essa parte do erro contém a maioria das informações úteis sobre o motivo do erro. |
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.
| Código do Erro | Descrição | Ação do Cliente |
|---|---|---|
invalid_request |
Erro de protocolo, como um parâmetro obrigatório ausente. | Corrija e reenvie a solicitação. Esse é um erro de desenvolvimento normalmente apontado durante o teste inicial. |
unauthorized_client |
O aplicativo cliente não tem permissão para solicitar um código de autorização. | Isso geralmente ocorre quando o aplicativo cliente não está registrado no Microsoft Entra ID ou não é adicionado ao locatário do Microsoft Entra do usuário. O aplicativo pode solicitar que o usuário instale o aplicativo e o adicione ao Microsoft Entra ID. |
access_denied |
Consentimento negado pelo proprietário do recurso | O aplicativo cliente pode informar ao usuário que ele não pode continuar, a menos que dê consentimento. |
unsupported_response_type |
O servidor de autorização não dá suporte ao tipo de resposta na solicitação. | Corrija e reenvie a solicitação. Esse é um erro de desenvolvimento normalmente apontado durante o teste inicial. No fluxo híbrido, esse erro sinaliza que você precisa 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. | Tente novamente a solicitação. Esses erros podem resultar de condições temporárias. O aplicativo cliente pode explicar ao usuário que a resposta está atrasada para um erro temporário. |
temporarily_unavailable |
O servidor está temporariamente muito ocupado para tratar da solicitação. | Tente novamente a solicitação. O aplicativo cliente pode explicar para o 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 ele existe, o Microsoft Entra ID não pode encontrá-lo ou ele não está configurado corretamente. | Esse erro indica que o recurso, se existir, não foi configurado no locatário. O aplicativo pode solicitar que o usuário instale o aplicativo e o adicione ao Microsoft Entra ID. |
login_required |
Muitos usuários ou nenhum usuário encontrado. | O cliente solicitou a autenticação silenciosa (prompt=none), mas não foi possível encontrar um usuário. Esse erro pode significar que há vários usuários ativos na sessão ou nenhum usuário. Esse erro leva em conta o locatário escolhido. Por exemplo, se houver duas contas do Microsoft Entra ID ativas e uma conta Microsoft e consumers for a escolhida, a autenticação silenciosa funcionará. |
interaction_required |
A solicitação requer interação do usuário. | Outra etapa de autenticação ou de consentimento é necessária. Repita a solicitação sem prompt=none. |
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
| Parâmetro atualizado | Obrigatório/opcional | Descrição |
|---|---|---|
response_type |
obrigatório | A adição de id_token indica ao servidor que o aplicativo gostaria de um token de ID na resposta do ponto de extremidade /authorize. |
scope |
exigido | Para tokens de ID, esse parâmetro precisa ser atualizado para incluir os escopos do token de ID: openid e, opcionalmente, profile e email. |
nonce |
necessárias | Um valor incluído na solicitação, gerado pelo aplicativo, que é incluído no id_token resultante como uma declaração. O aplicativo pode, então, verificar esse valor para atenuar os ataques de reproduçã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 |
recomendável | Especifica o método que deve ser usado para enviar o token resultante de volta ao aplicativo. O valor padrão é query para apenas um código de autorização, mas fragment quando a solicitação inclui um id_token response_type, como especificado na especificação do OpenID. Recomendamos que os aplicativos usem form_post, principalmente ao usar http://localhost como um URI de redirecionamento. |
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
| Parâmetro | Descrição |
|---|---|
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 declaração c_hash especial que é o hash do code na mesma solicitação. |
state |
Se um parâmetro state 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 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.
| Parâmetro | Obrigatório/opcional | Descrição |
|---|---|---|
tenant |
obrigatório | O valor {tenant} no caminho da solicitação pode ser usado para controlar quem pode entrar no aplicativo. Os valores válidos são common, organizations, consumers e identificadores de locatário. Para saber mais, confira 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 aplicativo atribui ao seu aplicativo. |
scope |
opcionais | Uma lista de escopos separados por espaços. Os escopos devem ser todos de um único recurso, juntamente com escopos OIDC (profile, openid, email). Para obter mais informações, confira Permissões e consentimento na plataforma de identidade da Microsoft. Esse 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 quais querem o token durante o resgate do token. |
code |
necessárias | O authorization_code que você adquiriu no primeiro segmento do fluxo. |
redirect_uri |
necessárias | O mesmo valor de redirect_uri que foi usado para adquirir o authorization_code. |
grant_type |
obrigatório | Deve ser authorization_code para o fluxo do código de autorização. |
code_verifier |
recomendável | O mesmo code_verifier usado para obter o authorization_code. Obrigatório se o PKCE foi usado na solicitação de concessão de código de autorização. Para mais informações, consulte PKCE RFC. |
client_secret |
necessário para aplicativos 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 de página única porque não é possível armazenar um client_secret de modo confiável em dispositivos ou páginas da Web. Ele é necessário para aplicativos Web e APIs Web, que podem armazenar o client_secret com segurança no lado do servidor. Como todos os parâmetros aqui, o segredo do cliente precisa ser codificado em URL antes de ser enviado. Essa etapa geralmente é feita pelo SDK. Para obter mais informações sobre a codificação de URI, consulte a Especificação de Sintaxe Genérica de URI. O padrão de autenticação básico de fornecer credenciais no cabeçalho de autorização, conforme a RFC 6749, também tem suporte. |
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 | Descrição |
|---|---|---|
tenant |
obrigatório | O valor {tenant} no caminho da solicitação pode ser usado para controlar quem pode entrar no aplicativo. Os valores válidos são common, organizations, consumers e identificadores de locatário. Para obter mais detalhes, confira 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 aplicativo atribui ao seu aplicativo. |
scope |
opcionais | Uma lista de escopos separados por espaços. Os escopos devem ser todos de um único recurso, juntamente com escopos OIDC (profile, openid, email). Para obter mais informações, confira Permissões, consentimento e escopos. Esse 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 quais querem o token durante o resgate do token. |
code |
necessárias | O authorization_code que você adquiriu no primeiro segmento do fluxo. |
redirect_uri |
necessárias | O mesmo valor de redirect_uri que foi usado para adquirir o authorization_code. |
grant_type |
obrigatório | Deve ser authorization_code para o fluxo do código de autorização. |
code_verifier |
recomendável | O mesmo code_verifier que foi usado para obter o authorization_code. Obrigatório se o PKCE foi usado na solicitação de concessão de código de autorização. Para mais informações, consulte PKCE RFC. |
client_assertion_type |
necessário para aplicativos Web confidenciais | O valor precisa ser definido como urn:ietf:params:oauth:client-assertion-type:jwt-bearer para usar uma credencial de certificado. |
client_assertion |
necessário para aplicativos Web confidenciais | Uma declaração, que é um JWT (Token Web JSON), que você precisa criar e assinar com o certificado registrado como as credenciais do aplicativo. Leia mais sobre credenciais de certificado para saber como registrar seu certificado e saber sobre o formato da asserção. |
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..."
}
| Parâmetro | Descrição |
|---|---|
access_token |
O token de acesso solicitado. O aplicativo pode usar esse token para se autenticar no recurso protegido, como uma API Web. |
token_type |
Indica o valor do tipo de token. O único tipo que Microsoft Entra ID dá suporte é 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. Esse parâmetro não é padrão e, se omitido, o token será para os escopos solicitados no trecho inicial do fluxo. |
refresh_token |
Um token de atualização do 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 têm uma vida longa. Eles podem manter o acesso aos recursos por períodos prolongados. Para obter mais detalhes sobre como atualizar um token de acesso, confira Atualizar o token de acesso mais adiante neste artigo. Observação: Somente fornecido se o escopo offline_access for solicitado. |
id_token |
Um Token Web JSON. O aplicativo pode decodificar os segmentos desse token para solicitar informações sobre o usuário que se conectou. O aplicativo pode armazenar os valores em cache e exibi-los. Os clientes confidenciais podem usar esse token para autorização. Para obter mais informações sobre id_tokens, veja a id_token reference. Observação: Somente fornecido se o escopo openid for 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 | Descrição |
|---|---|
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 pode ajudar no diagnóstico. |
timestamp |
A hora na qual 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 os componentes. |
Códigos de erro para erros de ponto de extremidade de token
| Código do Erro | Descrição | Ação do Cliente |
|---|---|---|
invalid_request |
Erro de protocolo, como um parâmetro obrigató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 o verificador de código PKCE é inválido ou expirou. | Tente uma nova solicitação para o ponto de extremidade /authorize e verifique se o parâmetro code_verifier estava correto. |
unauthorized_client |
O cliente autenticado não está autorizado a usar esse tipo de concessão de autorização. | Isso geralmente ocorre quando o aplicativo cliente não está registrado no Microsoft Entra ID ou não é adicionado ao locatário do Microsoft Entra do usuário. O aplicativo pode solicitar que o usuário instale o aplicativo e o adicione ao Microsoft Entra ID. |
invalid_client |
Falha na autenticação de cliente. | As credenciais do cliente não são válidas. Para corrigir isso, o Administrador do Aplicativo atualiza as credenciais. |
unsupported_grant_type |
O servidor de autorização não dá suporte ao tipo de concessão de autorização. | Altere o tipo de concessão na solicitação. Esse tipo de erro deve ocorrer somente durante o desenvolvimento e ser detectado durante os testes iniciais. |
invalid_resource |
O recurso de destino é inválido porque não ele existe, o Microsoft Entra ID não pode encontrá-lo ou ele 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 que o usuário instale o aplicativo e o adicione ao Microsoft Entra ID. |
interaction_required |
Não padrão, pois a especificação OIDC chama esse código apenas no ponto de extremidade /authorize. A solicitação requer interação do usuário. Por exemplo, outra etapa de autenticação é necessária. |
Repita a solicitação /authorize com os mesmos escopos. |
temporarily_unavailable |
O servidor está temporariamente muito ocupado para tratar da solicitação. | Repita a solicitação após um pequeno atraso. O aplicativo cliente pode explicar para o usuário que sua resposta está atrasada devido a uma condição temporária. |
consent_required |
A solicitação requer consentimento do usuário. Esse erro não é padrão. Normalmente, ele é retornado apenas no ponto de extremidade /authorize de acordo com as especificações do OIDC. Retornado quando um parâmetro scope é usado no fluxo de resgate de código que o aplicativo cliente não tem permissão para solicitar. |
O cliente deve retornar o usuário ao ponto de extremidade /authorize com o escopo correto para disparar o consentimento. |
invalid_scope |
O escopo solicitado pelo aplicativo é inválido. | Atualize o valor do parâmetro scope na solicitação de autenticação para um valor válido. |
Observação
Aplicativos de página única podem receber um erro invalid_request indicando que o resgate de token entre origens é permitido somente 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 redirecionamento spa. Revise as etapas de registro do aplicativo para saber como habilitar esse fluxo.
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.”
Importante
Para tokens de atualização enviados a um URI de redirecionamento registrado como spa, o token de atualização expira após 24 horas. Os tokens de atualização adicionais adquiridos usando o token de atualização inicial são executados durante esse tempo de expiração, portanto, os aplicativos precisam estar preparados para executar 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 têm que inserir as credenciais e, geralmente, nem mesmo veem nenhuma experiência do usuário, apenas uma solicitação para recarregar o aplicativo. O navegador precisa acessar a página de logon em um quadro de nível superior para ver a sessão de logon. Isso ocorre devido 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 valor {tenant} no caminho da solicitação pode ser usado para controlar quem pode entrar no aplicativo. Os valores válidos são common, organizations, consumers e identificadores de locatário. Para saber mais, confira Pontos de extremidade. |
client_id |
obrigatório | A ID do aplicativo (cliente) que a experiência centro de administração do Microsoft Entra - Registros de aplicativo atribui ao seu aplicativo. |
grant_type |
obrigatório | Deve ser refresh_token para essa ramificação do código de autorização. |
scope |
opcionais | Uma lista de escopos separados por espaços. Os escopos solicitados nesse trecho precisam ser equivalentes aos escopos solicitados no primeiro trecho authorization_code ou um subconjunto desses escopos. Se os escopos especificados nesta 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, confira Permissões e consentimento na plataforma de identidade da Microsoft. |
refresh_token |
exigido | O refresh_token que você adquiriu no segundo trecho do fluxo. |
client_secret |
obrigató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, pois o client_secret não pode ser armazenado com confiança em dispositivos. Ele é necessário para aplicativos Web e APIs Web, que podem armazenar o client_secret com segurança no lado do servidor. Esse segredo precisa ser codificado por URL. Para obter mais informações, consulte a especificação de sintaxe genérica do URI. |
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..."
}
| Parâmetro | Descrição |
|---|---|
access_token |
O token de acesso solicitado. O aplicativo pode usar esse token para se autenticar no recurso protegido, como uma API Web. |
token_type |
Indica o valor do tipo de token. O único tipo que a ID do Microsoft Entra dá suporte é Portador. |
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 adquirido recentemente para garantir que os tokens de atualização permaneçam válidos pelo tempo máximo possível. Observação: Somente fornecido se o escopo offline_access for solicitado. |
id_token |
Um Token Web JSON não assinado. O aplicativo pode decodificar os segmentos desse token para solicitar informações sobre o usuário que se conectou. O aplicativo pode armazenar em cache os valores e exibi-los, mas não deve confiar neles para nenhuma autorização ou limite de segurança. Para obter mais informações sobre id_token, confira os Tokens de ID da plataforma de identidade da Microsoft. Observação: Somente fornecido se o escopo openid for solicitado. |
Aviso
Não tente validar nem ler tokens de APIs que não sejam suas em seu código, incluindo os tokens deste exemplo. Os tokens de 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 do consumidor (conta Microsoft). Embora a leitura de tokens seja uma ferramenta útil de depuração e aprendizagem, não assuma dependências disso em seu código ou assuma informações específicas sobre tokens que não são de 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 | Descrição |
|---|---|
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 pode ajudar no diagnóstico. |
timestamp |
A hora na qual 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 os componentes. |
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.