Partilhar via


Autorizar o acesso a aplicativos Web do Azure Ative Directory usando o fluxo de concessão de código OAuth 2.0

Advertência

Este conteúdo destina-se ao ponto de extremidade do Azure AD v1.0 mais antigo. Utilize a plataforma de identidade da Microsoft para novos projetos.

Observação

Se você não informar ao servidor qual recurso você planeja chamar, o servidor não acionará as políticas de Acesso Condicional para esse recurso. Portanto, para ter o gatilho de MFA, você precisará incluir um recurso em sua URL.

O Azure Ative Directory (Azure AD) 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 do idioma e descreve como enviar e receber mensagens HTTP sem usar nenhuma de nossas bibliotecas de código aberto.

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. Ele é usado para executar autenticação e autorização na maioria dos tipos de aplicativos, incluindo aplicativos Web e aplicativos instalados nativamente.

Registe a sua aplicação com o seu inquilino do AD

Primeiro, registre seu aplicativo com seu locatário do Azure Ative Directory (Azure AD). Isso lhe dará uma ID de aplicativo para seu aplicativo, bem como permitirá que ele receba tokens.

  1. Inicie sessão no portal Azure.

  2. Escolha o seu inquilino do Azure AD selecionando a sua conta no canto superior direito da página, seguido pela seleção da navegação Alternar Diretório e, em seguida, selecione o inquilino apropriado.

    • 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.
  3. No portal do Azure, procure e selecione Azure Ative Directory.

  4. No menu esquerdo Azure Ative Directory, selecione Registos de Aplicações e, em seguida, selecione Novo registo.

  5. Siga as instruções e crie um novo aplicativo. Não importa se é uma aplicação web ou uma aplicação cliente público (móvel & desktop) para este tutorial, mas se pretender exemplos específicos para aplicações web ou aplicações cliente público, confira os nossos guias de início rápido.

    • Nome é o nome do aplicativo e descreve seu aplicativo para os usuários finais.
    • Em Tipos de conta suportados, selecione Contas em qualquer diretório organizacional e contas pessoais da Microsoft.
    • Forneça o URI de redirecionamento . Para aplicações Web, este é o URL base da sua aplicação onde os utilizadores podem iniciar sessão. Por exemplo, http://localhost:12345. Para cliente público (móvel & desktop), o Azure AD o usa para retornar respostas de token. Insira um valor específico para seu aplicativo. Por exemplo, http://MyFirstAADApp.
  6. Depois de concluir o registro, o Azure AD atribuirá ao seu aplicativo um identificador de cliente exclusivo (o ID do Aplicativo). Você precisa desse valor nas próximas seções, portanto, copie-o da página do aplicativo.

  7. Para localizar a sua aplicação no portal do Azure, selecione Registos de aplicaçõese, em seguida, selecione Ver todas as aplicações.

Fluxo de autorização do OAuth 2.0

Em um alto nível, todo o fluxo de autorização para um aplicativo se parece um pouco com isto:

Fluxo de código de autenticação OAuth

Solicitar um código de autorização

O fluxo de código de autorização começa quando o cliente direciona o utilizador para o endpoint /authorize. Nessa solicitação, o cliente indica as permissões que precisa adquirir do usuário. Você pode obter o ponto de extremidade de autorização OAuth 2.0 para seu locatário selecionando Pontos de extremidade de registros de > aplicativo 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 obrigatório O {tenant} valor 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 do locatário
ID do cliente obrigató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. Clique em Azure Ative Directory na barra lateral de serviços, clique em Registros de aplicativo e escolha o aplicativo.
tipo_de_resposta obrigatório Deve incluir code para o fluxo de código de autorização.
uri_de_redirecionamento recomendado 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 redirect_uris que você registrou no portal, exceto que deve ser codificado por URL. Para aplicativos nativos & móveis, você deve usar o valor padrão de https://login.microsoftonline.com/common/oauth2/nativeclient.
modo_de_resposta opcional Especifica o método que deve ser usado para enviar o token resultante de volta para seu aplicativo. Pode ser query, fragment, ou form_post. query fornece o código como um parâmetro de cadeia de caracteres de consulta no URI de redirecionamento. Se você estiver solicitando um token de ID usando o fluxo implícito, não poderá usá-lo 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 é retornado na resposta do token. Um valor exclusivo gerado aleatoriamente é normalmente usado para evitar ataques de falsificação de solicitação entre sites. O estado também é usado para codificar informações sobre o estado do usuário no aplicativo antes da solicitação de autenticação ocorrer, como a página ou a exibição em que eles estavam.
recurso recomendado O URI do ID do aplicativo da API Web de destino (recurso seguro). Para localizar o URI da ID do Aplicativo, no portal do Azure, clique em Azure Ative Directory, clique em Registros de aplicativos, 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-a na solicitação de autorização para garantir que o consentimento seja recebido do usuário.
Alcance ignorado Para aplicativos do Azure AD v1, os escopos devem ser configurados estaticamente no portal do Azure em Configurações de aplicativos, Permissões necessárias.
Sugestão opcional Indique o tipo de interação do usuário necessária.

Os valores válidos são:

login: 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 conectada existente, inserir suas credenciais para uma conta lembrada ou optar por usar uma conta completamente 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 pré-preencher o campo de nome de usuário/endereço de e-mail da página de login do usuário, se você souber seu nome de usuário com antecedência. Muitas vezes, os aplicativos usam esse parâmetro durante a reautenticação, já tendo extraído o nome de usuário de um login anterior usando a declaração preferred_username.
sugestão_de_domínio 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 estiver federado a um diretório local, o AAD redirecionará para o servidor de federação de locatário especificado.
método_desafio_código recomendado O método usado para codificar o code_verifier para o code_challenge parâmetro. Pode ser um dos plain ou S256. Se excluído, assume-se que code_challenge é considerado texto simples se code_challenge for incluído. O Azure AAD v1.0 suporta tanto o plain como o S256. Para obter mais informações, consulte a RFC PKCE.
desafio de código recomendado Usado para proteger concessões de código de autorização via Proof Key for Code Exchange (PKCE) de um cliente nativo ou público. Obrigatório se code_challenge_method estiver incluído. Para obter mais informações, consulte a RFC PKCE.

Observação

Se o usuário fizer parte de uma organização, um administrador da organização pode consentir ou recusar em nome do usuário, ou permitir que o usuário consinta. O utilizador tem a opção de consentir apenas quando o administrador o permite.

Neste ponto, o usuário é solicitado a inserir suas credenciais e consentir com 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 endereço em redirect_uri sua solicitação com o código.

Resposta com êxito

Uma resposta bem-sucedida pode ser assim:

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_de_administrador O valor é True se um administrador consentiu com um prompt de solicitação de consentimento.
código 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.
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 que é aprovado sem exame.
Estado Se um parâmetro de estado for incluído na solicitação, o mesmo valor deverá aparecer na resposta. É uma boa prática para o aplicativo verificar se os valores de estado na solicitação e na resposta são idênticos antes de usar a resposta. Isso ajuda a detetar 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 o redirect_uri para que o aplicativo possa tratá-las 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 do OAuth 2.0 Authorization Framework. A próxima tabela descreve os códigos de erro que o Azure AD retorna.
descrição_do_erro Uma descrição mais detalhada do erro. Esta mensagem não pretende ser de fácil utilização.
Estado O valor de estado é um valor não reutilizado gerado aleatoriamente que é enviado na solicitação e retornado na resposta para evitar ataques de falsificação de solicitação entre sites (CSRF).

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
pedido_inválido Erro de protocolo, como a ausência de um parâmetro obrigatório. Corrija e reenvie a solicitação. Este é um erro de desenvolvimento e normalmente é detetado 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 O proprietário do recurso negou consentimento O aplicativo cliente pode notificar o usuário de que não pode prosseguir a menos que o usuário consinta.
tipo_de_resposta_não_suportado O servidor de autorização não suporta o tipo de resposta na solicitação. Corrija e reenvie a solicitação. Este é um erro de desenvolvimento e normalmente é detetado durante o teste inicial.
erro_do_servidor 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 devido a um erro temporário.
temporariamente_indisponível 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.
recurso inválido O recurso de destino é inválido porque não existe, o Azure AD não pode encontrá-lo ou não está configurado corretamente. Isso 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 Azure AD.

Use o código de autorização para solicitar um token de acesso

Agora que já adquiriu um código de autorização e recebeu permissão do utilizador, pode trocar o código por um token de acesso ao recurso desejado, enviando uma solicitação POST para o ponto de extremidade /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 obrigatório O {tenant} valor 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 do locatário
ID do cliente obrigató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 obrigatório Deve ser authorization_code para o fluxo de código de autorização.
código obrigatório O authorization_code que adquiriste na secção anterior
uri_de_redirecionamento obrigatório Um redirect_uriregistado na aplicação cliente.
segredo_do_cliente Necessário para aplicativos Web, não permitido 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. É necessário para aplicativos da Web e APIs da Web (todos os clientes confidenciais), que têm a capacidade de armazenar o client_secret com segurança no lado do servidor. O client_secret deve ser codificado por URL antes de ser enviado.
recurso recomendado O URI do ID do aplicativo da API Web de destino (recurso seguro). Para localizar o URI da ID do Aplicativo, no portal do Azure, clique em Azure Ative Directory, clique em Registros de aplicativos, 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-a na solicitação de autorização para garantir que o consentimento seja recebido do usuário. Se na solicitação de autorização e na solicitação de token, os parâmetros do recurso devem corresponder.
verificador_de_código opcional 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 o PKCE RFC

Para localizar o URI da ID do Aplicativo, no portal do Azure, clique em Azure Ative Directory, clique em Registros de aplicativos, abra a página Configurações do aplicativo e clique em Propriedades.

Resposta com êxito

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 tokens de acesso em cache para o tempo de vida do token especificado na resposta OAuth 2.0. Para determinar o tempo de vida do token, use os expires_in valores ou expires_on parâmetro.

Se um recurso de API da Web retornar um código de invalid_token erro, isso pode indicar que o recurso determinou que o token expirou. Se os tempos de relógio do cliente e do recurso forem diferentes (conhecido como "distorção de tempo"), o recurso poderá considerar que o token expirou antes que o token seja limpo do cache do cliente. Se isso ocorrer, limpe o token do cache, mesmo que ele ainda esteja dentro de seu tempo de vida calculado.

Uma resposta bem-sucedida pode ser assim:

{
  "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. Esta é uma cadeia de caracteres opaca - depende do que o recurso espera receber e não se destina ao cliente para olhar. O aplicativo pode usar esse token para autenticar o recurso seguro, como uma API da Web.
tipo_de_token Indica o valor do tipo de token. O único tipo que o Azure AD suporta é Bearer. 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é o tempo de expiração. Esse valor é usado para determinar o tempo de vida dos tokens armazenados em cache.
recurso O URI do ID de aplicação da API Web (recurso seguro).
Alcance Permissões de imitação concedidas à aplicação 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 OAuth 2.0. O aplicativo pode usar esse token para adquirir tokens de acesso adicionais depois que o token de acesso atual expirar. 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 (token de identificação) 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 os valores em cache e exibi-los, mas não deve depender deles para qualquer autorização ou limites de segurança.

Para obter mais informações sobre tokens Web JSON, consulte o rascunho de especificação JWT do 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, porque o cliente chama o ponto de extremidade de emissão de token diretamente. 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.

Um exemplo de resposta de erro 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ódigo de erro que pode ser usada para classificar tipos de erros que ocorrem e pode ser usada para reagir a 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 podem ajudar no diagnóstico.
Data e hora A hora em que o erro ocorreu.
trace_id Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico.
identificador_de_correlacao Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico entre componentes.

Códigos de estado HTTP

A tabela seguinte apresenta os códigos de status HTTP que o endpoint de emissão de token retorna. Em alguns casos, o código de erro é suficiente para descrever a resposta, mas se houver erros, você precisa analisar o documento JSON que o 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 malformada. Corrija e reenvie a solicitação.
401 Falha na autenticação. Por exemplo, a solicitação está faltando 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. Repita o pedido.

Códigos de erro para erros no terminal de token

Código de Erro Descrição Ação do Cliente
pedido_inválido Erro de protocolo, como a ausência de um parâmetro obrigatório. Corrigir e reenviar a solicitação
subvençã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.
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.
tipo_de_concessão_não_suportado 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.
recurso inválido O recurso de destino é inválido porque não existe, o Azure AD não pode encontrá-lo ou não está configurado corretamente. Isso 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 Azure AD.
interação necessária A solicitação requer interação do usuário. Por exemplo, uma etapa de autenticação adicional é necessária. 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 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.

Usar o token de acesso para acessar o recurso

Agora que adquiriu com êxito um access_token, pode usar o token em solicitações para APIs da Web ao incluí-lo no cabeçalho Authorization. A especificação RFC 6750 explica como usar tokens de portador em solicitações HTTP para acessar recursos protegidos.

Pedido de amostra

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

Recursos seguros que implementam 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.

A seguir está 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
uri_de_autorização O URI (ponto de extremidade físico) do servidor de autorização. Este valor também é usado como uma chave de consulta para obter mais informações sobre o servidor a partir de um endpoint 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 https://login.microsoftonline.com ou outro nome de host suportado pelo Azure AD. Um recurso específico de um inquilino deve sempre devolver um URI de autorização específico para esse inquilino.

erro Um valor de código de erro definido na Seção 5.2 do OAuth 2.0 Authorization Framework.
descrição_do_erro Uma descrição mais detalhada do erro. Esta mensagem não pretende ser de fácil utilização.
identificador_de_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 o resource_id corresponde à base da URL da API web que está a ser acedida. Por exemplo, se https://service.contoso.com/data estiver sendo acessado, o resource_id pode ser https://service.contoso.com/. O aplicativo cliente deve rejeitar um resource_id que não comece com a URL base, a menos que haja uma maneira alternativa confiável de verificar a id.

Códigos de erro do esquema Bearer

A especificação RFC 6750 define os seguintes erros para recursos 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 pedido_inválido O pedido não está bem formulado. Por exemplo, pode estar faltando um parâmetro ou usando o mesmo parâmetro duas vezes. Corrija o erro e tente novamente a solicitação. Este tipo de erro deve ocorrer apenas durante o desenvolvimento e ser detetado nos testes iniciais.
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, ocorreu um erro inesperado. Envie uma mensagem de erro para o usuário e tente novamente após atrasos aleatórios.
403 escopo 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 "scope", utilize o valor de "scope" no pedido ao recurso.
403 acesso_insuficiente O assunto do token não tem as permissões necessárias para acessar o recurso. Solicitar que o usuário 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 após expirarem para continuar acessando recursos. Você pode atualizar o access_token enviando outra solicitação POST para o endpoint /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 o seu cliente já deu consentimento para aceder - assim, um token de atualização emitido num pedido para resource=https://graph.microsoft.com pode ser usado para solicitar um novo token de acesso para resource=https://contoso.com/api.

Os tokens de atualização 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 desejada. A sua aplicação necessita esperar e tratar corretamente os 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. Em particular, 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 interaction_required códigos de erro 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 ponto de extremidade específico do locatário (também pode usar o ponto de extremidade comum) para obter um novo token de acesso usando um token de atualização é apresentada da seguinte forma:

// 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 com êxito

Uma resposta de token bem-sucedida terá o seguinte formato:

{
  "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 suportado é portador.
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é o tempo de expiração.
recurso Identifica o recurso seguro que o token de acesso pode ser usado para acessar.
Alcance 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 que foi solicitado.
token de atualização Um novo OAuth 2.0 refresh_token que pode ser usado para solicitar novos tokens de acesso quando o desta resposta expirar.

Resposta de erro

Um exemplo de resposta de erro 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ódigo de erro que pode ser usada para classificar tipos de erros que ocorrem e pode ser usada para reagir a 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 podem ajudar no diagnóstico.
Data e hora A hora em que o erro ocorreu.
trace_id Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico.
id_de_correlação 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

Para saber mais sobre o ponto de extremidade do Azure AD v1.0 e como adicionar autenticação e autorização aos seus aplicativos Web e APIs Web, consulte Aplicativos de exemplo.