Autorizar o acesso a APIs no seu centro de APIs

Configure definições para autorizar o acesso às APIs no seu centro de APIs. Estas configurações:

• Ative a autenticação e autorização da API usando chaves API, autorização OAuth 2.0 ou outro esquema de segurança HTTP
• Associe as configurações de autenticação às versões da API no seu inventário
• Gerir o acesso às versões da API para utilizadores ou grupos designados através de políticas de acesso
• Permitir que utilizadores autorizados testem APIs no portal do API Center

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 APIs.

• Pelo menos uma API registada no seu centro de APIs. Veja o Tutorial: Registe APIs no teu inventário de APIs.

• Um ambiente e uma implementação configurados para a API. Veja o Tutorial: Adicionar ambientes e implementações para APIs.

• O portal do API Center foi configurado. Consulte Configurar o portal do API Center.

• Um cofre de chaves do Azure para armazenar chaves de API ou segredos de cliente OAuth 2.0. Consulte Criar um cofre de chaves. O cofre de chaves deve usar o modelo de permissões de controlo de acesso baseado em papéis (RBAC) do Azure.

• (Para OAuth 2.0 com Microsoft Entra ID) Permissões para criar um registo de aplicação num tenant Microsoft Entra associado à sua subscrição.

Opção 1: Configurar autenticação por chave API

Para uma API que suporta autenticação por chave API, complete os seguintes passos.

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

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

Aceda ao cofre de chaves usando a identidade gerida do seu centro API.

Habilite uma identidade gerenciada em seu centro de API

Para esse cenário, sua central de API usa uma identidade gerenciada para acessar recursos do Azure. Dependendo das suas necessidades, habilite uma identidade gerenciada atribuída pelo sistema ou uma ou mais identidades gerenciadas atribuídas pelo usuário.

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

az apic update --name <api-center-name> --resource-group <resource-group-name> --identity '{"type": "SystemAssigned"}'

Atribuir a identidade gerida à função Utilizador de Segredos do Cofre de Chaves

Para permitir a importação dos ativos, atribua à identidade gerida do seu centro API o papel de Utilizador Key Vault Secrets no seu Azure Key Vault. Você pode usar o portal ou a CLI do Azure.

2. Adicionar configuração de chave API

1. No portal, vai ao teu centro de API.

2. Em Governação, selecione Autorização (pré-visualização)>+ Adicionar configuração.

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

   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	Selecione Selecionar e selecione a subscrição, o cofre de chaves e o segredo que guardou. Exemplo: https://<key-vault-name>.vault.azure.net/secrets/<secret-name>

4. Selecione Criar.

Após concluir esta configuração, vá à secção Adicionar configuração de autenticação a uma versão da API para associar a configuração da chave API a uma versão da API.

Opção 2: Configurar a autorização OAuth 2.0

Para uma API que suporta autorização OAuth 2.0, complete os seguintes passos. Pode configurar um ou ambos os seguintes fluxos:

• Fluxo de código de autorização com PKCE (Proof Key for Code Exchange) - Autenticar utilizadores no navegador, como no portal do API Center.
• Fluxo de credenciais do cliente - Para aplicações que não requerem permissões específicas de um utilizador.

1. Crie um aplicativo OAuth 2.0

Crie um registo de aplicação num fornecedor de identidade, como o inquilino Microsoft Entra associado à sua subscrição. Os passos dependem do seu fornecedor de identidade.

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

1. Inicia sessão no portal Azure com permissões suficientes no tenant.
2. Vá ao Microsoft Entra ID>+ Novo registo.
3. Na página de Registo de Aplicação:
   1. No Nome, introduza um nome significativo.
   2. Nos tipos de conta suportados, selecione uma opção apropriada, por exemplo, Contas apenas neste diretório organizacional (Inquilino único).
   3. (Para fluxo de código de autorização) No Redirect URI, selecione Single-page application (SPA) e introduza o URI do portal do seu API Center: https://<service-name>.portal.<location>.azure-api-center.ms. Substitua <service-name> e <location> com o nome do seu centro API e localização de implementação. Exemplo: https://myapicenter.portal.eastus.azure-api-center.ms
   4. Selecione Register.
4. Em Gerir, selecione Certificados & Segredos>+ Novo cliente secreto.
   1. Insira uma descrição.
   2. Selecione uma opção para Data de Expiração.
   3. Selecione Adicionar.
   4. Copie o valor secreto do cliente antes de sair da página. Precisas disso na próxima secção.
5. Opcionalmente, adicione escopos de API no registro do seu aplicativo. Veja Configurar uma aplicação para expor uma API web.

Ao configurar o OAuth 2.0 no seu centro de API, precisa dos seguintes valores do registo da app:

• ID da aplicação (cliente) da página de Visão Geral , e o segredo do cliente que copiou.
• Os seguintes URLs dos pontos finais do Overview>Endpoints:
  • OAuth2.0 endpoint de autorização (v2)
  • OAuth 2.0 token endpoint (v2) (também usado como endpoint de atualização de token)
• Quaisquer escopos de API que tenha configurado.

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

Para armazenar o segredo do cliente no cofre de chaves, consulte Definir e recuperar segredo no Cofre de Chaves.

Aceda ao cofre de chaves usando a identidade gerida do seu centro API.

Habilite uma identidade gerenciada em seu centro de API

Para esse cenário, sua central de API usa uma identidade gerenciada para acessar recursos do Azure. Dependendo das suas necessidades, habilite uma identidade gerenciada atribuída pelo sistema ou uma ou mais identidades gerenciadas atribuídas pelo usuário.

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

az apic update --name <api-center-name> --resource-group <resource-group-name> --identity '{"type": "SystemAssigned"}'

Atribuir a identidade gerida à função Utilizador de Segredos do Cofre de Chaves

Para permitir a importação dos ativos, atribua à identidade gerida do seu centro API o papel de Utilizador Key Vault Secrets no seu Azure Key Vault. Você pode usar o portal ou a CLI do Azure.

3. Adicionar configuração OAuth 2.0

1. No portal, vai ao teu centro de API.

2. Em Governação, selecione Autorização (pré-visualização)>+ Adicionar configuração.

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

   

   Observação

   Use valores do registo da aplicação que criou anteriormente. Para o Microsoft Entra ID, encontre o ID do Cliente na página Visão Geral do registo da aplicação e os endpoints URL nas secções Visão Geral> e Endpoints.

   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) da aplicação que criou no seu provedor de identidade.
   Segredo do cliente	Selecione a subscrição, o cofre de chaves e o segredo de cliente que guardou. 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: código de autorização (PKCE) e credenciais do 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.

Após concluir esta configuração, vá à secção Adicionar configuração de autenticação a uma versão da API para associar a configuração do OAuth 2.0 a uma versão da API.

Opção 3: Configurar definições para outro esquema de segurança HTTP

Para APIs que utilizam outro esquema de segurança HTTP, como autenticação básica ou tokens portadores que não utilizam OAuth 2.0, complete os seguintes passos. Pode ser necessário escolher esta opção para APIs legadas.

No portal, vai ao teu centro de API.

1. Em Governação, selecione Autorização (pré-visualização)>+ Adicionar configuração.

2. Na página Adicionar configuração , defina os seguintes valores:

   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 HTTP.
   Esquema de autenticação	Selecione o esquema de autenticação utilizado pela API. Exemplos incluem os esquemas na seguinte tabela.

   Esquema de autenticação	Descrição
   Basic	Envia username:password como uma string codificada em Base64 no Authorization: Basic <credentials> cabeçalho.
   Portador	No cabeçalho Authorization: Bearer <token>, envia um token que não seja um token de acesso OAuth 2.0.
   Sumário	Um mecanismo de desafio-resposta onde o servidor envia um nonce; o cliente responde com um hash de credenciais + nonce.
   Personalizado	Outro esquema de mecanismo, como um esquema específico para o fornecedor.

Após completar esta configuração, avance para a secção seguinte para associar a configuração a uma versão da API.

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

Após configurar um esquema de autenticação, associe a configuração a uma versão da API.

1. No portal, vai ao teu centro de API.

2. Em Inventário, selecione Ativos.

3. Selecione a API para associar a configuração.

4. Em Detalhes, selecione Versões e depois selecione a versão alvo da API.

5. No menu de contexto da versão da API, selecione Gerir Acesso (pré-visualização).

6. Na página Gerir Acesso , selecione + Adicionar autenticação.

7. Selecione uma configuração de Autenticação disponível.

8. Selecione Criar.

Gerir o acesso para utilizadores ou grupos específicos

Configure uma política de acesso que atribua aos utilizadores ou grupos a função Leitor de Acesso a Credenciais do Centro de API, abrangendo configurações específicas de autenticação numa versão da API. Este papel permite apenas que utilizadores designados testem uma API no portal do API Center.

1. No portal, vai ao teu centro de API.

2. Vai para uma versão da API com uma configuração de autenticação.

3. Selecione Gerir Acesso (pré-visualização).

4. Selecione uma configuração de autenticação que queira gerir.

5. No menu suspenso, selecione Editar políticas de acesso.

6. Na página Gerir acesso , selecione + Adicionar > Utilizadores ou + Adicionar > Grupos.

7. Pesquise e selecione utilizadores ou grupos. Você pode selecionar vários itens.

8. Selecione Selecione.

Teste a API no portal API Center

Testa uma API que configuraste para autenticação e acesso do utilizador.

1. No portal, vai ao teu centro de API.

2. Em Portal do Centro API, selecione Definições do Portal>Ver portal do Centro API.

3. Selecione uma API, depois selecione uma versão com um método de autenticação configurado.

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

5. Selecione uma operação, depois selecione Tentar esta API.

6. Veja as definições de autenticação. Se tiver acesso, selecione Enviar.

7. Uma operação bem-sucedida retorna um código de resposta 200 OK e um corpo de resposta. Uma operação falhada devolve 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