Proteger uma API exigindo chaves de API

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Observação:este vídeo foi gravado com uma versão anterior da interface da Apigee. No entanto, os conceitos ainda são válidos.

Vídeo: confira este vídeo curto para ver como proteger sua API.

O que você aprenderá

Neste tutorial, explicamos como:

• Criar um proxy de API que exija uma chave de API.
• Criar um produto de API, um desenvolvedor e um aplicativo de desenvolvedor.
• 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.

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

• É válido
• Não foi revogada
• Corresponde à chave de API do 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 resultará em uma falha de autorização.

Observação:para concluir este tutorial, você vai criar e implantar um proxy que usa políticas extensíveis em vez de políticas padrão.

Criar o proxy de API

Apigee no console do Cloud

1. No console do Google Cloud , acesse a página Desenvolvimento de proxy > Proxies de API.

   Acessar proxies de API

2. Selecione sua organização no seletor de projetos no painel do Google Cloud. O nome da organização é o mesmo que o nome do projeto do Google Cloud.
3. Clique em + Criar.
4. No painel Criar um proxy, em Modelo de proxy, selecione Proxy reverso (mais comum). Um proxy reverso encaminha o tráfego de entrada para um serviço de back-end.
5. Configure o proxy da seguinte maneira:
   

   Nome	Valor
   Proxy Name	helloworld_apikey
   Base Path	/helloapikey O caminho base do projeto faz parte do URL usado para fazer solicitações ao proxy de API.
   Descrição	hello world protected by API key
   Destino (API existente)	http://mocktarget.apigee.net Isso define o URL de destino que a Apigee invoca em uma solicitação ao proxy de API. Esse destino retorna apenas uma resposta simples: Hello, Guest!.

6. Clique em Próxima.
7. Implantar (opcional). Deixe esses campos em branco.
8. Clique em Criar.
9. A Apigee cria o novo proxy e mostra o resumo dos detalhes no painel Resumo do proxy.

IU clássica

1. Acesse a IU da Apigee e faça login.
2. Selecione a organização usando o menu suspenso no canto superior esquerdo da UI.

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

4. Clique em Criar nova.
   
5. No assistente de criação de proxy, selecione Proxy reverso (mais comum).
6. 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 da API.
   Descrição	Insira: hello world protected by API key
   Destino (API existente)	Insira: http://mocktarget.apigee.net Isso define o URL de destino que a Apigee invoca em uma solicitação ao proxy de API. Esse destino retorna apenas uma resposta simples: Hello, Guest!.

7. Clique em Próxima.
8. Na página Políticas comuns, selecione Chave de API. Esta opção adiciona automaticamente duas políticas ao proxy de API e cria um produto de API necessário para gerar a chave de API.
9. Clique em Próxima.
10. Na página "Resumo", verifique se o ambiente de implantação está selecionado e clique em Criar e implantar.
11. Clique em Editar proxy para exibir a página Visão geral do proxy de API.

Ver as políticas

Apigee no console do Cloud

1. No painel Resumo do proxy do proxy helloworld_apikey, clique na guia Desenvolver.
2. No menu Políticas, clique em Adicionar política.
3. No painel Criar política, em Segurança, selecione Verificar chave de API.
4. No painel Verificar chave de API, preencha os campos obrigatórios nas seções Nome e Nome de exibição usando os seguintes valores:
   • Nome: insira um nome para a política. Por exemplo, VerifyAPIKey.
   • Nome de exibição: insira o nome da política para uso na interface. Por exemplo, Verify API Key.
5. Clique em Criar.
6. Clique em para adicionar outra política.
7. No painel Criar política, em Mediação, selecione Atribuir mensagem.
8. No painel Atribuir mensagem, preencha os campos obrigatórios nas seções Nome e Nome de exibição usando os seguintes valores:
   • Nome: insira um nome para a política. Por exemplo, AssignMessage.
   • Nome de exibição: insira o nome da política para uso na interface. Por exemplo, Assign Message.
9. Clique em Criar.
10. O elemento <APIKey> no código XML abaixo especifica a localização da chave de API na solicitação recebida. Por padrão, a política recupera a chave de 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.

11. Atualize o conteúdo da política Atribuir mensagem para o seguinte:
    Observação:o nome da política vai mudar para Remove Query Param apikey depois que você fizer essa edição.

<AssignMessage async="false" continueOnError="false" enabled="true" name="remove-query-param-apikey">
    <DisplayName>Remove Query Param apikey</DisplayName>
    <Remove>
        <QueryParams>
            <QueryParam name="apikey"/>
        </QueryParams>
    </Remove>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

12. Adicione as políticas VerifyApiKey e Remove Query Param apikey.
    1. No menu Endpoints de proxy, clique em Pré-fluxo.
    2. No painel Solicitação do editor visual, clique em Adicionar etapa de política.
    3. No painel Adicionar etapa de política, selecione Verificar chave de API.
    4. Clique em Adicionar.
    5. No painel Solicitação do editor visual, clique em Adicionar etapa de política.
    6. No painel Adicionar etapa de política, selecione Remover apikey do parâmetro de consulta.
    7. Clique em Adicionar.
13. Clique em Salvar.
14. Implante o proxy em um ambiente:
    1. Clique em Implantar.
    2. Selecione uma Revisão e um Ambiente.
    3. Clique em Implantar.
15. Teste suas mudanças chamando a API conforme descrito em Tentar chamar a API.

IU clássica

1. No editor de proxy da API, clique na guia Desenvolver. Você verá que duas políticas foram adicionadas ao fluxo de solicitações do proxy da API:
   • Verificar a chave de API: verifica a chamada de API para garantir a presença de uma chave de API válida (enviada como um parâmetro de consulta).
   • Remover apikey de consulta: uma política de atribuir mensagem que remove a chave de API após a verificação, para que ela não seja transmitida e exposta desnecessariamente.

2. Clique no ícone de política "Verificar chave de API" na visualização de fluxo e observe a configuração XML da política na visualização de código mais baixa. O elemento <APIKey> informa à política onde ele 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 fará uma chamada sem sucesso para o proxy de API para ver como ela está sendo protegida 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 da API está configurado para encaminhar a solicitação, mas você a alcançará diretamente por enquanto:

   http://mocktarget.apigee.net

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

2. Falha

   Agora tente chamar seu proxy de API:

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

   em que YOUR ENV_GROUP_HOSTNAME é o nome do host do grupo de ambiente. Consulte Encontrar o nome do host do grupo de ambientes.

   Observação: se você tiver problemas para chamar o proxy, talvez seja necessário adicionar o cabeçalho Host, conforme descrito em Implantar um proxy de amostra.

   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"}}}

   Isso significa que, corretamente, você não passou uma chave de API válida como um parâmetro de consulta.

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

Como adicionar um produto de API

Apigee no console do Cloud

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

1. No console do Google Cloud , acesse a página Distribuição > Produtos de API:

   Acessar produtos de API

2. Clique em +Criar.
3. Insira os detalhes do produto do 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.
   Nome de exibição	Nome de exibição do produto de API. O nome de exibição é usado na UI e pode ser editado a qualquer momento. Se não for especificado, o valor Name será usado. Esse campo é preenchido automaticamente com o valor do Nome. Você pode editar ou excluir o conteúdo. O nome de exibição pode incluir caracteres especiais.
   Descrição	Descrição do produto de API.
   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	Ativar a aprovação automática das solicitações de chave deste produto de API em qualquer app.
   Cota	Ignorar para este tutorial.
   Escopos do OAuth permitidos	Ignorar para este tutorial.

4. Na seção Operações, clique em Adicionar uma operação.
5. No campo Proxy de API, selecione o proxy que você acabou de criar.
6. No campo Caminho, digite "/". Ignore os outros campos.
7. Clique em Salvar para salvar a operação.
8. Clique em Salvar para salvar o produto da API.

Para mais informações sobre como adicionar um produto de API, consulte Criar um produto de API.

IU clássica

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

1. Selecione Publicar > Produtos da API.
2. Clique em Criar.
3. Insira os detalhes do produto do 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.
   Nome de exibição	Nome de exibição do produto de API. O nome de exibição é usado na IU e é possível editá-lo a qualquer momento. Se não for especificado, o valor Nome será usado. Esse campo é preenchido automaticamente com o valor do nome. você pode editar ou excluir o conteúdo. O nome de exibição pode incluir caracteres especiais.
   Descrição	Descrição do produto de API.
   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	Ativar a aprovação automática das solicitações de chave deste produto de API em qualquer app.
   Cota	Ignorar para este tutorial.
   Escopos do OAuth permitidos	Ignorar para este tutorial.

4. Na seção Operações, clique em ADICIONAR UMA OPERAÇÃO.
5. No campo "API Proxy", selecione o proxy de API que você acabou de criar.
6. No campo "Caminho", digite "/". Ignore os outros campos.
7. Clique em Salvar para salvar a operação.
8. Clique em Salvar para salvar o produto da API.

Adicionar um desenvolvedor e um app à sua organização

Em seguida, vamos simular o fluxo de trabalho de um desenvolvedor se inscrevendo para usar suas APIs. Um desenvolvedor terá um ou mais apps que chamam suas APIs, e cada app recebe uma chave exclusiva. Isso oferece a você, o provedor da API, um controle mais granular sobre o acesso às suas APIs e relatórios mais detalhados sobre o tráfego da API por aplicativo.

Crie um desenvolvedor

Apigee no console do Cloud

Para criar um desenvolvedor:

1. No console do Google Cloud , acesse a página Distribuição > Desenvolvedores:

   Acessar "Desenvolvedores"

2. Clique em + Criar.
3. Digite o seguinte na janela Adicionar desenvolvedor:
   

   Campo	Valor
   Nome	Keyser
   Sobrenome	Soze
   E-mail	[e-mail]
   Nome de usuário	keyser

4. Clique em Adicionar.

Para mais informações sobre como criar um desenvolvedor, consulte Como registrar desenvolvedores de apps.

IU clássica

Para criar um desenvolvedor:

1. Selecione Publicar > Desenvolvedores no menu.
   Observação: se você ainda estiver na tela "Desenvolver", clique em "<" por DESENVOLVER para exibir o menu e selecione Publicar > Desenvolvedores
2. Clique em + Desenvolvedor.
3. Digite o seguinte na janela "Novo desenvolvedor":
   

   Neste campo	enter
   Nome	Keyser
   Sobrenome	Soze
   Nome de usuário	keyser
   E-mail	[e-mail]

4. Clique em Criar.

Registrar um aplicativo

Apigee no console do Cloud

1. No console do Google Cloud , acesse a página Distribuição > Apps:

   Acessar "Apps".

2. Clique em + Criar.
3. Digite o seguinte na janela Criar app:
   

   Campo	Valor
   Nome do app	Insira: keyser_app
   Nome de exibição	Insira: keyser_app
   Desenvolvedor	Selecione: Keyser Soze ([e-mail])
   URL de callback	Deixar em branco
   Observações	Deixar em branco

4. Na seção "Credenciais", clique em Adicionar credencial.
5. Selecione Nunca. As credenciais deste aplicativo nunca expirarão.
6. Clique em Adicionar produtos.
7. Selecione o produto que você acabou de criar.
8. Clique em Adicionar.
9. Clique em Criar.

Para mais informações sobre como registrar um app, consulte Registrar um app.

IU clássica

Para registrar um app de desenvolvedor:

1. Selecione Publicar > Apps.
2. Clique em + App.
3. Digite o seguinte na janela "Novo app de desenvolvedor":
   

   Campo	Valor
   Nome e nome de exibição	Insira: keyser_app
   Desenvolvedor	Selecione: Keyser Soze ([e-mail])
   Callback URL e Observações	Deixar em branco

4. Na seção "Credenciais", selecione Nunca. As credenciais deste aplicativo nunca expirarão.
5. Clique em Adicionar produto.
6. Selecione o produto que você acabou de criar.
7. Clique em Criar.

Encontre a chave de API

Apigee no console do Cloud

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

1. No console do Google Cloud , acesse a página Distribuição > Apps.

   Acessar "Apps".

2. Selecione o app necessário na lista.
3. Na página Ver app, em Credenciais, clique em ao lado do campo Chave. A chave está associada ao produto que você criou.
4. Clique em Copiar. Você vai usar essa chave na próxima etapa.

IU clássica

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. A chave está associada ao produto que você criou.
   
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. Cole a chave de API conforme mostrado, como um parâmetro de consulta. Verifique se não há espaços extras no parâmetro de consulta.

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

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

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

Em geral, não é uma boa prática passar uma chave de API como um parâmetro de consulta. Considere passá-la no cabeçalho HTTP.

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

Observação: é recomendável transmitir a chave da API em um cabeçalho em vez de em um parâmetro de consulta. Os parâmetros de consulta aparecem no histórico do navegador e nos registros de rede, o que pode apresentar um risco à segurança. Os cabeçalhos não aparecem no histórico do navegador e nos registros de rede.

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

Apigee no console do Cloud

1. No console do Google Cloud , acesse a página Desenvolvimento de proxy > Proxies de API.

Acessar proxies de API

2. Selecione o proxy necessário na lista.
3. Na página Detalhes do proxy, clique em Desenvolver.
4. Modifique o XML da política para que ela procure no cabeçalho e não no queryparam:

<APIKey ref="request.header.x-apikey"/>

5. Clique em Salvar para armazenar as mudanças.
6. Clique em Implantar.
7. Selecione uma Revisão e um Ambiente.
8. Clique em Implantar.

9. Faça a seguinte chamada de API 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: YOUR_API_KEY" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey

Para concluir a alteração, você também precisa configurar a política "Atribuir mensagem" para remover o cabeçalho em vez do parâmetro de consulta. Por exemplo:

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

Observação: você também pode passar a chave de API como um parâmetro de formulário. Se você fizer isso, a política "Verificar chave de API" poderá ser configurada da seguinte maneira:

<APIKey ref="request.formparam.YOUR_API_KEY"/>

IU clássica

1. Edite o proxy de API. Selecione Desenvolver > Proxies de API > helloworld_apikey e acesse a visualização Desenvolver.

2. Selecione a política Verificar chave de API e modifique o XML da política para permitir que a política procure no header e não no queryparam:

   <APIKey ref="request.header.x-apikey"/>

3. Salve o proxy de API e selecione Implantar.

4. Faça a seguinte chamada de API 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_goes_here}" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey

Para concluir a alteração, você também precisa configurar a política "Atribuir mensagem" para remover o cabeçalho em vez do parâmetro de consulta. Por exemplo:

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

Observação: você também pode passar a chave de API como um parâmetro de formulário. Se você fizer isso, a política "Verificar chave de API" poderá ser configurada da seguinte maneira:

<APIKey ref="request.formparam.YOUR_API_KEY"/>

Temas relacionados

Veja alguns tópicos relacionados a produtos e chaves de API:

• Como gerenciar produtos de API
• Chaves de API
• Como registrar desenvolvedores de aplicativos
• Registrar apps e gerenciar chaves de API
• Política "Verificar chave de API"

A proteção de APIs geralmente envolve mais segurança, como o OAuth, um protocolo aberto que troca credenciais (como nome de usuário e senha) para tokens de acesso. Os tokens de acesso são strings longas e aleatórias que podem ser transmitidas por um pipeline de mensagem, mesmo de um app para outro, sem comprometer as credenciais originais.

Para uma visão geral dos tópicos relacionados à segurança, consulte Como proteger um proxy.