Como autorizar a consola de testes do portal do programador ao configurar a autorização de utilizador OAuth 2.0

Artigo
04/13/2024

Muitas APIs suportam OAuth 2.0 para proteger a API e garantir que apenas usuários válidos tenham acesso e que eles só possam acessar recursos aos quais têm direito. Para usar o console de desenvolvedor interativo do Gerenciamento de API do Azure com essas APIs, o serviço permite configurar um provedor externo para autorização de usuário do OAuth 2.0.

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

Pré-requisitos

Este artigo mostra como configurar sua instância de serviço de Gerenciamento de API para usar a autorização 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 de Gerenciamento de API, consulte Criar uma instância de serviço de Gerenciamento de API.

Descriçã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 um cliente adquira um token do servidor de autorização. A configuração é diferente para cada fornecedor de OAuth 2.0, embora os passos sejam semelhantes e as informações necessárias utilizadas para configurar o OAuth 2.0 na sua instância de serviço da Gestão de API sejam as mesmas. Este artigo mostra um exemplo usando o Microsoft Entra ID como um provedor OAuth 2.0.

Seguem-se os passos de configuração de alto nível:

Registe uma aplicação (aplicação de back-end) no Microsoft Entra ID para representar a API.
Registre outro aplicativo (client-app) no Microsoft Entra ID para representar um aplicativo cliente que precisa chamar a API - neste caso, o console de teste do portal do desenvolvedor.

No Microsoft Entra ID, conceda permissões para permitir que a aplicação cliente chame a aplicação de back-end.
Configure a consola de testes no portal do programador para chamar uma API com a autorização de utilizador OAuth 2.0.
Configure uma API para utilizar a autorização de utilizador OAuth 2.0.
Adicione uma política para pré-autorizar o token OAuth 2.0 para todos os pedidos recebidos. Você pode usar a validate-jwt política para qualquer provedor OAuth 2.0.

Esta configuração suporta o seguinte fluxo OAuth:

Gráfico de visão geral para conceituar 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 de API com o cabeçalho de autorização.
O token é validado usando a validate-jwt política no Gerenciamento de API pelo Microsoft Entra ID.
Com base no resultado da validação, o desenvolvedor receberá a resposta no portal do desenvolvedor.

Tipos de concessão de autorização

O Gerenciamento de API do Azure dá suporte aos seguintes tipos de concessão (fluxos) do OAuth 2.0. Um tipo de concessão refere-se a uma maneira 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 do seu provedor OAuth 2.0 e cenários.

Segue-se um resumo de alto nível. Para obter mais informações sobre tipos de concessão, consulte o OAuth 2.0 Authorization Framework e os tipos de concessão OAuth.

Tipo de subvenção	Description	Cenários
Código de autorização	Troca código de autorização para 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 móveis e públicos que não podem proteger um segredo ou 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 ou token, como aplicativos móveis e aplicativos de página única Geralmente não recomendado devido aos riscos inerentes de retornar o token de acesso no redirecionamento HTTP sem confirmação de que ele foi recebido pelo cliente
Palavra-passe do proprietário do recurso	Solicita credenciais de usuário (nome de usuário e senha), normalmente usando um formulário interativo	Para utilização com aplicações altamente fidedignas Só deve ser usado quando outros fluxos mais seguros não podem ser usados
Credenciais de cliente	Autentica e autoriza um aplicativo em vez de um usuário	Aplicativos máquina a máquina 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 de 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 dentro do 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 para configurar o escopo do token dependem do seu provedor OAuth 2.0.

Dependendo de seus cenários, você pode configurar escopos de token mais ou menos restritivos para outros aplicativos cliente criados para acessar APIs de back-end.
Tenha cuidado extra se ativar o fluxo de Credenciais do Cliente. O console de teste no portal do desenvolvedor, ao trabalhar 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.

Acompanhamento das informações essenciais

Ao longo deste tutorial, você será solicitado a registrar informações importantes para referência mais tarde:

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 do escopo é api://<Backend Application (client) ID>/<Scope Name> (por exemplo, api://1764e900-1827-4a0b-9182-b2c1841864c2/Read)
ID do aplicativo cliente (cliente): o GUID do aplicativo que representa o portal do desenvolvedor
Valor Secreto do Aplicativo Cliente: O GUID que serve como segredo para a interação com o aplicativo cliente no Microsoft Entra ID

Registrar aplicativos com o servidor OAuth

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

A seguir estão exemplos de etapas usando o Microsoft Entra ID como o provedor OAuth 2.0. Para obter detalhes sobre o registro do aplicativo, consulte Guia de início rápido: configurar um aplicativo para expor uma API da Web.

Registrar um aplicativo no Microsoft Entra ID para representar a API

No portal do Azure, procure e selecione Registos de aplicações.
Selecione Novo registo.
Quando a página Registar uma aplicação for apresentada, introduza as informações de registo da aplicação:
- Na seção Nome, insira um nome de aplicativo significativo que será exibido para os usuários do aplicativo, como back-end-app.
- Na seção Tipos de conta suportados, selecione uma opção adequada ao seu cenário.
Deixe a seção Redirecionar URI vazia. Mais tarde, você adicionará um URI de redirecionamento gerado na configuração do OAuth 2.0 no Gerenciamento de API.
Selecione Registar para criar a aplicação.
Na página Visão geral do aplicativo, localize o valor da ID do aplicativo (cliente) e registre-o para mais tarde.
Na seção Gerenciar do menu lateral, selecione Expor uma API e defina o URI da ID do Aplicativo com o valor padrão. Registe este valor para 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 suportado pela API (por exemplo, Files.Read).
2. Em Quem pode consentir?, faça uma seleção para o seu cenário, como Administradores e usuários. Selecione Administradores apenas para cenários com privilégios mais elevados.
3. Insira o nome de exibição do consentimento do administrador e a descrição do consentimento do administrador.
4. Verifique se o estado do escopo Ativado está selecionado.
Selecione o botão Adicionar escopo para criar o escopo.
Repita as duas etapas anteriores para adicionar todos os escopos suportados pela API.
Depois que os escopos forem criados, anote-os para uso em uma etapa subsequente.

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

Registre cada aplicativo cliente que chama a API como um aplicativo no Microsoft Entra ID.

No portal do Azure, procure e selecione Registos de aplicações.
Selecione Novo registo.
Quando a página Registar uma aplicação for apresentada, introduza as informações de registo da aplicação:
- Na seção Nome, insira um nome de aplicativo significativo que será exibido para os usuários do aplicativo, como cliente-aplicativo.
- Na seção Tipos de conta suportados, selecione uma opção adequada ao seu cenário.
Na seção Redirecionar URI, selecione Web e deixe o campo URL vazio por enquanto.
Selecione Registar para criar a aplicação.
Na página Visão geral do aplicativo, localize o valor da ID do aplicativo (cliente) e registre-o para mais tarde.
Crie um segredo de cliente para este aplicativo usar em uma etapa subsequente.
1. Na seção Gerenciar do menu lateral, selecione Certificados & 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.

Quando o segredo for criado, anote o valor da chave para uso em uma etapa subsequente. Você não pode acessar o segredo novamente no portal.

Conceder permissões no Microsoft Entra ID

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

No portal do Azure, procure e selecione Registos de aplicações.
Escolha seu aplicativo cliente. Em seguida, no menu lateral, selecione Permissões de API.
Selecione + Adicionar uma permissão.
Em Selecione uma API, selecione Minhas APIs e, em seguida, localize e selecione seu aplicativo de back-end.
Selecione Permissões delegadas e, em seguida, selecione as permissões apropriadas para seu aplicativo de back-end.
Selecione Adicionar permissões.

Opcionalmente:

Navegue até a página de permissões de API do seu aplicativo cliente.
Selecione Conceder consentimento de 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 OAuth 2.0 no Gerenciamento de API

No portal do Azure, navegue até sua instância de 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 .

Nota

Esses campos identificam o servidor de autorização OAuth 2.0 dentro do serviço de Gerenciamento de API atual. Seus valores não vêm do servidor OAuth 2.0.
Insira o URL da página de registro do cliente - por exemplo, https://contoso.com/login. Esta página é onde os usuários podem criar e gerenciar suas contas, se o seu provedor OAuth 2.0 suportar o gerenciamento de contas de usuários. A página varia dependendo do provedor OAuth 2.0 usado.

Se o seu provedor OAuth 2.0 não tiver o gerenciamento de contas de usuários configurado, insira uma URL de espaço reservado aqui, como a URL da sua empresa, ou uma URL, como http://localhost.
A próxima seção do formulário contém os tipos de concessão de autorização, URL do ponto de extremidade de autorização e configurações 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). Mais informações
- Insira o URL do ponto de extremidade de autorização. Você pode obter a URL do ponto de extremidade na página Pontos de extremidade de um dos registros do seu aplicativo. Para um aplicativo de locatário único no Microsoft Entra ID, essa URL será semelhante a uma das seguintes URLs, onde {aad-tenant} é substituída pela ID do seu locatário do Microsoft Entra.
  
  Recomenda-se o uso do endpoint v2; no entanto, o Gerenciamento de API suporta 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 PUBLICAR.
Especifique URL do ponto de extremidade do token, métodos de autenticação do cliente, método de envio do token de acesso e escopo padrão.
- Insira a URL do ponto de extremidade do token. Para um aplicativo de locatário único na ID do Microsoft Entra, ela será semelhante a uma das URLs a seguir, onde {aad-tenant} é substituída pela ID do seu locatário do Microsoft Entra. Use a mesma versão de 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)
- Se você usar pontos de extremidade v1 , adicione um parâmetro body:
  * Nome: recurso.
  * Valor: o aplicativo back-end Application (cliente) ID.
- Se você usar pontos de extremidade v2 :
  * Insira o escopo do aplicativo back-end que você criou no campo Escopo padrão.
  * Defina o valor da accessTokenAcceptedVersion propriedade como 2 no manifesto do aplicativo para os registros backend-app e client-app.
- 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 você obteve durante o processo de criação e configuração do seu aplicativo cliente.
Depois que a ID do Cliente e o segredo do Cliente forem especificados, o URI de Redirecionamento para o código de autorização será gerado. Esse URI é usado para configurar o URI de redirecionamento na configuração do servidor OAuth 2.0.

No portal do desenvolvedor, o sufixo URI tem a seguinte forma:
- /signin-oauth/code/callback/{authServerName} para fluxo de concessão de código de autorização
- /signin-oauth/implicit/callback para o fluxo de subvenção implícito
Copie o URI de redirecionamento apropriado para a página Autenticação do registro do seu aplicativo cliente. No registro do aplicativo, selecione Autenticação>+ Adicionar uma plataforma>Web e insira o URI de redirecionamento.
Se Tipos de concessão de autorização estiver definido como Senha do proprietário do recurso, a seção Credenciais da senha do proprietário do recurso será usada para especificar essas credenciais, caso contrário, você poderá deixá-la em branco.
Selecione Criar para salvar a configuração do servidor de autorização do API Management OAuth 2.0.
Republique o portal do desenvolvedor.

Importante

Ao fazer alterações relacionadas ao OAuth 2.0, certifique-se de publicar novamente o portal do desenvolvedor após cada modificação, pois alterações relevantes (por exemplo, alteração de escopo) não podem se propagar no portal e, posteriormente, ser usadas para testar as APIs.

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

Depois de salvar a configuração do servidor OAuth 2.0, configure uma API ou APIs para usar essa configuração.

Importante

Definir as configurações de autorização de usuário do OAuth 2.0 para uma API permite que o Gerenciamento de API adquira um token do servidor de autorização quando você usa o console de teste no portal do Azure ou no portal 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 OAuth 2.0 em tempo de execução, o aplicativo cliente deve adquirir e apresentar o token e você precisa configurar a validação de token no 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 OAuth 2.0 com a ID do Microsoft Entra.

Selecione APIs no menu Gerenciamento de API à esquerda.
Selecione o nome da API desejada e selecione a guia Configurações . Desloque-se para a secção Segurança e, em seguida, selecione OAuth 2.0.
Selecione o servidor de Autorização desejado na lista suspensa e selecione Salvar.

Portal do desenvolvedor - teste a autorização do usuário do OAuth 2.0

Depois de configurar seu servidor de autorização OAuth 2.0 e configurar sua API para usar esse servidor, você pode testá-lo acessando o portal do desenvolvedor e chamando uma API.

Selecione Portal do desenvolvedor no menu superior da página Visão geral da instância de Gerenciamento de API do Azure.
Navegue até qualquer operação sob a API no portal do desenvolvedor.
Selecione Experimentar para levá-lo ao console do desenvolvedor.
Observe um novo item na seção Autorização , correspondente ao servidor de autorização que você acabou de adicionar.
Selecione Código de autorização na lista suspensa de autorização.
Uma vez solicitado, entre no locatário do Microsoft Entra.
- Se já tiver sessão iniciada na conta, poderá não lhe ser solicitado.
Após a entrada bem-sucedida, um Authorization cabeçalho é adicionado à solicitação, com um token de acesso do ID do Microsoft Entra. O seguinte é 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 JWT para pré-autorizar solicitações

Na configuração até agora, o Gerenciamento de API não valida o token de acesso. Ele apenas passa 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 para validar o token de acesso de cada solicitação de entrada. Se uma solicitação não tiver um token válido, o Gerenciamento de API a bloqueará.

O exemplo de política a seguir, quando adicionado à <inbound> seção policy, verifica o valor da declaração de audiência em um token de acesso obtido do Microsoft Entra ID que é apresentado no cabeçalho Authorization. Ele retorna uma mensagem de erro se o token não for válido. Configure essa política em um escopo de política apropriado para seu cenário.

openid-config Na URL, o é o aad-tenant ID do locatário no ID do Microsoft Entra. Encontre esse valor no portal do Azure, por exemplo, na página Visão geral do seu recurso Microsoft Entra. O exemplo mostrado pressupõe um aplicativo Microsoft Entra de locatário único e um ponto de extremidade de configuração v2.
O valor do é a ID do claim cliente do aplicativo de back-end que você registrou 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>

Nota

O URL anterior openid-config corresponde ao ponto de extremidade v2. Para o ponto de extremidade v1 openid-config , use https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration.

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

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