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 web 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 partilha de recursos entre origens (CORS): siga os passos em URI de redirecionamento: MSAL.js 2.0 com o fluxo de código de autenticação.
-
Atualizar um URI de redirecionamento: Defina o URI de redirecionamento
typeparaspausando o editor de manifesto da aplicação no centro de administração do Microsoft Entra.
O tipo de redirecionamento spa é retrocompatível com o fluxo implícito. As aplicações que atualmente usam o fluxo implícito para obter tokens podem ser alteradas para o tipo de URI de redirecionamento spa sem problemas e continuar a usar o fluxo implícito. Apesar dessa compatibilidade com versões anteriores, recomendamos que se 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/oauth2/v2.0/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 endpoint. Neste exemplo de solicitação, o cliente solicita as openid, offline_access e https://graph.microsoft.com/mail.read permissões do usuário.
Algumas permissões são restritas ao administrador, por exemplo, usar Directory.ReadWrite.All para gravar dados no diretório de uma organização. 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 é fazer com que o único utilizador atual inicie sessão, mostrar o seletor de contas se houver vários utilizadores ou mostrar a página de login se não houver utilizadores 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 {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 inscreve um utilizador de um tenant para outro tenant, você deve fornecer o identificador de tenant para conectar o utilizador ao tenant de recurso. Para obter mais informações, consulte Pontos de extremidade. |
client_id |
obrigatório | O ID da Aplicação (cliente) que a experiência de Registos de Aplicações no Centro de Administração do Microsoft Entra atribuiu à sua aplicação. |
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 da sua aplicação, onde as respostas de autenticação podem ser enviadas e recebidas pela sua aplicação. 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 se pretende que o utilizador 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. O suporte também é oferecido se solicitar apenas um código.- form_post: Executa um POST contendo o código para o seu URI de redirecionamento. Suportado 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/ela poderia codificar a página ou visualização em que 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_hintdeclaraçã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, assume-se que code_challenge é considerado texto simples se code_challenge for incluído. A plataforma de identidade da Microsoft suporta tanto plain como 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 se autentica e concede consentimento, a plataforma de identidade da Microsoft retorna uma resposta ao seu aplicativo no local indicado por redirect_uri, usando o método especificado no parâmetro response_mode.
Resposta com êxito
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 a aplicação 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 redirect_uri para que a aplicação possa lidar com elas 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 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 do endpoint 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 | Descrição | Ação do Cliente |
|---|---|---|
invalid_request |
Erro de protocolo, como a ausência de um parâmetro obrigatório. | 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 proprietário do recurso negou consentimento | 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, este erro sinaliza que deve-se ativar a configuração de concessão implícita do token de ID no registo da aplicação 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 |
Demasiados ou nenhum utilizador 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 leva em consideração 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 | Descrição |
|---|---|---|
response_type |
obrigatório | A adição de id_token indica ao servidor que o aplicativo gostaria de um token ID na resposta do ponto de extremidade /authorize. |
scope |
obrigatório | Para tokens de ID, este parâmetro deve ser atualizado para incluir os escopos de tokens de ID: openid, e 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, ou fragment se a solicitação incluir um id_tokenresponse_type conforme especificado na especificação OpenID. Recomendamos que os aplicativos usem form_post, especialmente ao usar http://localhost como um URI de redirecionamento. |
O uso de fragment como modo de resposta causa problemas para aplicações web que leem o código a partir 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 | 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 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 aplicações na 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, pode resgatar o code em um recurso access_token. Resgate o(a) code enviando um pedido POST para o endpoint /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 {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 Identificação (ID) do aplicativo (cliente) que a página Centro de administração do Microsoft Entra – Registo de aplicações atribuiu à sua aplicação. |
scope |
opcional | Uma lista de escopos separados por espaço. 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 adquiriste na primeira fase 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 "Basic auth" em que se fornecem 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 | 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 detalhes, consulte Pontos de extremidade. |
client_id |
obrigatório | A ID da Aplicação (cliente) que a página do Centro de administração do Microsoft Entra – Registo de aplicações atribuiu à sua aplicação. |
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, openid, email). 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 | A authorization_code que adquiriste na primeira etapa 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 a fim de 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 precisas criar e assinar com o certificado que registaste como credencial para a tua aplicação. Leia sobre credenciais de certificado para saber como registar o seu certificado e o formato da afirmaçã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 | Descrição |
|---|---|
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, caso seja omitido, o token é para as permissões solicitadas 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 o offline_access âmbito for solicitado. |
id_token |
Um JSON Web Token. 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 | 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 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 no terminal de token
| Código de Erro | Descrição | Ação do Cliente |
|---|---|---|
invalid_request |
Erro de protocolo, tal como a falta de um parâmetro obrigatório. | 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 |
Fora do padrão, pois a especificação OIDC exige esse código apenas no endpoint /authorize. 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 parâmetro scope é usado no fluxo de resgate de código e o aplicativo cliente não tem permissão para solicitar esse parâmetro. |
O cliente deve enviar o utilizador de volta ao ponto de extremidade /authorize 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 usado para o redirecionamento ao solicitar o token não foi marcado como um URI de redirecionamento spa. Analise as etapas de registro do aplicativo sobre como habilitar esse fluxo.
Usar o token de acesso
Agora que adquiriste com êxito um access_token, podes 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 são de curta duração. Atualize-os depois que expirarem para continuar acessando recursos. Você pode fazer isso enviando outra POST solicitação ao /token endpoint. 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. A sua aplicação precisa esperar e lidar com erros devolvidos pelo endpoint de emissão de tokens. 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 mantêm esse mesmo tempo de expiração, portanto, os aplicativos devem estar preparados para executar de novo o fluxo de código de autorização mediante uma autenticação interativa para obter um novo token de atualização a cada 24 horas. Os utilizadores não precisam inserir as suas credenciais e, geralmente, não veem nenhuma experiência do utilizador, apenas um recarregamento da sua aplicação. 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 | O ID da Aplicação (cliente) que a experiência do Centro de Administração do Microsoft Entra – Registo de Aplicações atribuiu à sua aplicação. |
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 foi adquirido na segunda etapa 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 | Descrição |
|---|---|
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 tiver sido 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 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_token, consulte os tokens de ID da plataforma de identidade da Microsoft. Nota: Apenas fornecido se o openid âmbito tenha sido 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 | 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 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 para o 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.