Proteger uma API exigindo chaves de API

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

O que você vai aprender

Neste tutorial, você aprenderá a:

  • Criar um proxy de API que exija uma chave de API.
  • Adicionar um produto de API.
  • Adicionar um desenvolvedor e registrar um app.
  • Chamar a API com uma chave de API.

É importante proteger a API contra acesso não autorizado. Uma maneira de fazer isso é com chaves de API, também chamadas de chaves públicas, chaves do consumidor ou chaves de apps.

Quando um app faz uma solicitação à API, ele precisa fornecer uma chave válida. No ambiente de execução, a política "Verificar chave de API" confere se a chave de API fornecida:

  • É válido
  • Não foi revogada
  • Corresponde à chave de API para o produto de API que expõe os recursos solicitados

Se a chave for válida, a solicitação será permitida. Se a chave for inválida, a solicitação vai resultar em uma falha de autorização.

Neste tutorial, você criará um proxy de API que exige uma chave de API válida para acessá-lo.

Pré-requisitos

  • Uma conta do Apigee Edge. Se você ainda não tiver uma, inscreva-se seguindo as instruções em Como criar uma conta do Apigee Edge.
  • Um navegador da Web para fazer uma chamada de API.
  • Para a seção de crédito extra, não é necessário ter o cURL instalado na máquina para fazer chamadas de API a partir da linha de comando.

Criar o proxy de API

Sobre o "mocktarget"

O serviço mocktarget está hospedado na Apigee e retorna dados simples. Ele não requer nenhuma chave de API nem um token de acesso. Na verdade, você pode acessá-lo em um navegador da Web. Para testar, clique no seguinte:

http://mocktarget.apigee.net

O destino retorna Hello, Guest!. Use o recurso /help para acessar uma página de ajuda sobre outros recursos da API disponíveis.

  1. Acesse https://apigee.com/edge e faça login.
  2. Alterne para a organização desejada clicando no seu nome de usuário na parte superior da barra de navegação lateral para exibir o menu do perfil do usuário e selecionando a organização na lista.

    selecionar organização no menu do perfil do usuário
  3. Clique em Proxies de API na página de destino para exibir a lista de proxies de API.

    Menu das APIs do Edge
  4. Clique em + Proxy.
    Botão "Criar proxy"
  5. Na página Criar proxy, selecione Proxy reverso (mais comum).
  6. Na página Proxy Details, configure o proxy da seguinte maneira:
    Neste campo faça isso
    Nome do proxy Insira: helloworld_apikey
    Caminho base do projeto

    Altere para: /helloapikey

    O Caminho base do projeto faz parte do URL usado para fazer solicitações ao proxy de API.

    Observação: para ver as recomendações da Apigee sobre o controle de versões da API, consulte Controle de versões no e-book Design da API da Web: a parte ausente.

    Existing API

    Insira: http://mocktarget.apigee.net

    Isso define o URL de destino que o Apigee Edge invoca em uma solicitação ao proxy de API.

    Descrição Insira: hello world protected by API key
  7. Clique em Next.
  8. Na página Políticas comuns, em Segurança: autorização, selecione Chave de API e clique em Próxima. Isso adicionará duas políticas ao seu proxy de API.
  9. Na página Virtual Hosts, selecione default e secure, depois clique em Next. Selecionar default permite chamar a API com http://. Ao selecionar secure, você pode chamar a API com https://.
  10. Na página Resumo, verifique se o ambiente de implantação test está selecionado e clique em Criar e implantar.
  11. Você verá uma confirmação de que o novo proxy de API e um produto de API foram criados e que o proxy de API foi implantado no ambiente de teste.
  12. Clique em Editar proxy para exibir a página Visão geral do proxy de API.

Ver as políticas

  1. No editor de proxy da API, clique na guia Desenvolver. Você verá que duas políticas foram adicionadas ao fluxo de solicitação do proxy de API:
    • Verificar chave de API: verifica a chamada de API para garantir que uma chave de API válida esteja presente (enviada como um parâmetro de consulta).
    • Remover apikey do parâmetro de consulta:uma política AttributionMessage que remove a chave de API depois que ela é verificada, para que ela não seja transmitida e exposta desnecessariamente.
  2. Clique no ícone de política de verificação da chave de API na visualização de fluxo e confira a configuração XML da política na visualização de código inferior. O elemento <APIKey> informa à política onde ela precisa procurar a chave de API quando a chamada é feita. Por padrão, ele procura a chave como um parâmetro de consulta chamado apikey na solicitação HTTP:

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

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

Tentar chamar a API

Nesta etapa, você fará uma chamada de API bem-sucedida diretamente para o serviço de destino e, em seguida, fará uma chamada malsucedida ao proxy de API para ver como ele está sendo protegido pelas políticas.

  1. Sucesso

    Em um navegador da Web, acesse o endereço a seguir. Este é o serviço de destino para o qual o proxy de API está configurado para encaminhar a solicitação, mas você o abordará diretamente por enquanto:

    http://mocktarget.apigee.net
    

    Você receberá esta resposta bem-sucedida: Hello, Guest!

  2. Falha

    Agora tente chamar seu proxy de API:

    http://ORG_NAME-test.apigee.net/helloapikey
    

    substituindo ORG_NAME pelo nome da organização de Edge.

    Sem a política "Verificar chave de API", essa chamada daria a mesma resposta que a chamada anterior. Nesse caso, você 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 você não transmitiu uma chave de API válida (como um parâmetro de consulta).

Nas próximas etapas, você vai adicionar um produto de API.

Adicionar um produto de API.

Para adicionar um produto de API usando a IU da Apigee:

  1. Selecione Publicar > Produtos da API.
  2. Clique em +Produto da API.
  3. Insira os Detalhes do produto para seu produto de API.

    Campo Descrição
    Nome Nome interno do produto de API. Não especifique caracteres especiais no nome.
    Observação:não é possível editar o nome depois que o produto da API é criado. Por exemplo, helloworld_apikey-Product.
    Nome de exibição Nome de exibição do produto de API. O nome de exibição é usado na interface e pode ser editado a qualquer momento. Caso não seja especificado, o valor de "Nome" será usado. Esse campo é preenchido automaticamente com o valor "Nome". Você pode editar ou excluir o conteúdo dele. O nome de exibição pode incluir caracteres especiais. Por exemplo, helloworld_apikey-Product.
    Descrição Descrição do produto de API. Por exemplo, Test product for tutorial.
    Ambiente Ambientes em que o produto de API permitirá acesso. Por exemplo, test ou prod.
    Acesso Selecione Público.
    Aprovar automaticamente solicitações de acesso Ative a aprovação automática de solicitações de chave para este produto de API em qualquer app.
    Cota Ignorar para este tutorial.
    Escopos do OAuth permitidos Ignorar para este tutorial.
  4. Na seção de recursos da API, selecione o proxy de API que você acabou de criar. Por exemplo, helloworld_apikey.
  5. Clique em Adicionar.
  6. Na seção Caminhos, adicione o caminho "/".
  7. Clique em Adicionar.
  8. Clique em Salvar.

Nas próximas etapas, você receberá a chave de API necessária.

Adicionar um desenvolvedor e um app à organização

A seguir, vamos simular o fluxo de trabalho de um desenvolvedor que se inscreve para usar suas APIs. Um desenvolvedor tem um ou mais apps que chamam suas APIs, e cada um deles recebe uma chave de API exclusiva. Assim você, provedor de API, tem um controle mais granular sobre o acesso às suas APIs e relatórios mais detalhados sobre o tráfego da API por app.

Crie um desenvolvedor

Para criar um desenvolvedor:

  1. Selecione Publicar > Desenvolvedores no menu.
  2. Clique em + Desenvolvedor.
  3. Digite o seguinte na janela "New Developer":

    Neste campo digitar
    Nome Keyser
    Sobrenome Soze
    Username keyser
    E-mail keyser@example.com
  4. Clique em Criar.

Registrar um aplicativo

Para registrar um app de desenvolvedor:

  1. Selecione Publicar > Apps.
  2. Clique em + App.
  3. Digite o seguinte na janela New App:

    p
    Neste campo faça isso
    Nome e nome de exibição Insira: keyser_app
    Empresa / desenvolvedor Selecione: Developer
    Desenvolvedor Selecione: Keyser Soze (keyser@example.com)
    Callback URL e Observações Deixar em branco
  4. Na seção Credenciais, selecione Nunca no menu Validade. As credenciais deste aplicativo nunca expirarão.
  5. Em Produtos, clique em Adicionar produto.
  6. Selecione helloworld_apikey-Product.
  7. Clique em Adicionar.
  8. Clique em Criar acima e à direita da seção Detalhes do app para salvar seu trabalho.

Encontre a chave de API

Para acessar a chave de API, faça o seguinte:

  1. Na página Apps (Publicar > Apps), clique em keyser_app.
  2. Na página keyser_app, clique em Mostrar ao lado de Chave na seção Credenciais. Na seção Produto, observe que a chave está associada a gcr_apikey

  3. Selecione e copie a Chave. Ela será usada na próxima etapa.

Chamar a API com uma chave

Agora que você tem uma chave de API, pode usá-la para chamar o proxy de API. Digite o seguinte no navegador da Web: Substitua o nome da sua organização de Edge por ORG_NAME e a chave de API por API_KEY abaixo. Assegure-se de que não haja espaços extras no parâmetro de consulta.

http://ORG_NAME-test.apigee.net/helloapikey?apikey=API_KEY

Agora, ao chamar o proxy de API, você vai receber esta resposta: Hello, Guest!

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

Em geral, não é uma prática recomendada transmitir uma chave de API como um parâmetro de consulta. Considere transmiti-lo no cabeçalho HTTP.

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

Nesta etapa, você modificará o proxy para procurar a chave de API em um cabeçalho chamado x-apikey.

  1. Edite o proxy de API. Selecione Desenvolver > Proxies da API > gcr_apikey e vá para a visualização Desenvolver.
  2. Selecione a política Verificar chave de API e modifique o XML da política para que ela procure a header em vez do queryparam:

    <APIKey ref="request.header.x-apikey"/>
    
  3. Salve o proxy da API para implantar a alteração.
  4. Faça a chamada de API a seguir usando cURL para transmitir a chave de API como um cabeçalho chamado x-apikey. Não se esqueça de substituir o nome da sua organização.

    curl -v -H "x-apikey: API_KEY" http://ORG_NAME-test.apigee.net/helloapikey
    

Para concluir a alteração, você também precisaria configurar a política AttributionMessage para remover o cabeçalho em vez do parâmetro de consulta. Exemplo:

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

Temas relacionados

Veja alguns tópicos diretamente relacionados a este tutorial:

Indo mais fundo, proteger APIs com chaves de API é apenas uma parte da história. Muitas vezes, a proteção de APIs envolve mais segurança, como o OAuth.

O OAuth é um protocolo aberto que, em poucas palavras, troca credenciais (como nome de usuário e senha) por tokens de acesso. Os tokens de acesso são strings longas e aleatórias que podem ser transmitidas em torno de um pipeline de mensagens, mesmo de um app para outro, sem comprometer as credenciais originais. Os tokens de acesso geralmente têm vida útil curta, portanto, novos sempre são gerados.