Subscrições na Gestão de API do Azure

APLICA-SE A: Todas as camadas de gerenciamento de API

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 assinatura de Gerenciamento de API é usada especificamente para chamar APIs por meio do Gerenciamento de API usando uma chave de assinatura. Não é o mesmo que uma assinatura do Azure.

O que são subscrições?

Ao publicar APIs através da Gestão de API, pode proteger o acesso a APIs facilmente com a utilização de 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:

• Rejeitadas imediatamente pelo gateway de Gestão de API.
• Não reencaminhadas 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 assinatura é um contêiner nomeado para um par de chaves de assinatura.

Além disso

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

Gorjeta

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

• OAuth2.0
• Certificados de cliente
• Restringir IPs do chamador

Gerir chaves de subscrição

A regeneração regular de chaves é uma precaução de segurança comum. Como a maioria dos serviços do Azure que exigem uma chave de assinatura, o Gerenciamento de API gera chaves em pares. Cada aplicativo que usa o serviço pode alternar da chave A para a chave B e regenerar a chave A com o mínimo de interrupção e vice-versa.

A definição de chaves específicas em vez de regenerar as pode ser executada invocando a Subscrição de Gestão da API do Azure - Criar ou Atualizar a API REST do Azure. Especificamente, o properties.primaryKey e/ou properties.secondaryKey precisa ser definido no corpo da solicitação 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. Você pode desenvolver fluxos de trabalho para automatizar esses processos usando ferramentas como o 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

As assinaturas podem ser associadas a vários escopos: produto, todas as APIs ou uma API individual.

Subscrições de um produto

Tradicionalmente, as assinaturas no Gerenciamento de API eram associadas a um único escopo de produto . Programadores:

• Encontrada a lista de produtos no portal do desenvolvedor.
• Enviaram pedidos de subscrição para os produtos que pretendiam utilizar.
• Use as chaves nessas assinaturas (aprovadas automaticamente ou pelos editores de API) para acessar todas as APIs no produto.

Atualmente, o portal do desenvolvedor mostra apenas as assinaturas do escopo do produto na seção Perfil de Usuário .

Assinaturas para todas as APIs ou uma API individual

Você também pode criar chaves que concedem acesso a:

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

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

Subscrição de acesso total

Cada instância de Gerenciamento de API vem com uma assinatura de acesso total integrada que concede acesso a todas as APIs. Essa assinatura com escopo de serviço torna simples para os proprietários de serviços testar e depurar APIs no console de teste.

Aviso

A assinatura de acesso total permite o acesso a todas as APIs na instância de Gerenciamento de API e só deve ser usada por usuários autorizados. 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. Esse recurso se mostra útil em cenários semelhantes a vários desenvolvedores ou equipes compartilhando uma assinatura.

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:

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

Criar e gerir subscrições no portal do Azure

Os editores de API podem criar assinaturas diretamente no portal do Azure.

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

Utilizar uma chave de subscrição

Um assinante pode usar uma chave de assinatura do Gerenciamento de API de duas maneiras:

• 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 de chave de assinatura e um valor válido na URL. O parâmetro de consulta é verificado somente se o cabeçalho não estiver presente.

Gorjeta

Ocp-Apim-Subscription-Key é o nome padrão do cabeçalho da chave de assinatura e subscription-key é o nome padrão do parâmetro de 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 em um cabeçalho de solicitação ou parâmetro de consulta, a chave de assinatura por padrão é passada para o back-end e pode ser exposta em logs de monitoramento de back-end ou outros sistemas. Se isso for considerado dados confidenciais, você poderá configurar uma política no final da seção para remover o cabeçalho da chave de inbound assinatura (set-header) ou o parâmetro de consulta (set-query-parameter).

Habilitar ou desabilitar o requisito de assinatura para acesso à API ou ao produto

Por padrão, quando você cria uma API, uma chave de assinatura é necessária para o acesso à 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 uma assinatura. Essa configuração pode ser excessivamente permissiva e pode tornar uma API mais vulnerável a determinadas ameaças à segurança da API.

Nota

Os produtos abertos têm a definição Requer subscrição desativada, o que significa que os utilizadores não precisam de subscrevê-la. Por esse motivo, os produtos abertos não são exibidos na página Produtos do portal do desenvolvedor.

Você pode desativar o requisito de assinatura no momento em que criar uma API ou produto, ou em uma data posterior.

Para desativar o requisito de assinatura usando o portal:

• Desativar requisito para o produto - Na página Configurações do produto, desative Requer assinatura
• Desativar requisito para API - Na página Configurações da API, desative Assinatura 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 Gerenciamento de API 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 está associada a uma subscrição ativa:

   • Uma subscrição no âmbito da API
   • Uma subscrição no âmbito de um produto atribuído à API
   • Uma subscrição no âmbito de todas as APIs
   • A subscrição no âmbito do serviço (subscrição de acesso total incorporada)

   Se for fornecida uma chave válida para uma subscrição ativa num âmbito adequado, o acesso é permitido. São aplicadas políticas consoante a configuração da definição de políticas nesse âmbito.

2. Caso contrário, o acesso é negado (erro 401 de acesso negado).

Pedido à 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. Verifique primeiro a existência de um produto que inclua a API, mas não exija uma assinatura (um produto aberto ). Se o produto aberto existir, processa o pedido no contexto das APIs, políticas e regras de acesso configuradas para o produto. Uma API pode ser associada, no máximo, a um produto aberto.
2. Se não for encontrado um produto aberto que inclua a API, verifica se a API necessita de uma subscrição. Se não for necessária uma subscrição, processa o pedido no contexto dessa API e operação.
3. Se não for encontrado uma API ou produto configurado, o acesso é negado (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. As configurações que podem potencialmente habilitar o acesso anônimo e não intencional à API são observadas.

Todos os produtos atribuídos à API requerem subscrição	API requer assinatura	Chamada de API com chave de assinatura	Chamada de API sem chave de assinatura	Cenários típicos
✔️	✔️	Acesso permitido: • Chave de escopo do produto • Chave com escopo de API • Todas as chaves com escopo de API • Chave com escopo de serviço Acesso negado: • Outra chave sem escopo para o 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 • Todas as chaves com escopo de API • Chave com escopo de serviço Acesso negado: • Outra chave sem escopo para o produto ou API aplicável	Acesso permitido (contexto API)	• Acesso protegido à API com subscrição orientada para o âmbito do 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 de escopo do produto • Chave com escopo de API • Todas as chaves com escopo de API • 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 pretendido, 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 • Todas as chaves com escopo de API • 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 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

1 Existe um produto aberto associado à API.

Considerações

• O acesso à API em um contexto de produto é o mesmo, quer o produto seja publicado ou não. Cancelar a publicação do produto o oculta do portal do desenvolvedor, mas não invalida chaves de assinatura novas ou existentes.
• Mesmo que um produto ou API não exija uma assinatura, uma chave válida de uma assinatura ativa que permita o acesso ao produto ou à API ainda pode ser usada.
• "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).

Próximos passos

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

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