Assinaturas no Gerenciamento de API do Azure

  • Artigo

APLICA-SE A: todas as camadas do Gerenciamento de API

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

Observação

Uma assinatura de Gerenciamento de API é usada especificamente para chamar APIs através do Gerenciamento de API usando uma chave de inscrição. Não é o mesmo que uma assinatura do Azure.

O que são assinaturas?

Ao publicar APIs com o Gerenciamento de API, você poderá proteger facilmente o acesso à API usando chaves de assinatura. Os desenvolvedores que precisam consumir as APIs publicadas devem incluir uma chave de assinatura válida em solicitações HTTP ao fazer chamadas a essas APIs. Sem uma chave de assinatura válida, as chamadas:

  • Serão imediatamente rejeitadas pelo gateway de Gerenciamento de API.
  • Não serão encaminhadas para os serviços de back-end.

Para acessar APIs, os desenvolvedores precisarão de uma assinatura e uma chave de assinatura. Uma assinatura é um contêiner nomeado para um par de chaves de assinatura.

Além disso,

  • Os desenvolvedores podem obter assinaturas sem a necessidade de aprovação dos publicadores de API.
  • Os publicadores de API também podem criar assinaturas diretamente para os consumidores da API.

Dica

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

Gerenciar chaves de assinatura

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

A definição de chaves específicas em vez da regeneração de chaves pode ser executada invocando o comando Assinatura do Gerenciamento de API do Azure - Criar ou atualizar a API REST do Azure. Especificamente, properties.primaryKey e/ou properties.secondaryKey precisam ser definidos no corpo da solicitação HTTP.

Observação

  • 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 o acesso limitado a APIs, os editores de API podem usar políticas com chaves de assinatura ou usar um mecanismo que fornece expiração interna, como autenticação baseada em token.

Escopo das assinaturas

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

Assinaturas para um produto

Tradicionalmente, as assinaturas no Gerenciamento de API eram associadas a apenas um escopo de produto. Desenvolvedores:

  • Encontram a lista de produtos no portal do desenvolvedor.
  • Enviam solicitações de assinatura para os produtos que desejam usar.
  • Usam as chaves nessas assinaturas (aprovadas automaticamente ou por publicadores de API) para acessar todas as APIs no produto.

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

Assinaturas de produto

Assinaturas para todas as APIs ou uma API individual

Você pode criar chaves que permitem acesso a um dos seguintes:

  • Apenas uma API, ou
  • Todas as APIs em uma instância do Gerenciamento de API.

Nesses casos, não há o pré-requisito de criar um produto e adicionar APIs a ele.

Assinatura de acesso total

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

Aviso

A assinatura de todos os acessos permite o acesso a todas as API na instância de Gerenciamento de API e só deve ser usada por usuários autorizados. Nunca use essa assinatura para acesso rotineiro à API ou insira a chave de assinatura de todos os acessos em aplicativos cliente.

Observação

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

Assinaturas 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 é útil em cenários semelhantes em que vários desenvolvedores ou equipes compartilham uma assinatura.

Criar uma assinatura sem atribuir um proprietário faz com ela seja uma assinatura autônoma. Para conceder acesso à chave de assinatura autônoma aos desenvolvedores e ao restante da sua equipe:

  • Compartilhe manualmente a chave de assinatura.
  • Use um sistema personalizado para disponibilizar a chave de assinatura à sua equipe.

Criar e gerenciar assinaturas no portal do Azure

Os publicadores 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 interna de acesso total) para impedir o acesso à API.

Use uma chave de assinatura

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

Dica

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.

Observação

Quando incluída em um cabeçalho de solicitação ou parâmetro de consulta, a chave de assinatura é passada por padrão para o back-end e pode ser exposta em logs de monitoramento de back-end ou em outros sistemas. Se esses forem considerados dados confidenciais, você poderá configurar uma política no final da seção inbound para remover o cabeçalho da chave de 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 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 o requisito de assinaturas. Embora um editor possa permitir o acesso não seguro (anônimo) a determinadas APIs, é recomendável configurar outro mecanismo para proteger o acesso do cliente.

Cuidado

Tenha cuidado ao configurar um produto ou uma API que não exija uma assinatura. Essa configuração pode ser excessivamente permissiva e deixar uma API mais vulnerável a determinadas ameaças à segurança da API.

Observação

Os produtos abertos têm a configuração Requer assinatura desabilitada, o que significa que os usuários não precisam assinar. Por esse motivo, os produtos abertos não são exibidos na página Produtos do portal do desenvolvedor.

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

Para desabilitar o requisito de assinatura usando o portal:

  • Desabilitar requisito para produto – Na página Configurações do produto, desabilite Exigir assinatura
  • Desabilitar requisito para API – Na página Configurações da API, desabilite Exigir assinatura.

Depois que o requisito de assinatura for desabilitado, a API ou as APIs selecionadas podem ser acessadas sem uma chave de assinatura.

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

Solicitação de API com uma chave de assinatura

Quando o Gerenciamento de API recebe uma solicitação de API de um cliente com uma chave de assinatura, ele trata a solicitação de acordo com estas regras:

  1. Verifica primeiro se ela é uma chave válida associada a uma assinatura ativa:

    • Uma assinatura com escopo para a API
    • Uma assinatura com escopo para um produto atribuído à API
    • Uma assinatura com escopo para todas as APIs
    • A assinatura no escopo do serviço (assinatura de todo acesso interno)

    Se uma chave válida para uma assinatura ativa em um escopo apropriado for fornecida, o acesso será permitido. As políticas são aplicadas dependendo da configuração da definição de política nesse escopo.

  2. Se a chave não for válida, mas existir um produto que inclua a API, mas não exigir uma assinatura (um produto aberto), ignore a chave e manipule como uma solicitação de API sem uma chave de assinatura (veja abaixo).

  3. Caso contrário, o acesso será negado (401 Erro de acesso negado).

Solicitação de API sem uma chave de assinatura

Quando o Gerenciamento de API recebe uma solicitação de API de um cliente sem uma chave de assinatura, ele manipula a solicitação de acordo com estas regras:

  1. Verifique primeiro a existência de um produto que inclui a API, mas não requer uma assinatura (um produto aberto). Se o produto aberto existir, manipule a solicitação no contexto das APIs, políticas e regras de acesso configuradas para o produto aberto. Uma API pode ser associada a, no máximo, um produto aberto.
  2. Se nenhum produto aberto, incluindo a API, não for encontrado, verifique se a API exige uma assinatura. Se uma assinatura não for necessária, manipule a solicitação no contexto dessa API e operação.
  3. Se nenhuma API ou produto configurado for encontrado, o acesso será negado (401 Erro de acesso negado).

Tabela de resumo

A tabela a seguir resume como o gateway trata as solicitações de API com ou sem chaves de assinatura em cenários diferentes. As configurações que podem potencialmente habilitar o acesso anônimo e não intencional à API estão indicadas.

Todos os produtos atribuídos à API exigem assinatura API exige assinatura Chamada à API com chave de assinatura Chamada à API sem chave de assinatura Cenários comuns
✔️ ✔️ Acesso permitido:

• Chave no escopo do produto
• Chave no escopo da API
• Todas as chaves no escopo de APIs
• Chave no escopo do serviço

Acesso negado:

• Outra chave fora do escopo do produto ou da API aplicável		 Acesso negado Acesso protegido à API usando a assinatura no escopo do produto ou no escopo da API
✔️ ❌ Acesso permitido:

• Chave no escopo do produto
• Chave no escopo da API
• Todas as chaves no escopo de APIs
• Chave no escopo do serviço
• Outra chave fora do escopo do produto ou da API aplicável		 Acesso permitido (contexto de API) • Acesso protegido à API com assinatura no escopo de produto

• Acesso anônimo à API. Se o acesso anônimo não for a intenção, configure as políticas no nível da API para impor a autenticação e a autorização.
❌1 ✔️ Acesso permitido:

• Chave no escopo do produto
• Chave no escopo da API
• Todas as chaves no escopo de APIs
• Chave no escopo do serviço

Acesso negado:

• Outra chave fora do escopo do produto ou da API aplicável		 Acesso permitido (contexto de produto aberto) • Acesso protegido à API com assinatura no escopo da API

• Acesso anônimo à API. Se o acesso anônimo não for a intenção, configure com as políticas de produto para impor a autenticação e a autorização
❌1 ❌ Acesso permitido:

• Chave no escopo do produto
• Chave no escopo da API
• Todas as chaves no escopo de APIs
• Chave no escopo do serviço
• Outra chave fora do escopo do produto ou da API aplicável		 Acesso permitido (contexto de produto aberto) Acesso anônimo à API. Se o acesso anônimo não for a intenção, configure com as políticas de produto para impor a autenticação e a autorização

1 Existe um produto aberto associado à API.

Considerações

  • O acesso à API em um contexto de produto é o mesmo, independentemente de o produto ser publicado ou não. Cancelar a publicação do produto faz com que ele seja ocultado no portal do desenvolvedor, mas não invalida chaves de assinatura 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 assinatura é ignorada.
  • O "contexto" de acesso à API significa as políticas e os controles de acesso aplicados em um escopo específico (por exemplo, API ou produto).

Próximas etapas

Saiba mais sobre o Gerenciamento de API: