Autorizar o acesso a aplicações Web do Azure Active Directory através do fluxo de concessão de código do OAuth 2.0
Aviso
Este conteúdo destina-se ao ponto final Azure AD v1.0 mais antigo. Utilize o plataforma de identidades da Microsoft para novos projetos.
Nota
Se não disser ao servidor qual o recurso que pretende chamar, o servidor não acionará as políticas de Acesso Condicional para esse recurso. Por isso, para ter o acionador MFA, terá de incluir um recurso no URL.
O Azure Active Directory (Azure AD) utiliza o OAuth 2.0 para lhe permitir autorizar o acesso a aplicações Web e a APIs Web no seu inquilino do Azure AD. Este guia é independente de linguagem e descreve como enviar e receber mensagens HTTP sem utilizar nenhuma das nossas bibliotecas open source.
O fluxo de código de autorização OAuth 2.0 está descrito na secção 4.1 da especificação OAuth 2.0. É utilizado para efetuar autenticação e autorização na maioria dos tipos de aplicações, incluindo aplicações Web e aplicações instaladas nativamente.
Registar a aplicação com o inquilino do AD
Primeiro, registe a aplicação no inquilino do Azure Active Directory (Azure AD). Esta ação dar-lhe-á um ID de Aplicação para a aplicação e ativá-lo-á para receber tokens.
Inicie sessão no portal do Azure.
Selecione o seu inquilino Azure AD ao selecionar a sua conta no canto superior direito da página, seguido de selecionar a navegação Mudar de Diretório e, em seguida, selecionar o inquilino adequado.
- Ignore este passo se tiver apenas um inquilino Azure AD na sua conta ou se já tiver selecionado o inquilino Azure AD adequado.
Na portal do Azure, procure e selecione Azure Active Directory.
No menu esquerdo do Azure Active Directory , selecione Registos de Aplicações e, em seguida, selecione Novo registo.
Siga as instruções e crie uma nova aplicação. Não importa se é uma aplicação Web ou uma aplicação de cliente público (mobile & desktop) para este tutorial, mas se quiser exemplos específicos para aplicações Web ou aplicações cliente públicas, consulte os nossos inícios rápidos.
- Nome é o nome da aplicação e descreve a sua aplicação aos utilizadores finais.
- Em Tipos de conta suportados, selecione Contas em qualquer diretório organizacional e contas Microsoft pessoais.
- Indique 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 o cliente público (móvel & ambiente de trabalho), o Azure AD utiliza-o para devolver respostas de tokens. Introduza um valor específico na aplicação. Por exemplo,http://MyFirstAADApp.
Depois de concluir o registo, Azure AD atribuirá à sua aplicação um identificador de cliente exclusivo (o ID da Aplicação). Precisa deste valor nas secções seguintes, por isso, copie-o a partir da página da aplicação.
Para localizar a aplicação no portal do Azure, selecione Registos de aplicações e, em seguida, selecione Ver todas as aplicações.
Fluxo de autorização do OAuth 2.0
A um nível elevado, todo o fluxo de autorização de uma aplicação tem um aspeto semelhante ao seguinte:
Pedir um código de autorização
O fluxo de código de autorização começa com o cliente a direcionar o utilizador para o /authorize ponto final. Neste pedido, o cliente indica as permissões necessárias para adquirir ao utilizador. Pode obter o ponto final de autorização do OAuth 2.0 para o seu inquilino ao selecionar Registos de aplicações > Pontos finais 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 | Description |
|---|---|---|
| inquilino | obrigatório | O {tenant} valor no caminho do pedido pode ser utilizado para controlar quem pode iniciar sessão na aplicação. Os valores permitidos são identificadores de inquilino, por exemplo, 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 ou contoso.onmicrosoft.comcommon para tokens independentes de inquilinos |
| client_id | obrigatório | O ID da Aplicação atribuído à sua aplicação quando a registou com Azure AD. Pode encontrá-lo no portal do Azure. Clique em Azure Active Directory na barra lateral de serviços, clique em Registos de aplicações e escolha a aplicação. |
| response_type | obrigatório | Tem de incluir code para o fluxo de código de autorização. |
| redirect_uri | recomendado | A redirect_uri da sua aplicação, onde as respostas de autenticação podem ser enviadas e recebidas pela sua aplicação. Tem de corresponder exatamente a uma das redirect_uris que registou no portal, exceto que tem de estar codificada com URL. Para aplicações móveis nativas &, deve utilizar o valor predefinido de https://login.microsoftonline.com/common/oauth2/nativeclient. |
| response_mode | opcional | Especifica o método que deve ser utilizado para enviar o token resultante de volta para a sua aplicação. Pode ser query, fragmentou form_post.
query fornece o código como um parâmetro de cadeia de consulta no URI de redirecionamento. Se estiver a pedir um token de ID com o fluxo implícito, não pode utilizar query conforme especificado na especificação OpenID. Se estiver a pedir apenas o código, pode utilizar query, fragmentou form_post.
form_post executa um POST que contém o código para o URI de redirecionamento. A predefinição é query para um fluxo de código. |
| state | recomendado | Um valor incluído no pedido que também é devolvido 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 é utilizado para codificar informações sobre o estado do utilizador na aplicação antes do pedido de autenticação ocorrer, como a página ou vista em que se encontravam. |
| recurso | recomendado | O URI do ID da Aplicação da API Web de destino (recurso protegido). Para localizar o URI do ID da Aplicação, no portal do Azure, clique em Azure Active Directory, clique em Registos de aplicações, abra a página Definições da aplicação e, em seguida, clique em Propriedades. Também pode ser um recurso externo como https://graph.microsoft.com. Isto é necessário num dos pedidos de autorização ou token. Para garantir que menos pedidos de autenticação o colocam no pedido de autorização para garantir que o consentimento é recebido do utilizador. |
| scope | ignorado | Para aplicações de Azure AD v1, os âmbitos têm de ser configurados estaticamente no portal do Azure nas Definições das aplicações, Permissões Necessárias. |
| pedido de aviso | opcional | Indique o tipo de interação do utilizador que é necessário. Os valores válidos são: início de sessão: deve ser pedido ao utilizador para voltar a autenticar. select_account: é pedido ao utilizador para selecionar uma conta, interrompendo o início de sessão único. O utilizador pode selecionar uma conta com sessão iniciada existente, introduzir as respetivas credenciais para uma conta memorizada ou optar por utilizar completamente uma conta diferente. consentimento: o consentimento do utilizador foi concedido, mas tem de ser atualizado. O utilizador deve ser solicitado a consentir. admin_consent: Deve ser pedido a um administrador que dê consentimento em nome de todos os utilizadores na organização |
| login_hint | opcional | Pode ser utilizado para preencher previamente o campo de nome de utilizador/endereço de e-mail da página de início de sessão do utilizador, se souber antecipadamente o nome de utilizador. Muitas vezes, as aplicações utilizam este parâmetro durante a reautenticação, tendo já extraído o nome de utilizador de um início de sessão anterior com a preferred_username afirmação. |
| domain_hint | opcional | Fornece uma sugestão sobre o inquilino ou domínio que o utilizador deve utilizar para iniciar sessão. O valor do domain_hint é um domínio registado para o inquilino. Se o inquilino estiver federado num diretório no local, o AAD redireciona para o servidor de federação de inquilinos especificado. |
| code_challenge_method | recomendado | O método utilizado para codificar o code_verifier para o code_challenge parâmetro . Pode ser um de plain ou S256. Se for excluído, code_challenge assume-se que é texto simples se code_challenge estiver incluído. O Azure AAD v1.0 suporta e plainS256. Para obter mais informações, veja o RFC do PKCE. |
| code_challenge | recomendado | Utilizado para proteger concessões de código de autorização através da Chave de Prova para o Code Exchange (PKCE) a partir de um cliente nativo ou público. Necessário se code_challenge_method estiver incluído. Para obter mais informações, veja o RFC do PKCE. |
Nota
Se o utilizador fizer parte de uma organização, um administrador da organização pode consentir ou recusar em nome do utilizador ou permitir o consentimento do utilizador. É dada ao utilizador a opção de dar consentimento apenas quando o administrador o permitir.
Neste momento, é pedido ao utilizador que introduza as credenciais e o consentimento das permissões pedidas pela aplicação no portal do Azure. Assim que o utilizador autenticar e conceder consentimento, Azure AD envia uma resposta à sua aplicação no endereço no redirect_uri seu pedido com o código.
Resposta com êxito
Uma resposta bem-sucedida pode ter o seguinte aspeto:
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 | Description |
|---|---|
| admin_consent | O valor é Verdadeiro se um administrador tiver consentido um pedido de consentimento. |
| code | O código de autorização que a aplicação pediu. A aplicação pode utilizar o código de autorização para pedir um token de acesso para o recurso de destino. |
| session_state | Um valor exclusivo que identifica a sessão de utilizador atual. Este valor é um GUID, mas deve ser tratado como um valor opaco que é transmitido sem exame. |
| state | Se um parâmetro de estado estiver incluído no pedido, o mesmo valor deverá aparecer na resposta. É uma boa prática que a aplicação verifique se os valores de estado no pedido e na resposta são idênticos antes de utilizar a resposta. Isto ajuda a detetar ataques de Falsificação de Pedidos entre Sites (CSRF) contra o cliente. |
Resposta a erros
Também podem ser enviadas respostas de erro para que redirect_uri a aplicação possa processá-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 Secção 5.2 do OAuth 2.0 Authorization Framework. A tabela seguinte descreve os códigos de erro que Azure AD devolve. |
| error_description | Uma descrição mais detalhada do erro. Esta mensagem não se destina a ser amigável para o utilizador final. |
| state | O valor de estado é um valor gerado aleatoriamente não reutilizado que é enviado no pedido e devolvido na resposta para impedir ataques de falsificação de pedidos entre sites (CSRF). |
Códigos de erro para erros de ponto final de autorização
A tabela seguinte descreve os vários códigos de erro que podem ser devolvidos no error parâmetro da resposta de erro.
| Código de Erro | Description | Ação do Cliente |
|---|---|---|
| invalid_request | Erro de protocolo, como um parâmetro necessário em falta. | Corrija e volte a submeter o pedido. Trata-se de um erro de desenvolvimento e, normalmente, é detetado durante o teste inicial. |
| unauthorized_client | A aplicação cliente não está autorizada a pedir um código de autorização. | Normalmente, isto ocorre quando a aplicação cliente não está registada no Azure AD ou não é adicionada ao inquilino Azure AD do utilizador. A aplicação pode pedir ao utilizador instruções para instalar a aplicação e adicioná-la ao Azure AD. |
| access_denied | O proprietário do recurso negou o consentimento | A aplicação cliente pode notificar o utilizador de que não pode continuar, a menos que o utilizador consenta. |
| unsupported_response_type | O servidor de autorização não suporta o tipo de resposta no pedido. | Corrija e volte a submeter o pedido. Trata-se de um erro de desenvolvimento e, normalmente, é detetado durante o teste inicial. |
| server_error | O servidor encontrou um erro inesperado. | Repita o pedido. Estes erros podem resultar de condições temporárias. A aplicação cliente pode explicar ao utilizador que a resposta está atrasada devido a um erro temporário. |
| temporarily_unavailable | O servidor está temporariamente demasiado ocupado para processar o pedido. | Repita o pedido. A aplicação cliente pode explicar ao utilizador que a resposta está atrasada devido a uma condição temporária. |
| invalid_resource | O recurso de destino é inválido porque não existe, Azure AD não consegue encontrá-lo ou não está configurado corretamente. | Isto indica que o recurso, se existir, não foi configurado no inquilino. A aplicação pode pedir ao utilizador instruções para instalar a aplicação e adicioná-la ao Azure AD. |
Utilizar o código de autorização para pedir um token de acesso
Agora que adquiriu um código de autorização e lhe foi concedida permissão pelo utilizador, pode resgatar o código de um token de acesso para o recurso pretendido ao enviar um pedido POST para o /token ponto final:
// 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 | Description |
|---|---|---|
| inquilino | obrigatório | O {tenant} valor no caminho do pedido pode ser utilizado para controlar quem pode iniciar sessão na aplicação. Os valores permitidos são identificadores de inquilino, por exemplo, 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 ou contoso.onmicrosoft.comcommon para tokens independentes de inquilinos |
| client_id | obrigatório | O ID da Aplicação atribuído à sua aplicação quando a registou com Azure AD. Pode encontrá-lo no portal do Azure. O ID da Aplicação é apresentado nas definições do registo da aplicação. |
| grant_type | obrigatório | Tem de ser authorization_code para o fluxo de código de autorização. |
| code | obrigatório | O authorization_code que adquiriu na secção anterior |
| redirect_uri | obrigatório | Um redirect_uriregistado na aplicação cliente. |
| client_secret | necessário para aplicações Web, não permitido para clientes públicos | O segredo da aplicação que criou no portal do Azure para a sua aplicação em Chaves. Não pode ser utilizada numa aplicação nativa (cliente público), porque não é possível armazenar client_secrets em dispositivos de forma fiável. É necessário para aplicações 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 com URL antes de ser enviado. |
| recurso | recomendado | O URI do ID da Aplicação da API Web de destino (recurso protegido). Para localizar o URI do ID da Aplicação, no portal do Azure, clique em Azure Active Directory, clique em Registos de aplicações, abra a página Definições da aplicação e, em seguida, clique em Propriedades. Também pode ser um recurso externo como https://graph.microsoft.com. Isto é necessário num dos pedidos de autorização ou token. Para garantir que menos pedidos de autenticação o colocam no pedido de autorização para garantir que o consentimento é recebido do utilizador. Se no pedido de autorização e no pedido de token, os parâmetros do recurso têm de corresponder. |
| code_verifier | opcional | O mesmo code_verifier que foi utilizado para obter o authorization_code. Necessário se o PKCE tiver sido utilizado no pedido de concessão de código de autorização. Para obter mais informações, veja o RFC do PKCE |
Para localizar o URI do ID da Aplicação, no portal do Azure, clique em Azure Active Directory, clique em Registos de aplicações, abra a página Definições da aplicação e, em seguida, clique em Propriedades.
Resposta com êxito
Azure AD devolve um token de acesso após uma resposta bem-sucedida. Para minimizar as chamadas de rede da aplicação cliente e a respetiva latência associada, a aplicação cliente deve colocar em cache os tokens de acesso para a duração do token especificada na resposta OAuth 2.0. Para determinar a duração do token, utilize os expires_in valores de parâmetro ou expires_on .
Se um recurso da API Web devolver um invalid_token código de erro, tal poderá indicar que o recurso determinou que o token expirou. Se as horas do relógio do cliente e do recurso forem diferentes (conhecidas como "distorção de tempo"), o recurso poderá considerar que o token expirou antes de o token ser limpo da cache do cliente. Se isto ocorrer, limpe o token da cache, mesmo que ainda esteja dentro da duração calculada.
Uma resposta bem-sucedida pode ter o seguinte aspeto:
{
"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 | Description |
|---|---|
| access_token | O token de acesso pedido. Esta é uma cadeia opaca - depende do que o recurso espera receber e não se destina ao cliente a analisar. A aplicação pode utilizar este token para autenticar no recurso protegido, como uma API Web. |
| token_type | Indica o valor do tipo de token. O único tipo que Azure AD suporta é Portador. Para obter mais informações sobre tokens de portador, veja OAuth2.0 Authorization Framework: Bearer Token Usage (RFC 6750) |
| expires_in | Durante quanto tempo o token de acesso é válido (em segundos). |
| expires_on | 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é à hora de expiração. Este valor é utilizado para determinar a duração dos tokens em cache. |
| recurso | O URI do ID da Aplicação da API Web (recurso protegido). |
| scope | Permissões de representação concedidas à aplicação cliente. A permissão predefinida é user_impersonation. O proprietário do recurso protegido pode registar valores adicionais no Azure AD. |
| refresh_token | Um token de atualização OAuth 2.0. A aplicação pode utilizar este token para adquirir tokens de acesso adicionais após o token de acesso atual expirar. Os tokens de atualização são de longa duração e podem ser utilizados 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. A aplicação pode descodificar os segmentos deste token como base64Url para pedir informações sobre o utilizador que iniciou sessão. A aplicação pode colocar os valores em cache e apresentá-los, mas não deve depender deles para quaisquer limites de autorização ou segurança. |
Para obter mais informações sobre os tokens Web JSON, veja a especificação de rascunho do JWT IETF. Para saber mais sobre id_tokenso , veja o fluxo do OpenID Connect v1.0.
Resposta a erros
Os erros do ponto final de emissão de tokens são códigos de erro HTTP, porque o cliente chama o ponto final de emissão de tokens diretamente. Além do código de estado HTTP, o ponto final de emissão de tokens de Azure AD também devolve um documento JSON com objetos que descrevem o erro.
Uma resposta de erro de exemplo pode ter o seguinte aspeto:
{
"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 código de erro que pode ser utilizada para classificar tipos de erros que ocorrem e pode ser utilizada para reagir a erros. |
| error_description | Uma mensagem de erro específica que pode ajudar um programador a identificar a causa raiz de um erro de autenticação. |
| error_codes | Uma lista de códigos de erro específicos de STS que podem ajudar nos diagnósticos. |
| carimbo de data/hora | A hora em que ocorreu o erro. |
| trace_id | Um identificador exclusivo para o pedido que pode ajudar nos diagnósticos. |
| correlation_id | Um identificador exclusivo para o pedido que pode ajudar nos diagnósticos entre componentes. |
Códigos de estado HTTP
A tabela seguinte lista os códigos de estado HTTP que o ponto final de emissão de tokens devolve. Em alguns casos, o código de erro é suficiente para descrever a resposta, mas se existirem erros, tem de analisar o documento JSON que o acompanha e examinar o respetivo código de erro.
| Código HTTP | Descrição |
|---|---|
| 400 | Código HTTP predefinido. Utilizado na maioria dos casos e normalmente deve-se a um pedido com formato incorreto. Corrija e volte a submeter o pedido. |
| 401 | Falha na autenticação. Por exemplo, falta o parâmetro client_secret do pedido. |
| 403 | Falha na autorização. Por exemplo, o utilizador não tem permissão para aceder ao recurso. |
| 500 | Ocorreu um erro interno no serviço. Repita o pedido. |
Códigos de erro para erros de ponto final de token
| Código de Erro | Description | Ação do Cliente |
|---|---|---|
| invalid_request | Erro de protocolo, como um parâmetro necessário em falta. | Corrigir e submeter novamente o pedido |
| invalid_grant | O código de autorização é inválido ou expirou. | Experimentar um novo pedido para o /authorize ponto final |
| unauthorized_client | O cliente autenticado não está autorizado a utilizar este tipo de concessão de autorização. | Normalmente, isto ocorre quando a aplicação cliente não está registada no Azure AD ou não é adicionada ao inquilino Azure AD do utilizador. A aplicação pode pedir ao utilizador instruções para instalar a aplicação e adicioná-la 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 da aplicação 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 no pedido. Este tipo de erro deve ocorrer apenas durante o desenvolvimento e ser detetado durante o teste inicial. |
| invalid_resource | O recurso de destino é inválido porque não existe, Azure AD não consegue encontrá-lo ou não está configurado corretamente. | Isto indica que o recurso, se existir, não foi configurado no inquilino. A aplicação pode pedir ao utilizador instruções para instalar a aplicação e adicioná-la ao Azure AD. |
| interaction_required | O pedido requer a interação do utilizador. Por exemplo, é necessário um passo de autenticação adicional. | Em vez de um pedido não interativo, repita com um pedido de autorização interativo para o mesmo recurso. |
| temporarily_unavailable | O servidor está temporariamente demasiado ocupado para processar o pedido. | Repita o pedido. A aplicação cliente pode explicar ao utilizador que a resposta está atrasada devido a uma condição temporária. |
Utilizar o token de acesso para aceder ao recurso
Agora que adquiriu com êxito um access_token, pode utilizar o token em pedidos para APIs Web, incluindo-o no Authorization cabeçalho. A especificação RFC 6750 explica como utilizar tokens de portador em pedidos HTTP para aceder a recursos protegidos.
Pedido 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 a Erros
Recursos protegidos que implementam códigos de estado HTTP de RFC 6750. Se o pedido não incluir credenciais de autenticação ou estiver a perder o token, a resposta inclui um WWW-Authenticate cabeçalho. Quando um pedido falha, o servidor de recursos responde com o código de estado HTTP e um código de erro.
Segue-se um exemplo de uma resposta sem êxito quando o pedido de cliente não inclui o token do 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 | Description |
|---|---|
| authorization_uri | O URI (ponto final físico) do servidor de autorização. Este valor também é utilizado como uma chave de pesquisa para obter mais informações sobre o servidor a partir de um ponto final de deteção. O cliente tem de validar que o servidor de autorização é fidedigno. Quando o recurso está protegido por Azure AD, é suficiente para verificar se o URL começa com |
| erro | Um valor de código de erro definido na Secção 5.2 do OAuth 2.0 Authorization Framework. |
| error_description | Uma descrição mais detalhada do erro. Esta mensagem não se destina a ser amigável para o utilizador final. |
| resource_id | Devolve o identificador exclusivo do recurso. A aplicação cliente pode utilizar este identificador como o valor do resource parâmetro quando pede um token para o recurso. É importante que a aplicação cliente verifique este valor, caso contrário, um serviço malicioso poderá ser capaz de induzir um ataque de elevação de privilégios A estratégia recomendada para impedir um ataque é verificar se corresponde |
Códigos de erro do esquema de portador
A especificação RFC 6750 define os seguintes erros para os recursos que utilizam o cabeçalho WWW-Authenticate e o esquema portador na resposta.
| Código de Estado HTTP | Código de Erro | Description | Ação do Cliente |
|---|---|---|---|
| 400 | invalid_request | O pedido não está bem formado. Por exemplo, pode estar a perder um parâmetro ou a utilizar o mesmo parâmetro duas vezes. | Corrija o erro e repita o pedido. Este tipo de erro deve ocorrer apenas durante o desenvolvimento e ser detetado nos testes iniciais. |
| 401 | invalid_token | O token de acesso está em falta, é inválido ou é revogado. O valor do parâmetro error_description fornece detalhes adicionais. | Peça um novo token a partir do servidor de autorização. Se o novo token falhar, ocorreu um erro inesperado. Envie uma mensagem de erro ao utilizador e repita após atrasos aleatórios. |
| 403 | insufficient_scope | O token de acesso não contém as permissões de representação necessárias para aceder ao recurso. | Envie um novo pedido de autorização para o ponto final de autorização. Se a resposta contiver o parâmetro de âmbito, utilize o valor de âmbito no pedido para o recurso. |
| 403 | insufficient_access | O assunto do token não tem as permissões necessárias para aceder ao recurso. | Peça ao utilizador para utilizar uma conta diferente ou para pedir permissões para o recurso especificado. |
Atualizar os tokens de acesso
Os Tokens de Acesso são de curta duração e têm de ser atualizados depois de expirarem para continuarem a aceder aos recursos. Pode atualizar o access_token ao submeter outro POST pedido para o /token ponto final, mas desta vez fornecendo o refresh_token em vez do code. Os tokens de atualização são válidos para todos os recursos aos quais o cliente já deu consentimento para aceder. Assim, um token de atualização emitido num pedido para resource=https://graph.microsoft.com pode ser utilizado para pedir um novo token de acesso para resource=https://contoso.com/api.
Os tokens de atualização não têm durações especificadas. Normalmente, as durações dos tokens de atualização são relativamente longas. 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 pretendida. A sua aplicação tem de esperar e lidar corretamente com erros devolvidos pelo ponto final de emissão de tokens.
Quando receber uma resposta com um erro de token de atualização, elimine o token de atualização atual e peça um novo código de autorização ou token de acesso. Em particular, ao utilizar um token de atualização no fluxo de Concessão de Código de Autorização, se receber uma resposta com os interaction_required códigos de erro ou invalid_grant , elimine o token de atualização e peça um novo código de autorização.
Um pedido de exemplo para o ponto final específico do inquilino (também pode utilizar o ponto final comum ) para obter um novo token de acesso com um token de atualização tem o seguinte aspeto:
// 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 com êxito terá o seguinte aspeto:
{
"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 | Description |
|---|---|
| token_type | O tipo de token. O único valor suportado é o portador. |
| expires_in | A duração restante do token em segundos. Um valor típico é 3600 (uma hora). |
| expires_on | A data e hora em que o token expira. A data é representada como o número de segundos de 1970-01-01T0:0:0Z UTC até à hora de expiração. |
| recurso | Identifica o recurso seguro ao qual o token de acesso pode ser utilizado para aceder. |
| scope | Permissões de representação concedidas à aplicação cliente nativa. A permissão predefinida é user_impersonation. O proprietário do recurso de destino pode registar valores alternativos no Azure AD. |
| access_token | O novo token de acesso que foi pedido. |
| refresh_token | Um novo OAuth 2.0 refresh_token que pode ser utilizado para pedir novos tokens de acesso quando o existente nesta resposta expirar. |
Resposta a erros
Uma resposta de erro de exemplo pode ter o seguinte aspeto:
{
"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 código de erro que pode ser utilizada para classificar tipos de erros que ocorrem e pode ser utilizada para reagir a erros. |
| error_description | Uma mensagem de erro específica que pode ajudar um programador a identificar a causa raiz de um erro de autenticação. |
| error_codes | Uma lista de códigos de erro específicos de STS que podem ajudar nos diagnósticos. |
| carimbo de data/hora | A hora em que ocorreu o erro. |
| trace_id | Um identificador exclusivo para o pedido que pode ajudar nos diagnósticos. |
| correlation_id | Um identificador exclusivo para o pedido que pode ajudar nos diagnósticos entre componentes. |
Para obter uma descrição dos códigos de erro e da ação de cliente recomendada, veja Códigos de erro para erros de pontos finais de tokens.
Passos seguintes
Para saber mais sobre o ponto final Azure AD v1.0 e como adicionar autenticação e autorização às suas aplicações Web e APIs Web, veja aplicações de exemplo.