Como autorizar o console de teste do portal do desenvolvedor configurando a autorização de usuário do OAuth 2.0

Artigo
04/01/2024

Muitas APIs dão suporte ao OAuth 2.0 para proteger a API e garantir que apenas usuários válidos tenham acesso e possam acessar apenas os recursos para os quais eles estão qualificados. Para usar o console interativo do desenvolvedor do Gerenciamento de API do Azure com essas APIs, o serviço permite que você configure um provedor externo para a autorização de usuário do OAuth 2.0.

A configuração da autorização de usuário do OAuth 2.0 no console de teste do portal do desenvolvedor fornece aos desenvolvedores uma forma conveniente de adquirir um token de acesso OAuth 2.0. No console de teste, o token é transmitido ao back-end com a chamada à API. A validação do token precisa ser configurada separadamente, usando uma política de validação de JWT ou no serviço de back-end.

Pré-requisitos

Este artigo mostra como configurar sua instância de serviço do Gerenciamento de API para usar a autorização do OAuth 2.0 no console de teste do portal do desenvolvedor, mas não mostra como configurar um provedor OAuth 2.0.

Se você ainda não criou uma instância de serviço do Gerenciamento de API, confira Criar uma instância de serviço do Gerenciamento de API.

Visão geral do cenário

Configurar a autorização de usuário do OAuth 2.0 no Gerenciamento de API só permite que o console de teste do portal do desenvolvedor (e o console de teste no portal do Azure), como cliente, adquira um token do servidor de autorização. A configuração de cada provedor OAuth 2.0 é diferente, embora as etapas sejam semelhantes e as informações necessárias usadas ao configurar o OAuth 2.0 na sua instância de serviço de Gerenciamento de API sejam as mesmas. Esse artigo mostra um exemplo usando o Microsoft Entra ID como um provedor OAuth 2.0.

Estas são as etapas de configuração de alto nível:

Registrar um aplicativo (aplicativo de back-end) no Microsoft Entra ID para representar a API.
Registrar outro aplicativo (aplicativo cliente) no Microsoft Entra ID para representar um aplicativo cliente que precisa chamar a API. Nesse caso, o console de teste do portal do desenvolvedor.

Conceda permissões no Microsoft Entra ID para permitir que o aplicativo cliente chame o aplicativo de back-end.
Configure o console de teste no portal do desenvolvedor para chamar uma API usando a autorização de usuário do OAuth 2.0.
Configure uma API para usar a autorização de usuário do OAuth 2.0.
Adicione política para pré-autorizar o token OAuth 2.0 para todas as solicitações de entrada. Você pode usar a política validate-jwt para qualquer provedor OAuth 2.0.

Essa configuração dá suporte ao seguinte fluxo OAuth:

Gráfico de visão geral para conceitualizar visualmente o fluxo a seguir.

O portal do desenvolvedor solicita um token do Microsoft Entra ID usando as credenciais do aplicativo cliente.
Após a validação bem-sucedida, o Microsoft Entra ID emite o token de acesso/atualização.
Um desenvolvedor (usuário do portal do desenvolvedor) faz uma chamada à API com o cabeçalho de autorização.
O token é validado usando a política validate-jwt no Gerenciamento de API pelo Azure Microsoft Entra ID.
Com base no resultado da validação, o desenvolvedor receberá a resposta no portal do desenvolvedor.

Tipos de concessão da autorização

O Gerenciamento de API do Azure dá suporte aos tipos de concessão OAuth 2.0 (fluxos) a seguir. Um tipo de concessão refere-se a uma forma de um aplicativo cliente (neste contexto, o console de teste no portal do desenvolvedor) obter um token de acesso à sua API de back-end. Você pode configurar um ou mais tipos de concessão, dependendo dos cenários e do seu provedor OAuth 2.0.

Veja a seguir um resumo de alto nível. Para obter mais informações sobre os tipos de concessão, confira Estrutura de Autorização do OAuth 2.0 e Tipos de concessão do OAuth.

Tipo de concessão	Descrição	Cenários
Código de Autorização	Troca o código de autorização para o token	Aplicativos do lado do servidor, como aplicativos Web
Código de autorização + PKCE	Aprimoramento do fluxo de código de autorização que cria um desafio de código que é enviado com a solicitação de autorização	Clientes públicos e de dispositivos móveis que não podem proteger um segredo ou um token
Implícito (preterido)	Retorna o token de acesso imediatamente sem uma etapa extra de troca de código de autorização	Clientes que não podem proteger um segredo nem um token, como aplicativos móveis e aplicativos de página única Isso geralmente não é recomendado devido a riscos inerentes de retorno do token de acesso no redirecionamento HTTP sem a confirmação de que ele foi recebido pelo cliente
Senha de proprietário do recurso	Solicita as credenciais de usuário (nome de usuário e senha), normalmente por meio de um formulário interativo	Para uso com aplicativos altamente confiáveis Deve ser usado somente quando outros fluxos mais seguros não puderem ser usados
Credenciais do cliente	Autentica e autoriza um aplicativo em vez de um usuário	Aplicativos de comunicação entre computadores que não exigem permissões de um usuário específico para acessar dados, como CLIs, daemons ou serviços em execução no back-end

Considerações sobre segurança

Considere como o tipo de concessão gera um token, o escopo do token e como o token pode ser exposto. Um token comprometido pode ser usado por um ator mal-intencionado para acessar recursos adicionais no escopo do token.

Ao configurar a autorização de usuário do OAuth 2.0 no console de teste do portal do desenvolvedor:

Limite o escopo do token ao mínimo necessário para que os desenvolvedores testem as APIs. Limite o escopo ao console de teste ou às APIs afetadas. As etapas necessárias para configurar o escopo do token dependem do provedor OAuth 2.0.

Dependendo dos cenários, você pode configurar escopos de token mais ou menos restritivos para outros aplicativos cliente que você criar para acessar as APIs de back-end.
Tenha cuidado extra se você habilitar o fluxo de Credenciais do Cliente. O console de teste no portal do desenvolvedor, durante o trabalho com o fluxo de Credenciais do Cliente, não solicita credenciais. Um token de acesso pode ser exposto inadvertidamente a desenvolvedores ou usuários anônimos do console do desenvolvedor.

Manter o controle das informações principais

Ao longo deste tutorial, você será solicitado a gravar informações de chave para fazer referência posteriormente:

ID do aplicativo de back-end (cliente): o GUID do aplicativo que representa a API de back-end
Escopos de aplicativo de back-end: um ou mais escopos que você pode criar para acessar a API. O formato de escopo é api://<Backend Application (client) ID>/<Scope Name> (por exemplo, api://1764e900-1827-4a0b-9182-b2c1841864c2/Read)
ID do aplicativo de back-end (cliente): o GUID do aplicativo que representa o portal do desenvolvedor
Valor Secreto do Aplicativo Cliente: o GUID que serve como o segredo para interação com o aplicativo cliente no Microsoft Entra ID

Registrar aplicativos no servidor OAuth

Você precisará registrar dois aplicativos em seu provedor OAuth 2.0: um que representa a API de back-end a ser protegida e outro que representa o aplicativo cliente que chama a API – neste caso, o console de teste do portal do desenvolvedor.

Veja a seguir as etapas de exemplo usando o Microsoft Entra ID como o provedor OAuth 2.0. Para obter detalhes sobre o registro do aplicativo, consulte Início Rápido: Configurar um aplicativo para expor uma API Web.

Registrar um aplicativo no Microsoft Entra ID para representar a API

No portal do Azure, pesquise e selecione Registros de aplicativo.
Selecione Novo registro.
Quando a página Registrar um aplicativo for exibida, insira as informações de registro do aplicativo:
- Na seção Nome, insira um nome de aplicativo relevante que será exibido aos usuários do aplicativo, como aplicativo de back-end.
- Na seção Tipos de conta com suporte, selecione uma opção que se adapte ao seu cenário.
Deixe a seção URI de redirecionamento vazia. Posteriormente, você adicionará um URI de redirecionamento gerado na configuração do OAuth 2.0 no Gerenciamento de API.
Selecione Registrar para criar o aplicativo.
Na página Visão geral do aplicativo, localize o valor de ID do aplicativo (cliente) e registre-o para uso posterior.
Na seção Gerenciar do menu lateral, selecione Expor uma API e defina o URI da ID do Aplicativo com o valor padrão. Grave esse valor para usar mais tarde.
Selecione o botão Adicionar um escopo para exibir a página Adicionar um escopo:
1. Insira um Nome de escopo para um escopo compatível com a API (por exemplo, Files.Read).
2. Em Quem pode consentir?, faça uma seleção para seu cenário, como Administradores e usuários. Selecione Somente administradores para cenários com privilégios mais elevados.
3. Insira Nome de exibição do consentimento do administrador e Descrição do consentimento do administrador.
4. Verifique se o estado de escopo Habilitado está selecionado.
Selecione o botão Adicionar escopo para criar o escopo.
Repita as duas etapas anteriores para adicionar todos os escopos com suporte da API.
Após a criação dos escopos, anote quais são eles para usar em uma etapa posterior.

Registrar outro aplicativo no Microsoft Entra ID para representar um aplicativo cliente

Registre todos os aplicativos cliente que chamam a API como aplicativos no Microsoft Entra ID.

No portal do Azure, pesquise e selecione Registros de aplicativo.
Selecione Novo registro.
Quando a página Registrar um aplicativo for exibida, insira as informações de registro do aplicativo:
- Na seção Nome, insira um nome de aplicativo relevante que será exibido aos usuários do aplicativo, como aplicativo cliente.
- Na seção Tipos de conta com suporte, selecione uma opção que se adapte ao seu cenário.
Na seção URI de Redirecionamento, selecione Web e deixe o campo URL vazio por enquanto.
Selecione Registrar para criar o aplicativo.
Na página Visão geral do aplicativo, localize o valor de ID do aplicativo (cliente) e registre-o para uso posterior.
Criar um segredo do cliente para esse aplicativo, para usar em uma etapa posterior.
1. Na seção Gerenciar do menu lateral, selecione Certificados e segredos.
2. Em Segredos do cliente, selecione + Novo segredo do cliente.
3. Em Adicionar um segredo do cliente, forneça uma Descrição e escolha quando a chave deve expirar.
4. Selecione Adicionar.

Ao criar o segredo, anote o valor da chave para usar em uma etapa posterior. Não é possível acessar o segredo novamente no portal.

Conceder permissões no Microsoft Entra ID

Agora que você já registrou dois aplicativos para representar a API e o console de teste, conceda permissões para que o aplicativo cliente chame o aplicativo de back-end.

No portal do Azure, pesquise e selecione Registros de aplicativo.
Escolha seu aplicativo cliente. No menu lateral, selecione Permissões da API.
Selecione + Adicionar uma permissão.
Em Selecionar uma API, selecione Minhas APIse localize e selecione seu aplicativo de back-end.
Selecione Permissões delegadas e selecione as permissões apropriadas para o aplicativo de back-end.
Selecione Adicionar Permissões.

Como opção:

Acesse a página de permissões da API do aplicativo cliente.
Selecione Fornecer o consentimento do administrador para <seu-nome-de-locatário> para conceder consentimento em nome de todos os usuários neste diretório.

Configurar um servidor de autorização do OAuth 2.0 no Gerenciamento de API

No portal do Azure, navegue até a instância do Gerenciamento de API.
Em Portal do desenvolvedor no menu lateral, selecione OAuth 2.0 + OpenID Connect.
Na guia OAuth 2.0, selecione + Adicionar.
Insira um nome e uma descrição opcional nos campos Nome e Descrição.

Observação

Esses campos identificam o servidor de autorização OAuth 2.0 no serviço Gerenciamento de API atual. Os valores deles não são provenientes do servidor OAuth 2.0.
Insira a URL da página de registro do cliente, por exemplo, https://contoso.com/login. Esta página é o local em que os usuários podem criar e gerenciar contas, caso o provedor OAuth 2.0 dê suporte ao gerenciamento de contas do usuário. A página varia dependendo do provedor OAuth 2.0 usado.

Se seu provedor OAuth 2.0 não tiver o gerenciamento de usuário das contas configurado, insira uma URL de espaço reservado, como a de sua empresa ou como http://localhost.
A seção seguinte da forma contém as configurações dos Tipos de concessão de autorização, da URL do ponto de extremidade de autorização e do Método de solicitação de autorização.
- Selecione um ou mais tipos de concessão de autorização desejados. Para este exemplo, selecione Código de autorização (o padrão). Saiba mais
- Digite a URL do ponto de extremidade de autorização. É possível obter a URL do ponto de extremidade na página Pontos de extremidade de um dos registros do aplicativo. Para um aplicativo de locatário único no Microsoft Entra ID, essa URL será semelhante a uma das seguintes URLs, em que {aad-tenant} será substituído pela ID do seu locatário do Microsoft Entra.
  
  É recomendável usar o ponto de extremidade v2; no entanto, o Gerenciamento de API dá suporte a pontos de extremidade v1 e v2.
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/authorize (v2)
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/authorize (v1)
- O método de solicitação de autorização especifica como a solicitação de autorização é enviada para o servidor OAuth 2.0. Selecione POST.
Especifique a URL do ponto de extremidade do token, os Métodos de autenticação do cliente, o Método de envio do token de acesso e o Escopo padrão.
- Digite a URL do ponto de extremidade do token. Para um único aplicativo de locatário no Microsoft Entra ID, ela será semelhante a uma das URLs a seguir, em que {aad-tenant} será substituído pela ID do seu locatário do Microsoft Entra. Use a mesma versão do ponto de extremidade (v2 ou v1) que você escolheu anteriormente.
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/token (v2)
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/token (v1)
- Ao usar pontos de extremidade v1, adicione um parâmetro de corpo:
  * Nome: recurso.
  * Valor: a ID do aplicativo (cliente) de back-end.
- Se você usa o ponto de extremidade v2:
  * Insira o escopo do aplicativo de back-end criado no campo Escopo padrão.
  * Defina o valor da propriedade accessTokenAcceptedVersion como 2 no manifesto do aplicativo para os registros do aplicativo de back-end e do aplicativo cliente.
- Aceite as configurações padrão para Métodos de autenticação de cliente e Método de envio de token de acesso.
Em Credenciais do cliente, insira a ID do cliente e o Segredo do cliente, que são obtidos durante o processo de criação e de configuração do aplicativo cliente.
Após a especificação de ID do cliente e Segredo do cliente, o URI de redirecionamento do código de autorização é gerado. Ele é usado para configurar a URL de redirecionamento na configuração do servidor OAuth 2.0.

No portal do desenvolvedor, o sufixo de URI tem o formato:
- /signin-oauth/code/callback/{authServerName} para fluxo de concessão do código de autorização
- /signin-oauth/implicit/callback para fluxo de concessão implícita
Copie o URI de Redirecionamento apropriado na página Autenticação do registro do aplicativo cliente. No registro do aplicativo, selecione Autenticação>+ Adicionar uma plataforma>Web e insira o URI de Redirecionamento.
Se os Tipos de concessão da autorização são definidos como Senha do proprietário do recurso, a seção Credenciais de senha do proprietário de recurso é usada para especificar estas credenciais; não sendo o caso, você pode deixá-la em branco.
Selecione Criar para salvar a configuração do servidor de autorização do OAuth 2.0 do Gerenciamento de API.
Republicar o portal do desenvolvedor.

Importante

Ao fazer alterações relacionadas ao OAuth 2.0, não deixe de publicar novamente o portal do desenvolvedor após cada modificação como alterações relevantes (por exemplo, alteração de escopo) caso contrário, não será possível propagar para o portal e, posteriormente, ser usado para experimentar as APIs.

Configurar uma API para usar a autorização do usuário do OAuth 2.0

Depois de salvar a configuração do servidor OAuth 2.0, configure uma API ou APIs para usá-la.

Importante

Definir as configurações de autorização de usuário do OAuth 2.0 para uma API permite que Gerenciamento de API adquiram um token do servidor de autorização ao usar o console de teste no portal do Azure ou do desenvolvedor. As configurações do servidor de autorização também são adicionadas à definição e à documentação da API.
Para autorização do OAuth 2.0 no runtime, o aplicativo cliente deve adquirir e apresentar o token e você precisa configurar a validação de token em Gerenciamento de API ou na API de back-end. Para obter um exemplo, consulte Proteger uma API no Gerenciamento de API do Azure usando a autorização do OAuth 2.0 com o Microsoft Entra ID.

Selecione APIs no menu Gerenciamento de API à esquerda.
Escolha o nome da API desejado e selecione a guia Configurações. Role a página até a seção Segurança e escolha OAuth 2.0.
Selecione o Servidor de autorização desejado na lista suspensa e escolha Salvar.

Portal do desenvolvedor – Testar a autorização do usuário do OAuth 2.0

Depois de configurar seu servidor de autorização OAuth 2.0 e configurar a API para usar esse servidor, teste-o acessando o portal do desenvolvedor e chamando a API.

Escolha Portal do desenvolvedor no menu superior da página Visão geral da instância do Gerenciamento de API do Azure.
Navegue até qualquer operação na API no portal do desenvolvedor.
Selecione Experimentar para acessar o console do desenvolvedor.
Note que há um novo item na seção Autorização. Ele corresponde ao servidor de autorização que você acaba de adicionar.
Selecione Código de autorização na lista suspensa de autorização.
Uma vez solicitado, entre no locatário do Microsoft Entra.
- O logon poderá não ser solicitado caso você já esteja conectado com a conta.
Após o logon com êxito, será adicionado um cabeçalho de Authorization à solicitação com um token de acesso do Microsoft Entra ID. Este é um token de exemplo abreviado (codificado em Base64):
```
Authorization: Bearer eyJ0eXAiOi[...]3pkCfvEOyA
```
Configure os valores desejados para os parâmetros restantes e selecione Enviar para chamar a API.

Configurar uma política de validação de JWT para pré-autorizar solicitações

Na configuração até o momento, o Gerenciamento de API não valida o token de acesso. Ele apenas transmite o token no cabeçalho de autorização para a API de back-end.

Para pré-autorizar solicitações, configure uma política validate-jwt a fim de validar os tokens de acesso de cada solicitação recebida. Se uma solicitação não tiver um token válido, o Gerenciamento de API a bloqueará.

A política de exemplo a seguir, quando adicionada à seção de política <inbound>, verifica o valor da declaração de audiência em um token de acesso obtido do Microsoft Entra ID apresentado no cabeçalho de autorização. Se ele não for válido, ela retornará uma mensagem de erro. Configure essa política em um escopo de política apropriado para seu cenário.

No URL do openid-config, o aad-tenant é a ID do locatário no Microsoft Entra ID. Encontre esse valor no portal do Azure, por exemplo, na página Visão geral do recurso do Microsoft Entra. O exemplo mostrado pressupõe um aplicativo do Microsoft Entra de locatário único e um ponto de extremidade de configuração v2.
O valor do claim é a ID do cliente do aplicativo de back-end registrado no Microsoft Entra ID.

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/{aad-tenant}/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>{audience-value - (ex:api://guid)}</audience>
    </audiences>
    <issuers>
        <issuer>{issuer-value - (ex: https://sts.windows.net/{tenant id}/)}</issuer>
    </issuers>
    <required-claims>
        <claim name="aud">
            <value>{backend-app-client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

Observação

A URL openid-config acima corresponde ao ponto de extremidade v2. No ponto de extremidade openid-config v1, use https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration.

Para obter informações sobre como configurar as políticas, confira Definir ou editar políticas. Consulte a referência validate-jwt para obter mais personalização em validações JWT. Para validar um JWT fornecido pelo serviço Microsoft Entra, o Gerenciamento de API também fornece a política validate-azure-ad-token.

Para saber como usar o OAuth 2.0 e o Gerenciamento de API, consulte Proteger um back-end da API Web no Gerenciamento de API do Azure usando a autorização do OAuth 2.0 com o Microsoft Entra ID.
Saiba mais sobre a Plataforma de identidade da Microsoft e o fluxo de código de autorização do OAuth 2.0