APIs seguras usando assinaturas
Quando você publica APIs por meio do Gerenciamento de APIs, é fácil e comum 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 quando fizerem chamadas para essas APIs. Caso contrário, as chamadas serão rejeitadas imediatamente pelo gateway de Gerenciamento de API. Eles não são encaminhados para os serviços de back-end.
Para obter uma chave de assinatura para acessar APIs, é necessária uma assinatura. Uma assinatura é essencialmente um contêiner nomeado para um par de chaves de assinatura. Os desenvolvedores que precisam consumir as APIs publicadas podem obter assinaturas. E eles não precisam da aprovação dos editores de API. Os editores de API também podem criar assinaturas diretamente para consumidores de API.
Nota
O Gerenciamento de API também oferece suporte a outros mecanismos para proteger o acesso a APIs, incluindo: OAuth2.0, certificados de cliente e listagem de permissões de IP.
Subscrições e Chaves
Uma chave de subscrição é uma chave autogerada que pode ser transmitida através dos cabeçalhos do pedido do cliente ou como um parâmetro de cadeia de consulta. A chave está diretamente relacionada com uma subscrição, que estão no âmbito de áreas diferentes. As subscrições concedem-lhe controlo granular sobre as permissões e as políticas.
Os três principais âmbitos de subscrição são os seguintes:
| Âmbito | Detalhes |
|---|---|
| Todas as APIs | Aplicam-se a todas as APIs acessíveis a partir do gateway |
| Única API | Este âmbito aplica-se a uma única API importada e a todos os respetivos pontos finais |
| Produto | Um produto é uma coleção de uma ou mais APIs que configura na Gestão de API. Pode atribuir APIs a mais do que um produto. Os produtos podem ter diferentes regras de acesso, quotas de utilização e termos de utilização. |
As aplicações que chamam uma API protegida têm de incluir a chave em todos os pedidos.
Pode voltar a gerar essas chaves de subscrição em qualquer altura se, por exemplo, suspeitar que uma chave foi partilhada com utilizadores não autorizados.
Cada subscrição tem duas chaves: uma primária e uma secundária. Ter duas chaves facilita a tarefa de voltar a gerar uma chave, quando necessário. Por exemplo, se quiser alterar a chave primária e evitar períodos de indisponibilidade, utilize a chave secundária nas suas aplicações.
No caso de produtos para os quais são ativadas subscrições, os clientes têm de fornecer uma chave ao efetuar chamadas para APIs nesse produto. Os programadores podem obter uma chave ao enviar um pedido de subscrição. Se aprovar o pedido, tem de enviar a chave de subscrição de forma segura, por exemplo, numa mensagem encriptada. Este passo é uma parte importante do fluxo de trabalho da Gestão de API.
Chamar uma API com a chave de subscrição
As aplicações têm de incluir uma chave válida em todos os pedidos HTTP ao efetuarem chamadas para pontos finais da API protegidos por uma subscrição. As chaves podem ser transmitidas no cabeçalho do pedido ou sob a forma de uma cadeia de consulta no URL.
O nome do cabeçalho predefinido é Ocp-Apim-Subscription-Key e a cadeia de consulta predefinida é subscription-key.
Para testar as chamadas à API, pode utilizar o portal do programador ou ferramentas de linha de comando, como o curl. Eis um exemplo de um pedido GET no portal do programador, que mostra o cabeçalho da chave de subscrição:
Eis como pode transmitir uma chave no cabeçalho do pedido com o curl:
curl --header "Ocp-Apim-Subscription-Key: <key string>" https://<apim gateway>.azure-api.net/api/path
Eis um comando curl de exemplo que transmite uma chave no URL sob a forma de 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 sob a forma de uma cadeia de consulta no URL, obterá a resposta 401 Acesso Negado do gateway de API.