Autorizar o acesso a APIs no seu centro de APIs

Você pode definir configurações para autorizar o acesso a APIs em seu centro de APIs. Estas configurações:

• Habilite a autenticação de API usando chaves de API ou autorização OAuth 2.0
• Associe métodos de autenticação específicos a versões de API específicas em seu inventário
• Gerenciar a autenticação em versões de API por usuários ou grupos designados por meio de políticas de acesso
• Permitir que usuários autorizados testem APIs diretamente no portal do Centro de APIs

Pré-requisitos

• Um centro de API na sua subscrição do Azure. Se você ainda não criou um, consulte Guia de início rápido: criar sua central de API.

• Registre pelo menos uma API em seu centro de APIs. Para obter mais informações, consulte Tutorial: Registrar APIs em seu inventário de APIs.

• Configure um ambiente e uma implantação para a API. Para obter mais informações, consulte Tutorial: Adicionar ambientes e implantações para APIs.

• Configure o portal do Centro de APIs. Para obter mais informações, consulte Configurar o portal do Centro de API.

• Um cofre de chaves do Azure para armazenar chaves de API ou segredos de cliente OAuth 2.0. Para conhecer as etapas para criar um cofre de chaves, consulte Criar um cofre de chaves. O cofre de chaves deve usar o modelo de permissão RBAC (controle de acesso baseado em função) do Azure.

• (Para autorização OAuth 2.0 usando o Microsoft Entra ID) Permissões para criar um registro de aplicativo em um locatário do Microsoft Entra associado à sua assinatura do Azure.

Opção 1: Definir configurações para autenticação de chave de API

Para uma API que ofereça suporte à autenticação de chave de API, siga estas etapas para definir as configurações em sua central de APIs.

1. Armazenar a chave da API no Cofre da Chave do Azure

Para gerenciar a chave de API com segurança, armazene-a no Cofre de Chaves do Azure e acesse o cofre de chaves usando a identidade gerenciada do seu centro de API.

Para armazenar a chave da API como um segredo no cofre de chaves, consulte Definir e recuperar segredo no Cofre de Chaves.

Habilite uma identidade gerenciada em seu centro de API

Para esse cenário, o centro de API usa uma identidade gerenciada para acessar o cofre de chaves. Dependendo das suas necessidades, habilite uma identidade gerenciada atribuída pelo sistema ou uma ou mais identidades gerenciadas atribuídas pelo usuário.

O exemplo a seguir mostra como habilitar uma identidade gerenciada atribuída ao sistema usando o portal do Azure. Em um alto nível, as etapas de configuração são semelhantes para uma identidade gerenciada atribuída pelo usuário.

1. No portal, navegue até o seu centro de APIs.
2. No menu à esquerda, em Segurança, selecione Identidades gerenciadas.
3. Selecione Sistema atribuído e defina o status como Ativado.
4. Selecione Guardar.

Atribuir a função de usuário Segredos do Cofre de Chaves à identidade gerenciada

Atribua à identidade gerida do seu centro de API a função Key Vault Secrets User no Key Vault. As etapas a seguir usam o portal do Azure.

1. No portal, navegue até o seu cofre de chaves.
2. No menu à esquerda, selecione Controle de acesso (IAM).
3. Selecione + Adicionar atribuição de função.
4. Na página Adicionar atribuição de função, defina os valores da seguinte forma:
   1. Na guia Função, selecione Usuário de Segredos do Cofre da Chave.
   2. Na guia Membros, em Atribuir acesso a, selecione Identidade> gerenciada+ Selecionar membros.
   3. Na página Selecionar identidades gerenciadas, selecione a identidade gerenciada atribuída ao sistema do seu centro de API que você adicionou na seção anterior. Clique em Selecionar.
   4. Selecionar Rever + atribuir duas vezes.

2. Adicione a configuração da chave de API no seu centro de API

1. No portal, navegue até o seu centro de APIs.

2. No menu à esquerda, em Governança, selecione Autorização (visualização)>+ Adicionar configuração.

3. Na página Adicionar configuração , defina os valores da seguinte forma:

   Configuração	Descrição
   Título	Insira um nome para a autorização.
   Descrição	Opcionalmente, insira uma descrição para a autorização.
   Regime de segurança	Selecione Chave de API.
   Localização da chave da API	Selecione como a chave é apresentada nas solicitações de API. Os valores disponíveis são Header (cabeçalho da solicitação) e Query (parâmetro de consulta).
   Nome do parâmetro de chave da API	Digite o nome do cabeçalho HTTP ou parâmetro de consulta que contém a chave da API. Exemplo: x-api-key
   Referência secreta do Cofre da Chave da API	Clique em Selecionar e selecione a assinatura, o cofre de chaves e o segredo que você armazenou. Exemplo: https://<key-vault-name>.vault.azure.net/secrets/<secret-name>

4. Selecione Criar.

Opção 2: Definir configurações para autorização do OAuth 2.0

Para uma API que ofereça suporte à autorização OAuth 2.0, siga estas etapas para definir as configurações de autenticação no seu centro de API. Você pode definir configurações para um ou ambos os seguintes fluxos de autorização do OAuth 2.0:

• Fluxo de código de autorização com PKCE (Proof Key for Code Exchange) - Esse fluxo é recomendado para autenticar usuários no navegador, como no portal do Centro de APIs.
• Fluxo de credenciais do cliente - Esse fluxo é recomendado para aplicativos que não exigem permissões de um usuário específico para acessar dados.

1. Crie um aplicativo OAuth 2.0

Para autorização do OAuth 2.0, crie um registo de aplicação num fornecedor de identidade, como o tenant do Microsoft Entra associado ao seu subscrição do Azure. As etapas exatas de criação dependem do provedor de identidade que você usa.

O exemplo a seguir mostra como criar um registro de aplicativo no Microsoft Entra ID.

1. Entre no portal do Azure com uma conta com permissões suficientes no locatário.
2. Navegue até Microsoft Entra ID>+ Novo registro.
3. Na página Registar uma candidatura , introduza as definições de registo da sua candidatura:
   1. Em Nome, insira um nome significativo para o aplicativo.
   2. Em Tipos de conta suportados, selecione uma opção que se adapte ao seu cenário, por exemplo, Contas apenas neste diretório organizacional (Locatário único).
   3. (Para fluxo de código de autorização) Em Redirecionar URI, selecione Aplicativo de página única (SPA) e defina o URI. Insira o URI da implantação do portal do Centro de APIs, no seguinte formato: https://<service-name>.portal.<location>.azure-api-center.ms. Substitua <service name> e <location> pelo nome do seu centro de API e o local onde ele foi implantado, Exemplo: https://myapicenter.portal.eastus.azure-api-center.ms
   4. Selecione Register.
4. No menu à esquerda, em Gerenciar, selecione Certificados & segredos e, em seguida, selecione + Novo segredo do cliente.
   1. Insira uma descrição.
   2. Selecione uma opção para Data de Expiração.
   3. Selecione Adicionar.
   4. Copie o Valor do segredo do cliente antes de sair da página. Você precisará dele na seção a seguir.
5. Opcionalmente, adicione escopos de API no registro do seu aplicativo. Para obter mais informações, veja Configurar uma aplicação para expor uma API Web.

Ao configurar a autorização do OAuth 2.0 em seu centro de API, você precisará dos seguintes valores do registro do aplicativo:

• O ID do aplicativo (cliente) da página Visão geral do registro do aplicativo e o segredo do cliente copiado anteriormente.
• Os seguintes URLs de ponto de extremidade na página Visão Geral>Endpoints do registo da aplicação:
  • OAuth2.0 authorization endpoint (v2) - o endpoint de autorização do Microsoft Entra ID
  • OAuth 2.0 token endpoint (v2) - o ponto de extremidade de token e o ponto de extremidade de atualização de token para o Microsoft Entra ID
• Quaisquer escopos de API configurados no registro do aplicativo.

2. Armazenar segredo do cliente no Cofre da Chave do Azure

Para gerenciar o segredo com segurança, armazene-o no Cofre de Chaves do Azure e acesse o cofre de chaves usando a identidade gerenciada do seu centro de API.

Para armazenar a chave da API como um segredo no cofre de chaves, consulte Definir e recuperar segredo no Cofre de Chaves.

Habilite uma identidade gerenciada em seu centro de API

Para esse cenário, o centro de API usa uma identidade gerenciada para acessar o cofre de chaves. Dependendo das suas necessidades, habilite uma identidade gerenciada atribuída pelo sistema ou uma ou mais identidades gerenciadas atribuídas pelo usuário.

O exemplo a seguir mostra como habilitar uma identidade gerenciada atribuída ao sistema usando o portal do Azure. Em um alto nível, as etapas de configuração são semelhantes para uma identidade gerenciada atribuída pelo usuário.

1. No portal, navegue até o seu centro de APIs.
2. No menu à esquerda, em Segurança, selecione Identidades gerenciadas.
3. Selecione Sistema atribuído e defina o status como Ativado.
4. Selecione Guardar.

Atribuir a função de usuário Segredos do Cofre de Chaves à identidade gerenciada

Atribua à identidade gerida do seu centro de API a função Key Vault Secrets User no Key Vault. As etapas a seguir usam o portal do Azure.

1. No portal, navegue até o seu cofre de chaves.
2. No menu à esquerda, selecione Controle de acesso (IAM).
3. Selecione + Adicionar atribuição de função.
4. Na página Adicionar atribuição de função, defina os valores da seguinte forma:
   1. Na guia Função, selecione Usuário de Segredos do Cofre da Chave.
   2. Na guia Membros, em Atribuir acesso a, selecione Identidade> gerenciada+ Selecionar membros.
   3. Na página Selecionar identidades gerenciadas, selecione a identidade gerenciada atribuída ao sistema do seu centro de API que você adicionou na seção anterior. Clique em Selecionar.
   4. Selecionar Rever + atribuir duas vezes.

3. Adicione a autorização do OAuth 2.0 no seu centro de API

1. No portal, navegue até o seu centro de APIs.

2. No menu à esquerda, em Governança, selecione Autorização (visualização)>+ Adicionar configuração.

3. Na página Adicionar configuração , defina os valores da seguinte forma:

   

   Observação

   Configure as configurações com base no registro do aplicativo que você criou anteriormente em seu provedor de identidade. Caso esteja a usar o Microsoft Entra ID, encontre o ID do Cliente na página Visão Geral do registo da aplicação e encontre os URL dos pontos de extremidade na página Visão Geral>Pontos de Extremidade.

   Configuração	Descrição
   Título	Insira um nome para a autorização.
   Descrição	Opcionalmente, insira uma descrição para a autorização.
   Regime de segurança	Selecione OAuth2.
   ID de Cliente	Insira o ID do cliente (GUID) do aplicativo que você criou em seu provedor de identidade.
   Segredo do cliente	Clique em Selecionar e selecione a assinatura, o cofre de chaves e o segredo do cliente que você armazenou. Exemplo: https://<key-vault-name>.vault.azure.net/secrets/<secret-name>
   URL de autorização	Insira o endpoint de autorização OAuth 2.0 para o provedor de identidade. Exemplo de ID do Microsoft Entra: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize
   Token URL	Insira o endpoint de token OAuth 2.0 para o fornecedor de identidade. Exemplo de ID do Microsoft Entra: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
   Atualizar URL	Insira o endpoint de atualização do token OAuth 2.0 para o provedor de identidade. Para a maioria dos provedores, o mesmo que a URL do token Exemplo de ID do Microsoft Entra: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
   Fluxo OAuth2	Selecione um ou ambos os fluxos OAuth 2.0 que você deseja usar. Os valores disponíveis são código de autorização (PKCE) e credenciais de cliente.
   Escopos	Insira um ou mais escopos de API configurados para sua API, separados por espaços. Se nenhum escopo estiver configurado, digite .default.

4. Selecione Criar para salvar a configuração.

Adicionar configuração de autenticação a uma versão da API

Depois de definir as configurações para uma chave de API ou um fluxo OAuth 2.0, adicione a chave de API ou a configuração do OAuth 2.0 a uma versão da API no seu centro de API.

1. No portal, navegue até o seu centro de APIs.
2. No menu à esquerda, em Ativos, selecione APIs.
3. Selecione uma API à qual você deseja associar a configuração de autorização.
4. No menu à esquerda, em Detalhes, selecione Versões.
5. Selecione a versão da API à qual você deseja adicionar a configuração de autenticação.
6. No menu à esquerda, em Detalhes, selecione Gerenciar acesso (visualização)>+ Adicionar autenticação.
7. Na página Adicionar autenticação , selecione uma configuração de Autenticação disponível que você deseja associar.
8. Selecione Criar.

Gerenciar o acesso por usuários ou grupos específicos

Você pode gerenciar o acesso de usuários ou grupos específicos em sua organização à configuração de autenticação de uma versão da API. Para fazer isso, configure uma política de acesso que atribua aos usuários ou grupos a função Leitor de Acesso a Credenciais do Centro de API , com escopo para configurações de autenticação específicas na versão da API. Isso é útil, por exemplo, se você quiser permitir que apenas usuários específicos testem uma API no portal do Centro de API usando uma chave de API ou fluxo OAuth 2.0.

1. No portal, navegue até o seu centro de APIs.

2. Navegue até uma versão da API à qual você adicionou uma configuração de autenticação (consulte a seção anterior).

3. No menu à esquerda, em Detalhes, selecione Gerenciar acesso (visualização).

4. Selecione a lista suspensa Editar políticas de acesso no final da linha para a configuração de autenticação cujo acesso você deseja gerenciar.

5. Na página Gerenciar acesso , selecione + Adicionar > usuários ou + Adicionar > grupos.

6. Pesquise e selecione os usuários (ou grupos) que deseja adicionar. Você pode selecionar vários itens.

7. Clique em Selecionar.

Testar API no portal do Centro de API

Você pode usar o portal da Central de APIs para testar uma API configurada para autenticação e acesso de usuário.

1. No portal, navegue até o seu centro de APIs.

2. No menu à esquerda, em API Center Portal, selecione Configurações do portal.

3. Selecione Exibir portal do Centro de APIs.

4. No portal do Centro de APIs, selecione uma API que você deseja testar.

5. Selecione uma versão da API que tenha um método de autenticação configurado.

6. Em Opções, selecione Exibir documentação.

7. Selecione uma operação na API e selecione Experimentar esta API.

8. Na janela que se abre, reveja as definições de autenticação. Se você tiver acesso à API, selecione Enviar para tentar a API.

9. Se a operação for bem-sucedida, o utilizador verá o código de resposta 200 OK e o corpo da resposta. Se a operação falhar, você verá uma mensagem de erro.

Conteúdo relacionado

• Configurar o portal do Centro de API
• Habilitar o modo de exibição do portal do Centro de API do Azure no Visual Studio Code
• Autenticação e autorização às APIs na Gestão de API do Azure