Proteger APIs usando assinaturas
Quando você publica APIs por meio do Gerenciamento de API, é fácil e normal proteger o acesso a essas APIs 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 para essas APIs. O gateway de Gerenciamento de API rejeita chamadas sem uma chave de assinatura, as quais não são encaminhadas para os serviços de back-end.
É necessária uma assinatura para obter uma chave de assinatura para acessar APIs. A assinatura é essencialmente um contêiner nomeado para um par de chaves de assinatura. Os desenvolvedores que precisam consumir as APIs publicadas podem obter as assinaturas. E eles não precisam da aprovação dos editores das APIs. Os editores de API também podem criar assinaturas diretamente para os consumidores da API.
Observação
O Gerenciamento de API também dá suporte a outros mecanismos para proteger o acesso a APIs, incluindo: OAuth 2.0, certificados de cliente e listagem de permissão de IP.
Assinaturas e chaves
Uma chave de assinatura é uma chave exclusiva gerada automaticamente que pode ser passada por meio dos cabeçalhos da solicitação do cliente ou como um parâmetro de cadeia de consulta. A chave está diretamente relacionada a uma assinatura, que pode ter um escopo definido para diferentes áreas. As assinaturas oferecem um controle granular sobre permissões e políticas.
Os três escopos de assinatura principais são:
| Escopo | Detalhes |
|---|---|
| Todas as APIs | Aplica-se a todas as APIs acessíveis por meio do gateway |
| Única API | Esse escopo aplica-se a uma única API importada e a todos os seus pontos de extremidade |
| Produto | Um produto é uma coleção de uma ou mais APIs que você configura no Gerenciamento de API. Você pode atribuir APIs a mais de um produto. Os produtos podem ter diferentes regras de acesso, cotas de uso e termos de uso. |
Os aplicativos que chamam uma API protegida precisam incluir a chave em cada solicitação.
Você poderá regenerar essas chaves de assinatura a qualquer momento, por exemplo, se suspeitar que uma chave foi compartilhada com usuários não autorizados.
Toda assinatura tem duas chaves, uma primária e uma secundária. Ter duas chaves facilita regenerar uma chave. Por exemplo, caso deseje alterar a chave primária e evitar o tempo de inatividade, use a chave secundária em seus aplicativos.
Para os produtos em que as assinaturas estão habilitadas, os clientes precisarão fornecer uma chave ao fazer chamadas às APIs nesse produto. Os desenvolvedores podem obter uma chave enviando uma solicitação de assinatura. Se você aprovar a solicitação, precisará enviar a chave de assinatura com segurança, por exemplo, em uma mensagem criptografada. Essa etapa é uma parte importante do fluxo de trabalho do Gerenciamento de API.
Chamar uma API com a chave de assinatura
Os aplicativos precisam incluir uma chave válida em todas as solicitações HTTP ao fazer chamadas para pontos de extremidade de API protegidos por uma assinatura. As chaves podem ser passadas no cabeçalho da solicitação ou como uma cadeia de consulta na URL.
O nome de cabeçalho padrão é Ocp-Apim-Subscription-Key e a cadeia de consulta padrão é subscription-key.
Para testar as chamadas à API, use o portal do desenvolvedor ou ferramentas de linha de comando, como o cURL. Este é um exemplo de uma solicitação GET usando o portal do desenvolvedor, que mostra o cabeçalho da chave de assinatura:
Veja como você pode passar uma chave no cabeçalho de solicitação usando curl:
curl --header "Ocp-Apim-Subscription-Key: <key string>" https://<apim gateway>.azure-api.net/api/path
Veja um exemplo de comando curl que passa uma chave na URL como uma cadeia de consulta:
curl https://<apim gateway>.azure-api.net/api/path?subscription-key=<key string>
Se a chave não for transmitida no cabeçalho ou como uma cadeia de consulta na URL, você receberá uma resposta 401 Acesso Negado do gateway de API.