Autorizar o acesso a APIs em seu centro de API

Você pode definir configurações para autorizar o acesso a APIs no centro de API. Estas definições:

• Habilitar a autenticação de API usando chaves de API ou autorização do OAuth 2.0
• Associar 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 API

Pré-requisitos

• Um centro de API na sua assinatura do Azure. Se você ainda não criou um, consulte Início Rápido: criar seu centro de API.

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

• 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 API. 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 do cliente OAuth 2.0. Para obter etapas para criar um cofre de chaves, consulte Criar um Key Vault. O Key Vault deve usar o modelo de permissão de controle de acesso baseado em função (RBAC) do Azure.

• (Para autorização do OAuth 2.0 usando a ID do Microsoft Entra) 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 dá suporte à autenticação de chave de API, siga estas etapas para definir as configurações no centro de API.

1. Armazenar chave de API no Azure Key Vault

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

Para armazenar a chave de API como um segredo no cofre de chaves, consulte Definir e recuperar o segredo no Key Vault.

Habilitar uma identidade gerenciada em seu Centro de APIs

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 pelo sistema usando o portal do Azure. A um nível elevado, os passos de configuração são semelhantes para uma identidade gerida atribuída pelo utilizador.

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

Atribuir a função de Usuário de Segredos do Key Vault à identidade gerenciada

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

1. No portal, navegue até o cofre de chaves.
2. No menu à esquerda, selecione Controle de acesso (IAM).
3. Escolha Adicionar atribuição de função.
4. Na página Adicionar atribuição de função, defina os valores da seguinte maneira:
   1. Na guia Função, selecione Usuário de Segredos do Key Vault.
   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 pelo sistema ao Centro de APIs que você adicionou na seção anterior. Clique em Selecionar.
   4. Selecione Examinar + atribuir duas vezes.

2. Adicionar configuração de chave de API no centro de API

1. No portal, navegue até seu centro de API.

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

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

   Configurações	Descrição
   Título	Insira um nome para a autorização.
   Descrição	Opcionalmente, insira uma descrição para a autorização.
   Esquema de segurança	Selecione Chave de API.
   Local da chave de API	Selecione como a chave é apresentada em solicitações de API. Os valores disponíveis são Cabeçalho (cabeçalho da solicitação) e Consulta (parâmetro de consulta).
   Nome do parâmetro de chave de API	Insira o nome do cabeçalho HTTP ou parâmetro de consulta que contém a chave de API. Exemplo: x-api-key
   Referência de segredo da chave de API do Key Vault	Clique em Selecionar e selecione a assinatura, o cofre de chaves e o segredo armazenados. 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 obter uma API compatível com a autorização do OAuth 2.0, siga estas etapas para definir as configurações de autenticação no 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 (Chave de Prova para o Code Exchange) – esse fluxo é recomendado para autenticar usuários no navegador, como no portal do Centro de API.
• 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. Criar um aplicativo OAuth 2.0

Para autorização do OAuth 2.0, registre um aplicativo em um provedor de identidade, como o tenant do Microsoft Entra associado à sua assinatura 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 na ID do Microsoft Entra.

1. Entre no portal do Azure com uma conta que tenha permissões suficientes no locatário.
2. Navegue até Microsoft Entra ID>+ Novo registro.
3. Na página Registrar um aplicativo , insira as configurações de registro do aplicativo:
   1. Em Nome, insira um nome significativo para o aplicativo.
   2. Em tipos de conta com suporte, selecione uma opção que se adapte ao seu cenário, por exemplo, Contas somente neste diretório organizacional (locatário único).
   3. (Para fluxo de código de autorização) No URI de Redirecionamento, selecione SPA (aplicativo de página única) e defina o URI. Insira o URI da implantação do portal do Centro de API, no seguinte formulário: https://<service-name>.portal.<location>.azure-api-center.ms. Substitua <service name> e <location> pelo nome do centro de API e o local onde ele está implantado, exemplo: https://myapicenter.portal.eastus.azure-api-center.ms
   4. Selecione Registrar.
4. No menu à esquerda, em Gerenciar, selecione Certificados &segredos e selecione + Novo segredo do cliente.
   1. Insira uma Descrição.
   2. Selecione uma opção para Expira em.
   3. Selecione Adicionar.
   4. Copie o Valor da chave secreta do cliente antes de sair da página. Você precisará dela na seção a seguir.
5. Opcionalmente, adicione escopos de API no registro do aplicativo. Para obter mais informações, consulte Configurar um aplicativo para expor uma API Web.

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

• A ID do aplicativo (cliente) da página Visão Geral do registro do aplicativo e o segredo do cliente que você copiou anteriormente.
• As seguintes URLs de ponto de extremidade na página Visão geral>Pontos de extremidade do registro do aplicativo:
  • Ponto de extremidade da autorização OAuth2.0 (v2) - o ponto de extremidade da autorização para o Microsoft Entra ID
  • Ponto de extremidade do token OAuth 2.0 (v2) - o ponto de extremidade do token e o ponto de extremidade de atualização do token para o Microsoft Entra ID
• Todos os escopos de API configurados no registro do aplicativo.

2. Armazenar o segredo do cliente no Azure Key Vault

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

Para armazenar a chave de API como um segredo no cofre de chaves, consulte Definir e recuperar o segredo no Key Vault.

Habilitar uma identidade gerenciada em seu Centro de APIs

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 pelo sistema usando o portal do Azure. A um nível elevado, os passos de configuração são semelhantes para uma identidade gerida atribuída pelo utilizador.

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

Atribuir a função de Usuário de Segredos do Key Vault à identidade gerenciada

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

1. No portal, navegue até o cofre de chaves.
2. No menu à esquerda, selecione Controle de acesso (IAM).
3. Escolha Adicionar atribuição de função.
4. Na página Adicionar atribuição de função, defina os valores da seguinte maneira:
   1. Na guia Função, selecione Usuário de Segredos do Key Vault.
   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 pelo sistema ao Centro de APIs que você adicionou na seção anterior. Clique em Selecionar.
   4. Selecione Examinar + atribuir duas vezes.

3. Adicionar autorização do OAuth 2.0 no centro de API

1. No portal, navegue até seu centro de API.

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

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

   

   Observação

   Defina as configurações com base no registro de aplicativo criado anteriormente em seu provedor de identidade. Se você estiver usando o Microsoft Entra ID, encontre a ID do cliente na página Visão geral do registro do aplicativo e encontre as URLs dos pontos de extremidade na página Visão geral>Pontos de extremidade.

   Configurações	Descrição
   Título	Insira um nome para a autorização.
   Descrição	Opcionalmente, insira uma descrição para a autorização.
   Esquema de segurança	Selecione OAuth2.
   ID do cliente	Insira a 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 armazenados. Exemplo: https://<key-vault-name>.vault.azure.net/secrets/<secret-name>
   URL de Autorização	Insira o endpoint de autorização do OAuth 2.0 para o provedor de identidade. Exemplo de ID do Microsoft Entra: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize
   URL do Token	Insira o ponto de extremidade do token OAuth 2.0 para o provedor de identidade. Exemplo de ID do Microsoft Entra: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
   Atualizar URL	Insira o ponto de extremidade 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 o código de autorização (PKCE) e as credenciais do cliente.
   Escopos	Insira um ou mais escopos de API configurados para sua API, separados por espaços. Se nenhum escopo estiver configurado, insira .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 centro de API.

1. No portal, navegue até seu centro de API.
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 (versão prévia)>+ 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. Você faz isso configurando uma política de acesso que atribui aos usuários ou grupos a função Leitor de Acesso de Credencial 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 um fluxo OAuth 2.0.

1. No portal, navegue até seu centro de API.

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 (versão prévia).

4. Selecione a lista suspensa Editar políticas de acesso no final da linha da 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 você deseja adicionar. Você pode selecionar vários itens.

7. Clique em Selecionar.

Testar a API no portal do Centro de API

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

1. No portal, navegue até seu centro de API.

2. No menu à esquerda, no Portal do Centro de API, selecione as configurações do Portal.

3. Selecione Exibir portal do Centro de API.

4. No portal do Centro de API, 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 é aberta, examine as configurações de autenticação. Se você tiver acesso à API, selecione Enviar para experimentar a API.

9. Se a operação for bem-sucedida, você verá o 200 OK código de resposta 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 a exibição do portal do Centro de API do Azure no Visual Studio Code
• Autenticação e autorização no Gerenciamento de API do Azure