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.

Nota: este vídeo foi gravado com uma versão anterior da IU do Apigee. No entanto, os conceitos continuam válidos.

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 chave 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.

Nota: para concluir este tutorial, vai criar e implementar um proxy que usa políticas extensíveis vs. políticas padrão.

Crie o proxy de API

Apigee na Cloud Console

1. Na Google Cloud consola, aceda à página Desenvolvimento de proxy > Proxies de API.

   Aceda aos proxies de API

2. Selecione a sua organização no selecionador de projetos do painel do Google Cloud. O nome da organização é igual ao nome do seu projeto do Google Cloud.
3. Clique em + Criar.
4. No painel Criar um proxy, em Modelo de proxy, selecione Proxy inverso (mais comum). Um proxy inverso encaminha o tráfego recebido para um serviço de back-end.
5. Configure o proxy da seguinte forma:
   

   Nome	Valor
   Nome do proxy	helloworld_apikey
   Caminho base	/helloapikey O caminho base do projeto faz parte do URL usado para fazer pedidos ao proxy de API.
   Descrição	hello world protected by API key
   Destino (API existente)	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!.

6. Clicar em Seguinte.
7. Implemente (opcional). Deixe estes campos em branco.
8. Clique em Criar.
9. O Apigee cria o novo proxy e apresenta o resumo dos detalhes do proxy no painel Resumo do proxy.

IU clássica

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 Develop > API Proxies para apresentar a lista de proxies de API.

4. Clique em Criar novo.
   
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 de vista geral do proxy de API.

Veja as políticas

Apigee na Cloud Console

1. No painel Resumo do proxy para o proxy helloworld_apikey, clique no separador Desenvolver.
2. No menu Políticas, clique em Adicionar política.
3. No painel Criar política, em Segurança, selecione Validar chave da API.
4. No painel Validar chave da API, preencha os campos obrigatórios nas secções Nome e Nome a apresentar com os seguintes valores:
   • Nome: introduza um nome da política. Por exemplo, VerifyAPIKey.
   • Nome a apresentar: introduza o nome da política para utilização na IU. 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 secções Nome e Nome a apresentar com os seguintes valores:
   • Nome: introduza um nome da política. Por exemplo, AssignMessage.
   • Nome a apresentar: introduza o nome da política para utilização na IU. Por exemplo, Assign Message.
9. Clique em Criar.
10. O elemento <APIKey> no código XML abaixo especifica a localização da chave da API no pedido recebido. Por predefinição, a política obtém a chave de 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.

11. Atualize os conteúdos da política de Atribuir mensagem para o seguinte:
    Nota: o nome da política vai mudar para Remove Query Param apikey assim que fizer esta 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 Pontos finais de proxy, clique em Preflow.
    2. No painel Pedido do editor visual, clique em Adicionar etapa de política.
    3. No painel Passo Adicionar política, selecione Validar chave da API.
    4. Clique em Adicionar.
    5. No painel Pedido do editor visual, clique em Adicionar etapa de política.
    6. No painel Adicionar passo de política, selecione Remover apikey de parâmetro de consulta.
    7. Clique em Adicionar.
13. Clique em Guardar.
14. Implemente o seu proxy num ambiente:
    1. Clique em Implementar.
    2. Selecione uma Revisão e um Ambiente.
    3. Clique em Implementar.
15. Teste as alterações chamando a API conforme descrito em Tente chamar a API.

IU clássica

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 da 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.

   Nota: se tiver problemas em chamar o proxy, pode ter de adicionar o cabeçalho Host, conforme descrito em Implemente um proxy de exemplo.

   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 de API

Apigee na Cloud Console

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

1. Na Google Cloud consola, aceda à página Distribuição > Produtos API:

   Aceda aos produtos de API

2. Clique em +Criar.
3. Introduza os detalhes do produto para o seu produto de 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 da 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 Name. 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.

Para mais informações sobre como adicionar um produto API, consulte o artigo Crie um produto API.

IU clássica

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 do 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

Apigee na Cloud Console

Para criar um programador:

1. Na Google Cloud consola, aceda à página Distribuição > Programadores:

   Aceda ao Google Developers

2. Clique em + Criar.
3. Introduza o seguinte na janela Adicionar programador:
   

   Campo	Valor
   Nome próprio	Keyser
   Apelido	Soze
   Email	[e-mail]
   Nome de utilizador	keyser

4. Clique em Adicionar.

Para mais informações sobre como criar um programador, consulte o artigo Registar programadores de apps.

IU clássica

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	[e-mail]

4. Clique em Criar.

Registe uma app

Apigee na Cloud Console

1. Na Google Cloud consola, aceda à página Distribuição > Apps:

   Aceda a Apps

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

   Campo	Valor
   Nome da app	Introduza: keyser_app
   Nome a apresentar	Introduza: keyser_app
   Programador	Selecionar: Keyser Soze ([e-mail])
   URL de retorno de chamada	Deixe em branco
   Notes	Deixe em branco

4. Na secção Credenciais, clique em Adicionar credencial.
5. Selecione Nunca. As credenciais desta app nunca expiram.
6. Clique em Adicionar produtos.
7. Selecione o produto que acabou de criar.
8. Clique em Adicionar.
9. Clique em Criar.

Para mais informações sobre o registo de uma app, consulte o artigo Registar uma app.

IU clássica

Para registar uma app de programador:

1. Selecione Publicar > Apps.
2. Clique em + App.
3. Introduza o seguinte na janela Nova app de programador:
   

   Campo	Valor
   Nome e Nome a apresentar	Introduza: keyser_app
   Programador	Selecionar: Keyser Soze ([e-mail])
   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

Apigee na Cloud Console

Para obter a chave da API:

1. Na Google Cloud consola, aceda à página Distribuição > Apps.

   Aceda a Apps

2. Selecione a app necessária na lista de apps.
3. Na página Ver app, em Credenciais, clique em junto ao campo Chave. Repare que a chave está associada ao produto que criou.
4. Clique em Copiar. Vai usar esta chave no passo seguinte.

IU clássica

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

Nota: é uma boa prática transmitir a chave da API num cabeçalho em vez de num parâmetro de consulta. Os parâmetros de consulta aparecem no histórico do navegador e nos registos de rede, o que pode apresentar um risco de segurança. Os cabeçalhos não aparecem no histórico do navegador nem nos registos de rede.

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

Apigee na Cloud Console

1. Na Google Cloud consola, aceda à página Desenvolvimento de proxy > Proxies de API.

Aceda aos proxies de API

2. Selecione o proxy necessário na lista de proxies.
3. Na página Detalhes do proxy, clique em Desenvolver.
4. Modifique o XML da política para indicar à política que procure no cabeçalho e não no parâmetro de consulta:

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

5. Clique em Guardar para guardar as alterações.
6. Clique em Implementar.
7. Selecione uma Revisão e um Ambiente.
8. Clique em Implementar.

9. Faça a seguinte chamada da API com o 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: YOUR_API_KEY" 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>

Nota: também pode transmitir a chave da API como um parâmetro de formulário. Se o fizesse, a política Verify API Key seria configurada da seguinte forma:

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

IU clássica

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

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>

Nota: também pode transmitir a chave da API como um parâmetro de formulário. Se o fizesse, a política Verify API Key seria configurada da seguinte forma:

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

Tópicos relacionados

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

• Gerir produtos de API
• Chaves de API
• Registar programadores de apps
• Registe apps e faça a gestão das chaves da API
• Política de validação da chave 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.