Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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 é utilizada especificamente para fazer chamadas a APIs através do Gerenciamento de API, utilizando uma chave de assinatura. Não é o mesmo que uma assinatura do Azure.
O que são assinaturas?
Ao publicar APIs por meio do Gerenciamento de API, você pode 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 encaminhado 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. 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 interrupção mínima 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, defina properties.primaryKey e/ou properties.secondaryKey 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 por tempo às 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
Você pode associar assinaturas a vários escopos: produto, todas as APIs ou uma API individual.
Assinaturas para um produto
Tradicionalmente, você associa assinaturas no Gerenciamento de API a um único escopo de produto . Desenvolvedores:
- Localize a lista de produtos no portal do desenvolvedor.
- Envie solicitações de assinatura para os produtos que deseja usar.
- Acesse as APIs do produto usando as chaves das assinaturas que são aprovadas automaticamente ou pelos editores de API.
Atualmente, o portal do desenvolvedor mostra apenas as assinaturas de escopo do produto na seção Perfil do usuário.
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 de Gerenciamento de API vem com uma assinatura integrada de acesso total que concede acesso a todas as APIs. Esta assinatura com escopo de serviço facilita 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 API na instância de Gerenciamento de API. Somente usuários autorizados devem usar essa assinatura. 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 como vários desenvolvedores ou equipes compartilhando 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.
Observação
Você não pode atribuir assinaturas diretamente no Gerenciamento de API a grupos de segurança do Microsoft Entra ID. Para fornecer acesso à assinatura a vários usuários em um grupo, crie uma assinatura autônoma e distribua as chaves de assinatura aos membros do grupo ou integre-se à ID do Microsoft Entra para autenticação e use políticas para controlar o acesso à API com base na associação ao grupo.
Criar e gerenciar assinaturas no portal do Azure
Os editores de API (administradores ou desenvolvedores com permissões apropriadas) podem criar assinaturas diretamente no portal do Azure entrando em sua instância de Gerenciamento de API. Os consumidores de API não podem criar assinaturas por meio do portal do Azure; normalmente, eles solicitam assinaturas por meio do portal do desenvolvedor ou as recebem de editores de API.
Quando você cria uma assinatura no portal, ela 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
Os assinantes podem 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 desejado, 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 é, por padrão, passada para o back-end e pode ser exposta em logs de monitoramento de back-end ou em outros sistemas. Se esses dados forem confidenciais, você poderá configurar uma política no final da inbound seção 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 que você adicionar 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.
Atenção
Tenha cuidado ao configurar um produto ou uma API que não exija uma assinatura. Essa configuração pode ser muito permissiva e pode tornar 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 se inscrever neles. Por esse motivo, os produtos abertos não aparecem na página Produtos do portal do desenvolvedor.
Você pode desabilitar o requisito de assinatura ao criar uma API ou produto ou posterior.
Para desabilitar o requisito de assinatura usando o portal:
- Desabilitar o requisito para o produto – Na página Configurações do produto, desabilite a opção Requer 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:
Ele verifica se a chave é válida e associada a uma assinatura ativa, definida como:
- Uma assinatura com escopo definido para a API.
- Uma assinatura com escopo definido para um produto vinculado à API.
- Uma assinatura abrangendo todas as APIs.
- A assinatura com escopo de serviço (assinatura interna com acesso completo).
Se a chave for válida para uma assinatura ativa em um escopo apropriado, o Gerenciamento de API concederá acesso. Ele aplica políticas dependendo da configuração da definição de política nesse escopo.
Se a chave não for válida, mas existir um produto que inclua a API sem a necessidade de uma assinatura (um produto aberto ), o Gerenciamento de API ignorará a chave e manipulará a solicitação como uma solicitação de API sem uma chave de assinatura (consulte a seção a seguir).
Caso contrário, a Gestão de API nega acesso (erro de acesso negado 401).
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:
- Ele verifica a existência de um produto que inclui a API, mas não requer uma assinatura (um produto aberto ). Se o produto aberto existir, o Gerenciamento de API manipulará 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.
- Se um produto aberto, incluindo a API, não for encontrado, o Gerenciamento de API verificará se a API requer uma assinatura. Se uma assinatura não for necessária, o Gerenciamento de API manipulará a solicitação no contexto dessa API e operação.
- Se nenhum produto ou API configurado for encontrado, o Gerenciamento de API negará o acesso (erro 401 do Access 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. A tabela observa as configurações que poderiam potencialmente habilitar o acesso não intencional e anônimo à API.
| 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 com escopo de serviço Acesso negado: • Outra chave fora do escopo do produto ou da API aplicável |
Acesso negado | Acesso protegido à API usando assinatura com escopo de produto ou API |
| ✔️ | ❌ | Acesso permitido: • Chave no escopo do produto • Chave no escopo da API • Todas as chaves no escopo de APIs • Chave com escopo de 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 com escopo de 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 com escopo de 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. A não publicação do produto o oculta 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).
Conteúdo relacionado
Saiba mais sobre o Gerenciamento de API:
- Saiba como as políticas de Gerenciamento de API são aplicadas em escopos diferentes.
- Conheça outros conceitos no Gerenciamento de API.
- Siga nossos tutoriais para saber mais sobre o Gerenciamento de API.
- Verifique nossa página de perguntas Frequentes para perguntas comuns.