Partilhar via

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

Observação

Esta funcionalidade está atualmente em pré-visualização.

Pré-requisitos

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: Captura de tela da configuração de uma chave de API no portal.

    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:

    Captura de tela da configuração do OAuth 2.0 no portal.

    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.

Observação

Você pode adicionar várias configurações de autenticação a uma versão da API. Por exemplo, você pode adicionar a chave da API e as configurações do OAuth 2.0 à mesma versão da API, se suportada pela API. Da mesma forma, você pode adicionar as mesmas configurações a várias versões de API.

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. Captura de ecrã a mostrar a adição de uma política de acesso no portal.

  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.

Sugestão

Você também pode remover usuários ou grupos da política de acesso. Na página Gerenciar acesso , selecione Excluir no menu de contexto (...) para o usuário ou grupo.

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.

Sugestão

Além de permitir que usuários específicos testem APIs específicas no portal do Centro de APIs, você pode definir configurações de visibilidade para APIs. As configurações de visibilidade no portal controlam as APIs que aparecem para todos os usuários conectados.

  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. Captura de tela dos detalhes da API no portal do Centro de APIs.

  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. Captura de tela do teste de uma API no console de teste do portal do Centro de APIs.

  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

  • Last updated on