Assinaturas no API Management do Azure

APLICA-SE: Todos os níveis de Gestão de APIs

No Gerenciamento de API do Azure, as assinaturas são a maneira mais comum de os consumidores de API acessarem APIs publicadas por meio de uma instância de Gerenciamento de API. Este artigo fornece uma visão geral do conceito.

Nota

Uma subscrição de Gestão de APIs é usada especificamente para chamar APIs através da Gestão de APIs, utilizando uma chave de subscrição. Não é o mesmo que uma subscrição do Azure.

O que são subscrições?

Ao publicar APIs através da API Management, pode facilmente garantir o acesso à API usando chaves de subscrição. Os programadores que precisem de utilizar as APIs publicadas devem incluir uma chave de subscrição válida nos pedidos HTTP ao chamar essas APIs. Sem a utilização de uma chave de subscrição válida, as chamadas são:

• Rejeitada imediatamente pelo gateway de Gestão de API.
• Não reencaminhados para os serviços de back-end.

Para aceder às APIs, os programadores precisam de uma subscrição e de uma chave de subscrição. Uma subscrição é um contêiner nomeado para um par de chaves de subscrição.

Além disso,

• Os desenvolvedores podem obter subscrições sem precisar da aprovação dos editores de API.
• Os publicadores de API podem criar assinaturas diretamente para consumidores de API.

Sugestão

O API Management também oferece suporte a outros mecanismos para proteger o acesso a APIs, incluindo os seguintes exemplos:

• OAuth2.0
• Certificados de cliente
• Restringir IPs dos chamadores

Gerir chaves de subscrição

A regeneração regular de chaves é uma precaução de segurança comum. Tal como a maioria dos serviços Azure que requerem uma chave de subscrição, a API Management gera chaves em pares. Cada aplicação que utiliza o serviço pode alternar da chave A para a chave B e regenerar a chave A com o mínimo de perturbações, e vice-versa.

Em vez de regenerar chaves, você pode definir chaves específicas invocando a Assinatura de Gerenciamento de API do Azure - Criar ou atualizar a API REST do Azure. Especificamente, definir properties.primaryKey e/ou properties.secondaryKey no corpo do pedido HTTP.

Nota

• O Gerenciamento de API não fornece recursos internos para gerenciar o ciclo de vida das chaves de assinatura, como definir datas de expiração ou girar chaves automaticamente. Pode desenvolver fluxos de trabalho para automatizar estes processos usando ferramentas como Azure PowerShell ou os SDKs do Azure.
• Para impor acesso limitado por tempo às APIs, os editores de API podem usar políticas com chaves de assinatura ou usar um mecanismo que forneça expiração interna, como autenticação baseada em token.

Âmbito das subscrições

Pode associar subscrições a vários âmbitos: produto, todas as APIs ou uma API individual.

Subscrições de um produto

Tradicionalmente, associa-se as subscrições na API Management a um único âmbito de produto . Desenvolvedores:

• Encontre a lista de produtos no portal do desenvolvedor.
• Envie pedidos de subscrição para os produtos que querem usar.
• Acesse as APIs do produto usando as chaves nessas subscrições que são aprovadas automaticamente ou pelos publicadores da API.

Atualmente, o portal do desenvolvedor mostra apenas as assinaturas do escopo do produto na secção Perfil de Utilizador.

Assinaturas para todas as APIs ou uma API individual

Você também pode criar chaves que concedem acesso a uma das seguintes opções:

• Uma única API, ou
• Todas as APIs dentro de uma instância de Gestão de API.

Nesses casos, não precisa de criar um produto e adicionar APIs a ele primeiro.

Subscrição de acesso ilimitado

Cada instância de Gerenciamento de API vem com uma assinatura de acesso total interna que concede acesso a todas as APIs. Esta assinatura com âmbito de serviço facilita aos proprietários do serviço testar e depurar APIs na consola de teste.

Aviso

A subscrição de acesso total permite o acesso a todas as APIs na instância de Gestão de APIs. Apenas utilizadores autorizados devem usar esta subscrição. Nunca utilize esta subscrição para acesso de rotina à API ou incorpore a chave de subscrição de acesso total em aplicações cliente.

Nota

Se você estiver usando uma assinatura com escopo de API, uma assinatura com todas as APIs ou a assinatura interna de acesso total, as políticas configuradas no escopo do produto não serão aplicadas às solicitações dessa assinatura.

Subscrições autónomas

O Gerenciamento de API também permite assinaturas autônomas , que não estão associadas a uma conta de desenvolvedor. Esta funcionalidade é útil em cenários como vários programadores ou equipas a partilhar uma subscrição.

Criar uma subscrição sem atribuir um proprietário torna-a numa subscrição autónoma. Para conceder aos programadores e ao resto da sua equipa acesso à chave de subscrição autónoma, escolha uma das seguintes opções:

• Partilhe manualmente a chave de subscrição.
• Use um sistema personalizado para disponibilizar a chave de assinatura à sua equipa.

Nota

Não podes atribuir subscrições diretamente na API Management aos grupos de segurança do Microsoft Entra ID. Para fornecer acesso por subscrição a múltiplos utilizadores num grupo, criar uma subscrição autónoma e distribuir as chaves de subscrição aos membros do grupo, ou integrar com o Microsoft Entra ID para autenticação e usar políticas para controlar o acesso à API com base na pertença ao grupo.

Criar e gerir subscrições no portal do Azure

Os editores de APIs (administradores ou programadores com permissões adequadas) podem criar subscrições diretamente no portal Azure, iniciando sessão na sua instância de Gestão de APIs. Os consumidores da API não podem criar subscrições através do portal Azure; normalmente solicitam subscrições através do portal de programadores ou recebem-nas de editores de APIs.

Quando crias uma subscrição no portal, está no estado Ativo , o que significa que um assinante pode chamar uma API associada usando uma chave de subscrição válida. Você pode alterar o estado da subscrição conforme necessário. Por exemplo, pode suspender, cancelar ou excluir qualquer assinatura (incluindo a assinatura interna de acesso total) para impedir o acesso à API.

Utilizar uma chave de subscrição

Os subscritores podem usar uma chave de subscrição de Gestão de API de duas formas:

• Adicione o cabeçalho HTTP Ocp-Apim-Subscription-Key à solicitação, passando o valor de uma chave de assinatura válida.
• Inclua o parâmetro de consulta subscription-key e um valor válido na URL. O parâmetro de consulta é verificado somente se o cabeçalho não estiver presente.

Sugestão

Ocp-Apim-Subscription-Key é o nome padrão do cabeçalho da chave de subscrição, e subscription-key é o nome padrão do parâmetro da consulta. Se desejar, você pode modificar esses nomes nas configurações de cada API. Por exemplo, no portal, atualize esses nomes na guia Configurações de uma API.

Nota

Quando incluída num cabeçalho de pedido ou parâmetro de consulta, a chave de subscrição é por defeito passada para o backend e pode ser exposta em registos de monitorização do backend ou noutros sistemas. Se estes dados forem sensíveis, pode configurar uma política no final da inbound secção para remover o cabeçalho da chave de subscrição (set-header) ou o parâmetro de consulta (set-query-parameter).

Use uma chave de subscrição no cabeçalho de Autorização

Para aceitar chaves de subscrição de clientes que enviam Authorization: Bearer <subscription-key>, defina properties.subscriptionKeyParameterNames.bearer para enabled na API. Os valores aceites são enabled e disabled; o padrão é disabled. Esta configuração aplica-se a cada API separadamente e não substitui o cabeçalho de chave de subscrição configurado ou o parâmetro de consulta configurado.

A API Management verifica primeiro o cabeçalho da chave de subscrição configurado, depois o parâmetro de consulta configurado, e depois o parâmetro de consulta legado key se o fallback legado estiver ativado. Verifica o valor bearer de Authorization apenas quando nenhuma dessas fontes fornece uma chave e o reconhecimento de bearer está ativado. Uma chave inválida de uma fonte de prioridade superior não faz com que a API Management tente novamente com o valor bearer.

O valor bearer é comparado com as chaves de subscrição da API Management. Ativar esta opção não realiza validação OAuth ou JWT. Use o cabeçalho de chave de subscrição configurado quando o cabeçalho de Autorização precisar de transportar um token de acesso separado.

Para um exemplo que fornece uma chave de subscrição através do argumento do api_key SDK OpenAI em Python, veja Chamar uma API de modelo unificado a partir de uma aplicação cliente.

Habilitar ou desabilitar o requisito de subscrição para acesso à API ou ao produto

Por padrão, quando criar uma API, é necessária uma chave de subscrição para aceder à API. Da mesma forma, quando você cria um produto, por padrão, uma chave de assinatura é necessária para acessar qualquer API adicionada ao produto. Em determinados cenários, um editor de API pode querer publicar um produto ou uma API específica para o público sem a exigência de assinaturas. Embora um editor possa optar por habilitar o acesso não seguro (anônimo) a determinadas APIs, recomenda-se configurar outro mecanismo para proteger o acesso do cliente.

Atenção

Tenha cuidado ao configurar um produto ou uma API que não exija subscrição. Esta configuração pode ser demasiado permissiva e tornar uma API mais vulnerável a certas ameaças de segurança da API.

Nota

Os produtos abertos têm a opção Exige subscrição desativada, o que significa que os utilizadores não precisam de subscrever. Por esta razão, os produtos abertos não aparecem na página de Produtos do portal de programadores.

Pode desativar o requisito de subscrição quando criar uma API ou produto, ou mais tarde.

Para desativar o requisito de subscrição utilizando o portal:

• Desativar requisito do produto - Na página de Definições do produto, desative Exige subscrição.
• Desativar o requisito para a API - Na página de Definições da API, desative a opção Subscrição necessária.

Depois que o requisito de assinatura for desativado, a API ou APIs selecionadas poderão ser acessadas sem uma chave de assinatura.

Como o API Management lida com solicitações com ou sem chaves de assinatura

Pedido à API com uma chave de subscrição

Quando a Gestão de API recebe um pedido à API de um cliente com uma chave de subscrição, processa o pedido de acordo com as seguintes regras:

1. Verifica se a chave é válida e associada a uma subscrição ativa, definida como:

   • Uma assinatura direcionada à API.
   • Uma assinatura limitada a um produto atribuído na API.
   • Uma assinatura com escopo para todas as APIs.
   • A subscrição com âmbito de serviço específico (integrada em todas as subscrições de acesso).

   Se a chave for válida para uma subscrição ativa num âmbito apropriado, a Gestão da API concede acesso. Aplica políticas consoante a configuração da definição da política nesse âmbito.

2. Se a chave não for válida mas existir um produto que inclui a API sem exigir subscrição (um produto aberto ), a Gestão da API ignora a chave e trata o pedido como um pedido de API sem chave de subscrição (ver a secção seguinte).

3. Caso contrário, a API Management nega o acesso (erro 401 de acesso negado).

Pedido de API sem uma chave de subscrição

Quando a Gestão de API recebe um pedido à API de um cliente sem uma chave de subscrição, processa o pedido de acordo com as seguintes regras:

1. Verifica a existência de um produto que inclui a API mas não exige subscrição (um produto aberto ). Se o produto aberto existir, a Gestão de APIs trata do pedido no contexto das APIs, políticas e regras de acesso configuradas para o produto aberto. Uma API pode ser associada, no máximo, a um produto aberto.
2. Se não for encontrado um produto aberto, incluindo a API, a Gestão da API verifica se a API requer uma subscrição. Se não for necessária subscrição, a Gestão de APIs trata do pedido no contexto dessa API e operação.
3. Se não for encontrado nenhum produto ou API configurado, a Gestão de APIs nega o acesso (erro 401 de acesso negado).

Quadro-resumo

A tabela a seguir resume como o gateway lida com solicitações de API com ou sem chaves de assinatura em diferentes cenários. A tabela indica configurações que poderiam potencialmente permitir o acesso anónimo e não intencional à API.

Todos os produtos atribuídos à API requerem subscrição	A API requer uma assinatura	Chamada de API com chave de assinatura	Chamada de API sem chave de assinatura	Cenários típicos
✔️	✔️	Acesso permitido: • Chave com âmbito de produto • Chave com escopo de API • Chave com escopo de todas as APIs • Chave com escopo de serviço Acesso negado: • Outra chave não associada ao produto ou à API aplicável	Acesso negado	Acesso protegido à API usando assinatura com escopo de produto ou escopo de API
✔️	❌	Acesso permitido: • Chave de escopo do produto • Chave com escopo de API • Chave com escopo de todas as APIs • Chave com escopo de serviço • Outra chave sem escopo para o produto ou API aplicável	Acesso permitido (contexto API)	• Acesso protegido à API com subscrição com âmbito de produto • Acesso anónimo à API. Se o acesso anônimo não for pretendido, configure políticas no nível da API para impor autenticação e autorização.
❌ 1	✔️	Acesso permitido: • Chave com âmbito de produto • Chave com escopo de API • Chave com escopo de todas as APIs • Chave com escopo de serviço Acesso negado: • Outra chave sem escopo para o produto ou API aplicável	Acesso permitido (contexto aberto do produto)	• Acesso protegido à API com subscrição com âmbito de API • Acesso anónimo à API. Se o acesso anónimo não for desejado, configure com políticas de produto para impor autenticação e autorização
❌ 1	❌	Acesso permitido: • Chave de escopo do produto • Chave com escopo de API • Chave com escopo de todas as APIs • Chave com escopo de serviço • Outra chave sem escopo para o produto ou API aplicável	Acesso permitido (contexto aberto do produto)	Acesso anónimo à API. Se o acesso anônimo não for pretendido, configure com políticas de produto para impor autenticação e autorização

¹ Existe um produto aberto associado à API.

Considerações

• O acesso à API no contexto de um produto é o mesmo, quer o produto seja publicado ou não. Despublicar o produto esconde-o do portal de programadores, mas não invalida as chaves de subscrição novas ou existentes.
• Se uma API não exigir autenticação de assinatura, qualquer solicitação de API que inclua uma chave de assinatura será tratada da mesma forma que uma solicitação sem uma chave de assinatura. A chave de subscrição é ignorada.
• "Contexto" de acesso à API significa as políticas e controles de acesso que são aplicados em um escopo específico (por exemplo, API ou produto).

Conteúdo relacionado

Obtenha mais informações sobre o Gerenciamento de API:

• Saiba como as políticas de API Management são aplicadas em diferentes escopos.
• Aprenda outros conceitos em API Management.
• Siga nossos tutoriais para saber mais sobre o Gerenciamento de API.
• Consulte a nossa página de FAQ para perguntas comuns.