Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Aviso
Este conteúdo é destinado à versão mais antiga do Azure AD v1.0. Use a plataforma de identidade da Microsoft para obter novos projetos.
Observação
Se você não informar ao servidor qual recurso você planeja chamar, o servidor não disparará as políticas de Acesso Condicional para esse recurso. Portanto, para ter um gatilho de MFA, você precisará incluir um recurso em sua URL.
O Azure AD (Azure Active Directory) usa o OAuth 2.0 para permitir que você autorize o acesso a aplicativos Web e APIs Web em seu locatário do Azure AD. Este guia é independente de linguagem e descreve como enviar e receber mensagens HTTP sem usar nenhuma de nossas bibliotecas de software livre.
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. Ele é usado para executar autenticação e autorização na maioria dos tipos de aplicativos, incluindo aplicativos Web e aplicativos instalados nativamente.
Registre seu aplicativo com seu locatário do Azure Active Directory
Primeiro, registre seu aplicativo no locatário do Azure AD (Azure Active Directory). Isso lhe dará uma ID de aplicativo para seu aplicativo, bem como permitirá que ele receba tokens.
Entre no portal do Azure.
Escolha sua locação do Azure AD selecionando sua conta no canto superior direito da página, depois selecione a navegação Switch Directory e, em seguida, selecione a locação apropriada.
- Ignore esta etapa se você tiver apenas um locatário do Azure AD em sua conta ou se já tiver selecionado o locatário apropriado do Azure AD.
No portal do Azure, pesquise e selecione do Azure Active Directory.
No menu esquerdo do Azure Active Directory, selecione Registro de Aplicativose, em seguida, selecione Novo registro.
Siga os prompts e crie um novo aplicativo. Não importa se é um aplicativo Web ou um aplicativo de cliente público (mobile & desktop) para este tutorial, mas se você quiser exemplos específicos para aplicativos Web ou aplicativos cliente públicos, confira nossos inícios rápidos.
- Name é o nome do aplicativo e descreve seu aplicativo para usuários finais.
- Em Tipos de conta com suporte, selecione Contas em qualquer diretório organizacional e contas pessoais da Microsoft.
- Forneça o URI de Redirecionamento . Para aplicativos Web, essa é a URL base do seu aplicativo em que os usuários podem entrar. Por exemplo,
http://localhost:12345. Para o cliente público (móvel e desktop), o Azure AD o usa para retornar respostas de token. Insira um valor específico ao seu aplicativo. Por exemplo,http://MyFirstAADApp.
Depois de concluir o registro, o Azure AD atribuirá ao aplicativo um identificador de cliente exclusivo (a ID do aplicativo ). Você precisa desse valor nas próximas seções, portanto, copie-o da página do aplicativo.
Para localizar seu aplicativo no portal do Azure, selecione registros de aplicativoe selecione Exibir todos os aplicativos.
Fluxo de autorização do OAuth 2.0
Em um alto nível, todo o fluxo de autorização para um aplicativo tem esta aparência:
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 endpoint /authorize. Nesta solicitação, o cliente indica as permissões que precisa obter do usuário. Você pode obter o ponto de extremidade de autorização do OAuth 2.0 para o seu inquilino selecionando Registros de aplicativos > Pontos de extremidade no portal do Azure.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%3A12345
&response_mode=query
&resource=https%3A%2F%2Fservice.contoso.com%2F
&state=12345
| Parâmetro | Tipo | Descrição |
|---|---|---|
| inquilino | Necessário | O valor de {tenant} no caminho da solicitação pode ser usado para controlar quem pode entrar no aplicativo. Os valores permitidos são identificadores de locatário, por exemplo, 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 ou contoso.onmicrosoft.com ou common para tokens independentes de locatário |
| ID do cliente | Necessário | A ID do aplicativo atribuída ao aplicativo quando você o registrou no Azure AD. Você pode encontrar isso no portal do Azure. Clique no Azure Active Directory na barra lateral dos serviços, clique em Registros de aplicativo e escolha o aplicativo. |
| tipo_de_resposta | Necessário | É necessário incluir code no fluxo de código de autorização. |
| URI de redirecionamento | recomendado | O redirect_uri do seu aplicativo, em que as respostas de autenticação podem ser enviadas e recebidas pelo aplicativo. Ele deve corresponder exatamente a uma das redirect_uris que você registrou no portal, exceto que ela deve ser codificada em URL. Para aplicativos nativos e móveis, você deve usar o valor padrão de https://login.microsoftonline.com/common/oauth2/nativeclient. |
| response_mode | opcional | Especifica o método que deve ser usado para enviar o token resultante de volta ao aplicativo. Pode ser query, fragment ou form_post.
query fornece o código como um parâmetro de cadeia de caracteres de consulta em seu URI de redirecionamento. Se você estiver solicitando um token de ID usando o fluxo implícito, não poderá usar query conforme especificado na especificação OpenID. Se você estiver solicitando apenas o código, poderá usar query, fragmentou form_post.
form_post executa um POST que contém o código para o URI de redirecionamento. O padrão é query para um fluxo de código. |
| estado | recomendado | Um valor incluído na solicitação que também retorna na resposta do token. Normalmente, é utilizado um valor exclusivo gerado aleatoriamente para impedir ataques de falsificação de pedidos entre sites. O estado também é usado para codificar informações sobre o estado do usuário no aplicativo antes que a solicitação de autenticação ocorra, como a página ou a exibição em que ele estava. |
| recurso | recomendado | O URI da ID do aplicativo da API Web de destino (recurso protegido). Para localizar o URI da ID do Aplicativo, no portal do Azure, clique em Azure Active Directory, clique em Registros de aplicativo, abra a página Configurações do aplicativo e clique em Propriedades. Também pode ser um recurso externo como https://graph.microsoft.com. Isso é necessário em uma das solicitações de autorização ou token. Para garantir menos solicitações de autenticação, coloque-as na solicitação de autorização para garantir que o consentimento seja recebido do usuário. |
| âmbito | Ignorado | Para aplicativos do Azure AD v1, os escopos devem ser configurados estaticamente no portal do Azure nas Configurações de Aplicativos, Permissões Necessárias. |
| solicitação | opcional | Indique o tipo de interação do usuário necessário. Os valores válidos são: logon: o usuário deve ser solicitado a autenticar novamente. select_account: o usuário é solicitado a selecionar uma conta, interrompendo o logon único. O usuário pode selecionar uma conta de entrada existente, inserir suas credenciais para uma conta lembrada ou optar por usar uma conta totalmente diferente. consentimento: o consentimento do usuário foi concedido, mas precisa ser atualizado. O usuário deve ser solicitado a consentir. admin_consent: um administrador deve ser solicitado a consentir em nome de todos os usuários em sua organização |
| login_hint | opcional | Pode ser usado para preencher previamente o campo nome de usuário/endereço de email da página de entrada do usuário, se você souber seu nome de usuário com antecedência. Geralmente, os aplicativos usam esse parâmetro durante a reautenticação, já tendo extraído o nome de usuário de uma sessão anterior usando o atributo de declaração preferred_username. |
| domain_hint | opcional | Fornece uma dica sobre o locatário ou domínio que o usuário deve usar para entrar. O valor do domain_hint é um domínio registrado para o locatário. Se o locatário for federado a um diretório local no local, o Azure Active Directory redirecionará para o servidor de federação do locatário especificado. |
| método_de_desafio_de_código | recomendado | O método utilizado para codificar o code_verifier para o parâmetro code_challenge. Pode ser um de plain ou S256. Se excluído, code_challenge será considerado texto não criptografado se code_challenge estiver incluído. O Azure AAD v1.0 dá suporte a ambos plain e S256. Para mais informações, consulte PKCE RFC. |
| desafio de código | recomendado | Usado para proteger concessões de código de autorização através da Prova de Chave para Troca de Código (PKCE) de um cliente nativo ou público. Necessário se code_challenge_method estiver incluído. Para mais informações, consulte PKCE RFC. |
Observação
Se o usuário fizer parte de uma organização, um administrador da organização poderá consentir ou recusar em nome do usuário ou permitir que o usuário consenta. O usuário recebe a opção de consentir somente quando o administrador permitir.
Neste ponto, o usuário é solicitado a inserir suas credenciais e consentimento para as permissões solicitadas pelo aplicativo no portal do Azure. Depois que o usuário autentica e concede consentimento, o Azure AD envia uma resposta ao seu aplicativo no redirect_uri endereço em sua solicitação com o código.
Resposta bem-sucedida
Uma resposta bem-sucedida pode ter esta aparência:
GET HTTP/1.1 302 Found
Location: http://localhost:12345/?code= AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA&session_state=7B29111D-C220-4263-99AB-6F6E135D75EF&state=D79E5777-702E-4260-9A62-37F75FF22CCE
| Parâmetro | Descrição |
|---|---|
| consentimento do administrador | O valor será True se um administrador consentiu com um prompt de solicitação de consentimento. |
| código | O código de autorização solicitado pelo aplicativo. O aplicativo pode usar o código de autorização para solicitar um token de acesso para o recurso de destino. |
| estado_de_sessão | Um valor exclusivo que identifica a sessão de usuário atual. Esse valor é um GUID, mas deve ser tratado como um valor opaco passado sem ser examinado. |
| estado | Se um parâmetro de estado estiver incluído no pedido, o mesmo valor deverá aparecer na resposta. É uma boa prática para o aplicativo verificar se os valores de estado na solicitação e resposta são idênticos antes de usar a resposta. Isso ajuda a detectar ataques de Falsificação de Solicitação Entre Sites (CSRF) contra o cliente. |
Resposta de erro
As respostas de erro também podem ser enviadas para redirect_uri, de modo que o aplicativo as trate adequadamente.
GET http://localhost:12345/?
error=access_denied
&error_description=the+user+canceled+the+authentication
| Parâmetro | Descrição |
|---|---|
| erro | Um valor de código de erro definido na Seção 5.2 da Estrutura de Autorização do OAuth 2.0. A próxima tabela descreve os códigos de erro retornados pelo Azure AD. |
| descrição_do_erro | Uma descrição mais detalhada do erro. Esta mensagem não se destina a ser amigável ao usuário final. |
| estado | O valor de estado é um valor não reutilizado gerado aleatoriamente que é enviado na solicitação e retornado na resposta para evitar ataques CSRF (solicitação forjada entre sites). |
Códigos de erro para erros de endpoint 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 de erro | Descrição | Ação do cliente |
|---|---|---|
| solicitação_inválida | Erro de protocolo, como um parâmetro obrigatório ausente. | Corrija e reenvie a solicitação. Esse é um erro de desenvolvimento e normalmente é capturado durante o teste inicial. |
| cliente_não_autorizado | 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 Azure AD ou não é adicionado ao locatário do Azure AD do usuário. O aplicativo pode solicitar ao usuário instruções para instalar o aplicativo e adicioná-lo ao Azure AD. |
| acesso_negado | Proprietário do recurso negou consentimento | O aplicativo cliente pode notificar o usuário de que ele não pode prosseguir, a menos que o usuário consenta. |
| tipo_de_resposta_não_suportado | 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 e normalmente é capturado durante o teste inicial. |
| erro_do_servidor | 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 sua resposta está atrasada devido a um erro temporário. |
| temporariamente_indisponível | O servidor está temporariamente muito ocupado para tratar da solicitação. | Tente novamente a solicitação. O aplicativo cliente pode explicar ao usuário que sua resposta está atrasada devido a uma condição temporária. |
| recurso_inválido | O recurso de destino é inválido porque ele não existe, o Azure AD não pode encontrá-lo ou não está configurado corretamente. | Isso indica que o recurso, se ele 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 Azure AD. |
Usar o código de autorização para solicitar um token de acesso
Agora que você adquiriu um código de autorização e recebeu permissão do usuário, você pode trocar o código por um token de acesso ao recurso desejado, enviando uma solicitação POST para o endpoint /token.
// Line breaks for legibility only
POST /{tenant}/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA
&redirect_uri=https%3A%2F%2Flocalhost%3A12345
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=p@ssw0rd
//NOTE: client_secret only required for web apps
| Parâmetro | Tipo | Descrição |
|---|---|---|
| inquilino | Necessário | O valor de {tenant} no caminho da solicitação pode ser usado para controlar quem pode entrar no aplicativo. Os valores permitidos são identificadores de locatário, por exemplo, 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 ou contoso.onmicrosoft.com ou common para tokens independentes de locatário |
| ID do cliente | Necessário | A ID do aplicativo atribuída ao seu aplicativo quando você o registrou no Azure AD. Você pode encontrar isso no portal do Azure. A ID do aplicativo é exibida nas configurações do registro do aplicativo. |
| tipo_de_concessão | Necessário | Deve ser authorization_code para o fluxo do código de autorização. |
| código | Necessário | O authorization_code que você adquiriu na seção anterior |
| URI de redirecionamento | Necessário |
redirect_uri registrado no aplicativo cliente. |
| segredo_do_cliente | necessário para aplicativos Web, não permitidos para clientes públicos | O segredo do aplicativo que você criou no portal do Azure para seu aplicativo em Chaves. Ele não pode ser usado em um aplicativo nativo (cliente público), porque client_secrets não pode ser armazenado de forma confiável em dispositivos. Isso é necessário para aplicativos Web e APIs Web (todos os clientes confidenciais), que têm a capacidade de armazenar o client_secret de forma segura no lado do servidor. O client_secret deve ser codificado em URL antes de ser enviado. |
| recurso | recomendado | O URI da ID do aplicativo da API Web de destino (recurso protegido). Para localizar o URI da ID do Aplicativo, no portal do Azure, clique em Azure Active Directory, clique em Registros de aplicativo, abra a página Configurações do aplicativo e clique em Propriedades. Também pode ser um recurso externo como https://graph.microsoft.com. Isso é necessário em uma das solicitações de autorização ou token. Para reduzir o número de solicitações de autenticação, inclua-o na solicitação de autorização para garantir que o usuário forneça o consentimento. Na solicitação de autorização e na solicitação de token, os parâmetros do recurso devem corresponder. |
| verificador_de_codigo | opcional | O mesmo code_verifier usado para obter o código de autorização. Obrigatório se o PKCE foi usado na solicitação de concessão de código de autorização. Para obter mais informações, consulte o RFC do PKCE |
Para localizar o URI da ID do Aplicativo, no portal do Azure, clique em Azure Active Directory, clique em Registros de aplicativo, abra a página Configurações do aplicativo e clique em Propriedades.
Resposta bem-sucedida
O Azure AD retorna um token de acesso após uma resposta bem-sucedida. Para minimizar as chamadas de rede do aplicativo cliente e sua latência associada, o aplicativo cliente deve armazenar em cache tokens de acesso para o tempo de vida do token especificado na resposta OAuth 2.0. Para determinar o tempo de vida do token, use os valores dos parâmetros expires_in ou expires_on.
Se um recurso de API Web retornar um invalid_token código de erro, isso poderá indicar que o recurso determinou que o token expirou. Se os tempos de relógio do cliente e do recurso forem diferentes (conhecidos como "distorção de tempo"), o recurso poderá considerar que o token expirou antes que o token seja removido do cache do cliente. Se isso ocorrer, desmarque o token do cache, mesmo que ele ainda esteja dentro de seu tempo de vida calculado.
Uma resposta bem-sucedida pode ter esta aparência:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
"token_type": "Bearer",
"expires_in": "3600",
"expires_on": "1388444763",
"resource": "https://service.contoso.com/",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA",
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83ZmU4MTQ0Ny1kYTU3LTQzODUtYmVjYi02ZGU1N2YyMTQ3N2UvIiwiaWF0IjoxMzg4NDQwODYzLCJuYmYiOjEzODg0NDA4NjMsImV4cCI6MTM4ODQ0NDc2MywidmVyIjoiMS4wIiwidGlkIjoiN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlIiwib2lkIjoiNjgzODlhZTItNjJmYS00YjE4LTkxZmUtNTNkZDEwOWQ3NGY1IiwidXBuIjoiZnJhbmttQGNvbnRvc28uY29tIiwidW5pcXVlX25hbWUiOiJmcmFua21AY29udG9zby5jb20iLCJzdWIiOiJKV3ZZZENXUGhobHBTMVpzZjd5WVV4U2hVd3RVbTV5elBtd18talgzZkhZIiwiZmFtaWx5X25hbWUiOiJNaWxsZXIiLCJnaXZlbl9uYW1lIjoiRnJhbmsifQ."
}
| Parâmetro | Descrição |
|---|---|
| token_de_acesso | O token de acesso solicitado. Essa é uma cadeia de caracteres opaca– depende do que o recurso espera receber e não se destina ao cliente examinar. O aplicativo pode usar esse token para se autenticar no recurso protegido, como uma API Web. |
| tipo_de_token | Indica o valor do tipo de token. O único tipo compatível com o Azure AD é o Portador. Para obter mais informações sobre tokens de portador, consulte OAuth2.0 Authorization Framework: Bearer Token Usage (RFC 6750) |
| expira_em | Por quanto tempo o token de acesso é válido (em segundos). |
| expira_em | A hora em que o token de acesso expira. A data é representada como o número de segundos de 1970-01-01T0:0:0Z UTC até a hora de expiração. Esse valor é usado para determinar o tempo de vida de tokens em cache. |
| recurso | O URI de ID do aplicativo da API Web (recurso protegido). |
| âmbito | Permissões de impersonação concedidas ao aplicativo cliente. A permissão padrão é user_impersonation. O proprietário do recurso protegido pode registrar valores adicionais no Azure AD. |
| token de atualização | Um token de atualização do OAuth 2.0. A aplicação pode utilizar este token para adquirir tokens de acesso adicionais após a expiração do token de acesso atual. Os tokens de atualização são de longa duração e podem ser usados para manter o acesso aos recursos por longos períodos de tempo. |
| id_token | Um JSON Web Token (JWT) não assinado que representa um token de ID. O aplicativo pode base64Url decodificar os segmentos desse token para solicitar informações sobre o usuário que entrou. O aplicativo pode armazenar em cache os valores e exibi-los, mas não deve depender deles para quaisquer limites de autorização ou segurança. |
Para obter mais informações sobre tokens Web JSON, consulte a especificação de rascunho do JWT IETF. Para saber mais sobre id_tokens, consulte o fluxo do OpenID Connect v1.0.
Resposta de erro
Os erros de ponto de extremidade de emissão de token são códigos de erro HTTP, pois o cliente chama diretamente o ponto de extremidade de emissão de token. Além do código de status HTTP, o ponto de extremidade de emissão de token do Azure AD também retorna um documento JSON com objetos que descrevem o erro.
Uma resposta de erro de exemplo pode ter esta aparência:
{
"error": "invalid_grant",
"error_description": "AADSTS70002: Error validating credentials. AADSTS70008: The provided authorization code or refresh token is expired. Send a new interactive authorization request for this user and resource.\r\nTrace ID: 3939d04c-d7ba-42bf-9cb7-1e5854cdce9e\r\nCorrelation ID: a8125194-2dc8-4078-90ba-7b6592a7f231\r\nTimestamp: 2016-04-11 18:00:12Z",
"error_codes": [
70002,
70008
],
"timestamp": "2016-04-11 18:00:12Z",
"trace_id": "3939d04c-d7ba-42bf-9cb7-1e5854cdce9e",
"correlation_id": "a8125194-2dc8-4078-90ba-7b6592a7f231"
}
| Parâmetro | Descrição |
|---|---|
| erro | Uma cadeia de caracteres de códigos de erro que pode ser usada para classificar tipos de erro que ocorrem e pode ser usada para responder aos erros. |
| descrição_do_erro | 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. |
| carimbo de data/hora | 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 status HTTP
A tabela a seguir lista os códigos de status HTTP que o ponto de extremidade de emissão de token retorna. Em alguns casos, o código de erro é suficiente para descrever a resposta, mas se houver erros, você precisará analisar o documento JSON que acompanha e examinar seu código de erro.
| Código HTTP | Descrição |
|---|---|
| 400 | Código HTTP padrão. Usado na maioria dos casos e normalmente é devido a uma solicitação malformulada. Corrija e reenvie a solicitação. |
| 401 | Falha na autenticação. Por exemplo, a solicitação não tem o parâmetro client_secret. |
| 403 | Falha na autorização. Por exemplo, o usuário não tem permissão para acessar o recurso. |
| 500 | Ocorreu um erro interno no serviço. Tente novamente a solicitação. |
Códigos de erro para erros de ponto de extremidade de token
| Código de erro | Descrição | Ação do cliente |
|---|---|---|
| solicitação_inválida | Erro de protocolo, como um parâmetro obrigatório ausente. | Corrigir e reenviar a solicitação |
| concessão inválida | O código de autorização é inválido ou expirou. | Tente uma nova solicitação para o /authorize endpoint |
| cliente_não_autorizado | 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 Azure AD ou não é adicionado ao locatário do Azure AD do usuário. O aplicativo pode solicitar ao usuário instruções para instalar o aplicativo e adicioná-lo ao Azure AD. |
| cliente_inválido | Falha na autenticação de cliente. | As credenciais do cliente não são válidas. Para corrigi-las, 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. |
| recurso_inválido | O recurso de destino é inválido porque ele não existe, o Azure AD não pode encontrá-lo ou não está configurado corretamente. | Isso indica que o recurso, se ele 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 Azure AD. |
| interação necessária | A solicitação requer interação do usuário. Por exemplo, é necessária uma etapa de autenticação adicional. | Em vez de uma solicitação não interativa, tente novamente com uma solicitação de autorização interativa para o mesmo recurso. |
| temporariamente_indisponível | O servidor está temporariamente muito ocupado para tratar da solicitação. | Tente novamente a solicitação. O aplicativo cliente pode explicar ao usuário que sua resposta está atrasada devido a uma condição temporária. |
Usar o token de acesso para acessar o recurso
Agora que você adquiriu com êxito um token access_token, você pode usar o token em solicitações para APIs Web, incluindo-o no cabeçalho Authorization. A especificação RFC 6750 explica como usar tokens de portador em solicitações HTTP para acessar recursos protegidos.
Solicitação de exemplo
GET /data HTTP/1.1
Host: service.contoso.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ
Resposta de erro
Os recursos protegidos que implementam o RFC 6750 emitem códigos de status HTTP. Se a solicitação não incluir credenciais de autenticação ou estiver faltando o token, a resposta incluirá um WWW-Authenticate cabeçalho. Quando uma solicitação falha, o servidor de recursos responde com o código de status HTTP e um código de erro.
Veja a seguir um exemplo de uma resposta malsucedida quando a solicitação do cliente não inclui o token de portador:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer authorization_uri="https://login.microsoftonline.com/contoso.com/oauth2/authorize", error="invalid_token", error_description="The access token is missing.",
Parâmetros de erro
| Parâmetro | Descrição |
|---|---|
| authorization_uri | O URI (ponto de extremidade físico) do servidor de autorização. Esse valor também é usado como uma chave de pesquisa para obter mais informações sobre o servidor de um ponto de extremidade de descoberta. O cliente deve validar se o servidor de autorização é confiável. Quando o recurso é protegido pelo Azure AD, é suficiente verificar se a URL começa com |
| erro | Um valor de código de erro definido na Seção 5.2 da Estrutura de Autorização do OAuth 2.0. |
| descrição_do_erro | Uma descrição mais detalhada do erro. Esta mensagem não se destina a ser amigável ao usuário final. |
| id_recurso | Retorna o identificador exclusivo do recurso. O aplicativo cliente pode usar esse identificador como o valor do resource parâmetro quando solicita um token para o recurso. É importante que o aplicativo cliente verifique esse valor, caso contrário, um serviço mal-intencionado poderá induzir um ataque de elevação de privilégios A estratégia recomendada para evitar um ataque é verificar se a |
Códigos de erro do sistema Bearer
A especificação RFC 6750 define os seguintes erros para elementos que usam o cabeçalho WWW-Authenticate e o esquema Bearer na resposta.
| Código de Estado HTTP | Código de erro | Descrição | Ação do cliente |
|---|---|---|---|
| 400 | solicitação_inválida | A solicitação não está bem formada. Por exemplo, pode estar faltando um parâmetro ou usando o mesmo parâmetro duas vezes. | Corrija o erro e repita a solicitação. Esse tipo de erro deve ocorrer somente durante o desenvolvimento e ser detectado no teste inicial. |
| 401 | token inválido | O token de acesso está ausente, inválido ou revogado. O valor do parâmetro error_description fornece detalhes adicionais. | Solicite um novo token do servidor de autorização. Se o novo token falhar, ocorrerá um erro inesperado. Envie uma mensagem de erro para o usuário e tente novamente após atrasos aleatórios. |
| 403 | esfera insuficiente | O token de acesso não contém as permissões de representação necessárias para acessar o recurso. | Envie uma nova solicitação de autorização para o endpoint de autorização. Se a resposta contiver o parâmetro de escopo, use o valor de escopo na solicitação para o recurso. |
| 403 | acesso_insuficiente | O assunto do token não tem as permissões necessárias para acessar o recurso. | Solicite ao usuário que use uma conta diferente ou solicite permissões para o recurso especificado. |
Atualizando os tokens de acesso
Os Tokens de Acesso são de curta duração e devem ser atualizados depois que expirarem para continuar acessando recursos. Você pode atualizar o access_token enviando outra solicitação POST para o ponto de extremidade /token, mas desta vez fornecendo o refresh_token em vez do code. Os tokens de atualização são válidos para todos os recursos para os quais seu cliente já recebeu consentimento para acessar, portanto, um token de atualização emitido em uma solicitação resource=https://graph.microsoft.com pode ser usado para solicitar um novo token resource=https://contoso.com/apide acesso.
Os tokens de atualização não têm tempos de vida especificados. 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 desejada. Seu aplicativo deve antecipar e lidar corretamente com erros retornados pelo endpoint de emissão de token.
Quando você receber uma resposta com um erro de token de atualização, descarte o token de atualização atual e solicite um novo código de autorização ou token de acesso. Particularmente, ao usar um token de atualização no fluxo de Concessão de Código de Autorização, se você receber uma resposta com os códigos de erro interaction_required ou invalid_grant, descarte o token de atualização e solicite um novo código de autorização.
Uma solicitação de exemplo para o endpoint específico do locatário (você também pode usar o endpoint comum) para obter um novo token de acesso usando um token de atualização tem o seguinte formato:
// Line breaks for legibility only
POST /{tenant}/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for web apps
Resposta bem-sucedida
Uma resposta de token bem-sucedida terá a seguinte aparência:
{
"token_type": "Bearer",
"expires_in": "3600",
"expires_on": "1460404526",
"resource": "https://service.contoso.com/",
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
"refresh_token": "AwABAAAAv YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl PM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfmVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA"
}
| Parâmetro | Descrição |
|---|---|
| tipo_de_token | O tipo de token. O único valor com suporte é Bearer. |
| expira_em | O tempo de vida restante do token em segundos. Um valor típico é 3600 (uma hora). |
| expira_em | A data e a hora em que o token expira. A data é representada como o número de segundos de 1970-01-01T0:0:0Z UTC até a hora de expiração. |
| recurso | Identifica o recurso protegido que o token de acesso pode ser usado para acessar. |
| âmbito | Permissões de representação concedidas ao aplicativo cliente nativo. A permissão padrão é user_impersonation. O proprietário do recurso de destino pode registrar valores alternativos no Azure AD. |
| token_de_acesso | O novo token de acesso solicitado. |
| token de atualização | Um novo OAuth 2.0 refresh_token que pode ser usado para solicitar novos tokens de acesso quando o da resposta expirar. |
Resposta de erro
Uma resposta de erro de exemplo pode ter esta aparência:
{
"error": "invalid_resource",
"error_description": "AADSTS50001: The application named https://foo.microsoft.com/mail.read was not found in the tenant named 295e01fc-0c56-4ac3-ac57-5d0ed568f872. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You might have sent your authentication request to the wrong tenant.\r\nTrace ID: ef1f89f6-a14f-49de-9868-61bd4072f0a9\r\nCorrelation ID: b6908274-2c58-4e91-aea9-1f6b9c99347c\r\nTimestamp: 2016-04-11 18:59:01Z",
"error_codes": [
50001
],
"timestamp": "2016-04-11 18:59:01Z",
"trace_id": "ef1f89f6-a14f-49de-9868-61bd4072f0a9",
"correlation_id": "b6908274-2c58-4e91-aea9-1f6b9c99347c"
}
| Parâmetro | Descrição |
|---|---|
| erro | Uma cadeia de caracteres de códigos de erro que pode ser usada para classificar tipos de erro que ocorrem e pode ser usada para responder aos erros. |
| descrição_do_erro | Uma mensagem de erro específica que pode ajudar um desenvolvedor a identificar a causa raiz de um erro de autenticação. |
| códigos_de_erro | Uma lista de códigos de erro específicos do STS que pode ajudar no diagnóstico. |
| carimbo de data/hora | 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
Para saber mais sobre o ponto de extremidade do Azure AD v1.0 e como adicionar autenticação e autorização a seus aplicativos Web e APIs Web, consulte aplicativos de exemplo.