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.

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:

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

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.

Â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 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 interna 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.

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:

• 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 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 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

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

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.

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

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