Proteja uma API exigindo chaves da API

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Vídeo: veja este breve vídeo para uma introdução sobre como proteger a sua API.

O que vai aprender

Este tutorial explica como:

  • Crie um proxy de API que exija uma chave da API.
  • Crie um produto API, um programador e uma app de programador.
  • Chame a API com uma chave da API.

É importante proteger a sua API contra acesso não autorizado. Uma forma de o fazer é com chaves da API.

Quando uma app faz um pedido a um proxy de API configurado para validar uma chave da API, a app tem de fornecer uma chave válida. Em tempo de execução, a política de chaves da API de verificação verifica se a chave da API fornecida:

  • É válido
  • Não foi revogada
  • Corresponde à chave da API do produto da API que expõe os recursos pedidos

Se a chave for válida, o pedido é permitido. Se a chave for inválida, o pedido resulta numa falha de autorização.

Crie o proxy de API

  1. Aceda à IU do Apigee e inicie sessão.
  2. Selecione a sua organização através do menu pendente no canto superior esquerdo da IU.

  3. Clique em Desenvolver > Proxies de API para apresentar a lista de proxies de API.

  4. Clique em Criar novo.
    Botão Criar proxy
  5. No assistente Criar um proxy, selecione Proxy inverso (mais comum).
  6. Configure o proxy da seguinte forma:
    Neste campo faça o seguinte
    Nome do proxy Introduza: helloworld_apikey
    Caminho base do projeto

    Alterar para: /helloapikey

    O caminho base do projeto faz parte do URL usado para fazer pedidos ao proxy da API.
    Descrição Introduza: hello world protected by API key
    Destino (API existente)

    Introduza: http://mocktarget.apigee.net

    Isto define o URL de destino que o Apigee invoca num pedido ao proxy da API. Este destino devolve apenas uma resposta simples: Hello, Guest!.
  7. Clicar em Seguinte.
  8. Na página Políticas comuns, selecione Chave da API. Esta opção adiciona automaticamente duas políticas ao seu proxy de API e cria um produto de API necessário para gerar a chave da API.
  9. Clicar em Seguinte.
  10. Na página Resumo, certifique-se de que selecionou um ambiente de implementação e clique em Criar e implementar.
  11. Clique em Editar proxy para apresentar a página Descrição geral do proxy de API.

Veja as políticas

  1. No editor de proxy de API, clique no separador Desenvolver. Vai ver que foram adicionadas duas políticas ao fluxo de pedidos do proxy de API:
    • Validar chave da API: verifica a chamada API para garantir que está presente uma chave da API válida (enviada como um parâmetro de consulta).
    • Remover parâmetro de consulta apikey: uma política de atribuição de mensagens que remove a chave de API depois de ser verificada, para que não seja transmitida e exposta desnecessariamente.

  2. Clique no ícone da política de verificação da chave da API na vista de fluxo e consulte a configuração XML da política na vista de código inferior. O elemento <APIKey> indica à política onde deve procurar a chave da API quando a chamada é feita. Por predefinição, procura a chave como um parâmetro de consulta denominado apikey no pedido HTTP:

    <APIKey ref="request.queryparam.apikey" />

    O nome apikey é arbitrário e pode ser qualquer propriedade que contenha a chave da API.

Tente chamar a API

Neste passo, vai fazer uma chamada API bem-sucedida diretamente para o serviço de destino e, em seguida, vai fazer uma chamada sem êxito para o proxy API para ver como está a ser protegido pelas políticas.

  1. Êxito

    Num navegador de Internet, aceda ao seguinte endereço. Este é o serviço de destino para o qual o proxy da API está configurado para encaminhar o pedido, mas vai aceder diretamente a ele por agora:

    http://mocktarget.apigee.net

    Deve receber esta resposta com êxito: Hello, Guest!

  2. Falha

    Agora, experimente chamar o proxy da API:

    curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey

    onde YOUR ENV_GROUP_HOSTNAME é o nome do anfitrião do grupo de ambientes. Consulte Encontre o nome de anfitrião do grupo de ambientes.

    Sem a política da chave da API Verify, esta chamada daria a mesma resposta que a chamada anterior. No entanto, neste caso, deve receber a seguinte resposta de erro:

    {"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

    o que significa, corretamente, que não transmitiu uma chave da API válida (como um parâmetro de consulta).

Nos passos seguintes, vai receber a chave da API necessária.

Adicionar um produto API

Para adicionar um produto de API através da IU do Apigee:

  1. Selecione Publicar > Produtos API.
  2. Clique em +Criar.
  3. Introduza os detalhes do produto da API.
    Campo Descrição
    Nome Nome interno do produto API. Não especifique carateres especiais no nome.
    Nota: não pode editar o nome depois de criar o produto API.
    Nome a apresentar Nome a apresentar do produto API. O nome a apresentar é usado na IU e pode editá-lo em qualquer altura. Se não for especificado, é usado o valor do nome. Este campo é preenchido automaticamente com o valor Nome. Pode editar ou eliminar o respetivo conteúdo. O nome a apresentar pode incluir carateres especiais.
    Descrição Descrição do produto API.
    Ambiente Ambientes aos quais o produto API vai permitir o acesso. Por exemplo, test ou prod.
    Acesso Selecione Público.
    Aprovar automaticamente pedidos de acesso Ativar a aprovação automática de pedidos de chaves para este produto de API a partir de qualquer app.
    Quota Ignore para este tutorial.
    Âmbitos do OAuth permitidos Ignore para este tutorial.
  4. Na secção Operações, clique em ADICIONAR UMA OPERAÇÃO.
  5. No campo Proxy de API, selecione o proxy de API que acabou de criar.
  6. No campo Caminho, introduza "/". Ignore os outros campos.
  7. Clique em Guardar para guardar a operação.
  8. Clique em Guardar para guardar o produto API.

Adicione um programador e uma app à sua organização

Em seguida, vamos simular o fluxo de trabalho de um programador que se inscreve para usar as suas APIs. Um programador tem uma ou mais apps que chamam as suas APIs, e cada app recebe uma chave da API única. Isto dá-lhe, ao fornecedor de APIs, um controlo mais detalhado sobre o acesso às suas APIs e relatórios mais detalhados sobre o tráfego de APIs por app.

Crie um programador

Para criar um programador:

  1. Selecione Publicar > Programadores no menu.
    Nota: se ainda estiver no ecrã Desenvolver, clique em "<" junto a DESENVOLVER para apresentar o menu e selecione Publicar > Programadores
  2. Clique em + Programador.
  3. Introduza o seguinte na janela Novo programador:
    Neste campo enter
    Nome próprio Keyser
    Apelido Soze
    Nome de utilizador keyser
    Email keyser@example.com
  4. Clique em Criar.

Registe uma app

Para registar uma app de programador:

  1. Selecione Publicar > Apps.
  2. Clique em + App.
  3. Introduza o seguinte na janela Nova app de programador:
    Neste campo faça o seguinte
    Nome e Nome a apresentar Introduza: keyser_app
    Programador Selecionar: Keyser Soze (keyser@example.com)
    URL de retorno e Notas Deixe em branco
  4. Na secção Credenciais, selecione Nunca. As credenciais desta app nunca expiram.
  5. Clique em Adicionar produto.
  6. Selecione o produto que acabou de criar.
  7. Clique em Criar.

Obtenha a chave da API

Para obter a chave da API:

  1. Na página Apps (Publicar > Apps), clique em keyser_app.
  2. Na página keyser_app, clique em Mostrar junto a Chave na secção Credenciais. Repare que a chave está associada ao produto que criou.
  3. Selecione e copie a chave. Vai usá-lo no passo seguinte.

Chame a API com uma chave

Agora que tem uma chave da API, pode usá-la para chamar o proxy da API. Cole a chave da API conforme mostrado, como um parâmetro de consulta. Certifique-se de que não existem espaços adicionais no parâmetro de consulta.

curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey?apikey=your_api_key

Agora, quando chamar o proxy da API, deve receber esta resposta: Hello, Guest!

Parabéns! Criou um proxy de API e protegeu-o exigindo que uma chave da API válida seja incluída na chamada.

Tenha em atenção que, em geral, não é uma boa prática transmitir uma chave da API como um parâmetro de consulta. Em alternativa, deve considerar transmiti-lo no cabeçalho HTTP.

Prática recomendada: transmitir a chave no cabeçalho HTTP

Neste passo, vai modificar o proxy para procurar a chave API num cabeçalho denominado x-apikey.

  1. Edite o proxy da API. Selecione Develop > API Proxies > helloworld_apikey e aceda à vista Develop.

  2. Selecione a política Verificar chave da API e modifique o XML da política para indicar à política que procure no header em vez de no queryparam:

    <APIKey ref="request.header.x-apikey"/>
  3. Guarde o proxy da API e use Implementar para o implementar.

  4. Faça a seguinte chamada da API usando cURL para transmitir a chave da API como um cabeçalho denominado x-apikey. Não se esqueça de substituir o nome da sua organização.

    curl -v -H "x-apikey: {api_key_goes_here}" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey

Tenha em atenção que, para concluir totalmente a alteração, também tem de configurar a política Assign Message para remover o cabeçalho em vez do parâmetro de consulta. Por exemplo:

<Remove>
  <Headers>
      <Header name="x-apikey"/>
  </Headers>
</Remove>

Tópicos relacionados

Seguem-se alguns tópicos relacionados com produtos e chaves de API:

A proteção de APIs envolve frequentemente segurança adicional, como o OAuth, um protocolo aberto que troca credenciais (como o nome de utilizador e a palavra-passe) por tokens de acesso. Os tokens de acesso são strings longas e aleatórias que podem ser transmitidas através de um pipeline de mensagens, incluindo de app para app, sem comprometer as credenciais originais.

Para uma vista geral dos tópicos relacionados com a segurança, consulte o artigo Proteger um proxy.