Esta página se aplica à Apigee e à Apigee híbrida.
Confira a documentação da
Apigee Edge.
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.
Criar o proxy de API
Apigee no console do Cloud
No console do Google Cloud , acesse a página Desenvolvimento de proxy > Proxies de API.
- 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.
- Clique em + Criar.
- 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.
- 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!
. - Clique em Próxima.
- Implantar (opcional). Deixe esses campos em branco.
- Clique em Criar.
- A Apigee cria o novo proxy e mostra o resumo dos detalhes no painel Resumo do proxy.
IU clássica
- Acesse a IU da Apigee e faça login.
- Selecione a organização usando o menu suspenso no canto superior esquerdo da UI.
-
Clique em Desenvolver > Proxies de API para exibir a lista de proxies de API.
- Clique em Criar nova.
- No assistente de criação de proxy, selecione Proxy reverso (mais comum).
- 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!
. - Clique em Próxima.
- 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.
- Clique em Próxima.
- Na página "Resumo", verifique se o ambiente de implantação está selecionado e clique em Criar e implantar.
- 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
- No painel Resumo do proxy do proxy helloworld_apikey, clique na guia Desenvolver.
- No menu Políticas, clique em Adicionar política.
- No painel Criar política, em Segurança, selecione Verificar chave de API.
- 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
.
- Nome: insira um nome para a política. Por exemplo,
- Clique em Criar.
- Clique em para adicionar outra política.
- No painel Criar política, em Mediação, selecione Atribuir mensagem.
- 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
.
- Nome: insira um nome para a política. Por exemplo,
- Clique em Criar.
- 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 chamadoapikey
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. - Atualize o conteúdo da política Atribuir mensagem para o seguinte:
- Adicione as políticas
VerifyApiKey
eRemove Query Param apikey
.- No menu Endpoints de proxy, clique em Pré-fluxo.
- No painel Solicitação do editor visual, clique em Adicionar etapa de política.
- No painel Adicionar etapa de política, selecione Verificar chave de API.
- Clique em Adicionar.
- No painel Solicitação do editor visual, clique em Adicionar etapa de política.
- No painel Adicionar etapa de política, selecione Remover apikey do parâmetro de consulta.
- Clique em Adicionar.
- Clique em Salvar.
- Implante o proxy em um ambiente:
- Clique em Implantar.
- Selecione uma Revisão e um Ambiente.
- Clique em Implantar.
- Teste suas mudanças chamando a API conforme descrito em Tentar chamar a API.
<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>
IU clássica
- 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.
-
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 chamadoapikey
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.
-
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!
-
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.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:
No console do Google Cloud , acesse a página Distribuição > Produtos de API:
- Clique em +Criar.
- 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
ouprod
.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. - Na seção Operações, clique em Adicionar uma operação.
- No campo Proxy de API, selecione o proxy que você acabou de criar.
- No campo Caminho, digite "/". Ignore os outros campos.
- Clique em Salvar para salvar a operação.
- 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:
- Selecione Publicar > Produtos da API.
- Clique em Criar.
- 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
ouprod
.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. - Na seção Operações, clique em ADICIONAR UMA OPERAÇÃO.
- No campo "API Proxy", selecione o proxy de API que você acabou de criar.
- No campo "Caminho", digite "/". Ignore os outros campos.
- Clique em Salvar para salvar a operação.
- 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:
-
No console do Google Cloud , acesse a página Distribuição > Desenvolvedores:
- Clique em + Criar.
- Digite o seguinte na janela Adicionar desenvolvedor:
Campo Valor Nome Keyser
Sobrenome Soze
E-mail keyser@example.com
Nome de usuário keyser
- 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:
- 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 - Clique em + Desenvolvedor.
- Digite o seguinte na janela "Novo desenvolvedor":
Neste campo enter Nome Keyser
Sobrenome Soze
Nome de usuário keyser
E-mail keyser@example.com
- Clique em Criar.
Registrar um aplicativo
Apigee no console do Cloud
-
No console do Google Cloud , acesse a página Distribuição > Apps:
- Clique em + Criar.
- 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 (keyser@example.com)
URL de callback Deixar em branco Observações Deixar em branco - Na seção "Credenciais", clique em Adicionar credencial.
- Selecione Nunca. As credenciais deste aplicativo nunca expirarão.
- Clique em Adicionar produtos.
- Selecione o produto que você acabou de criar.
- Clique em Adicionar.
- 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:
- Selecione Publicar > Apps.
- Clique em + App.
- Digite o seguinte na janela "Novo app de desenvolvedor":
Campo Valor Nome e nome de exibição Insira: keyser_app
Desenvolvedor Selecione: Keyser Soze (keyser@example.com)
Callback URL e Observações Deixar em branco - Na seção "Credenciais", selecione Nunca. As credenciais deste aplicativo nunca expirarão.
- Clique em Adicionar produto.
- Selecione o produto que você acabou de criar.
- Clique em Criar.
Encontre a chave de API
Apigee no console do Cloud
Para acessar a chave de API, faça o seguinte:
No console do Google Cloud , acesse a página Distribuição > Apps.
- Selecione o app necessário na lista.
- Na página Ver app, em Credenciais, clique em ao lado do campo Chave. A chave está associada ao produto que você criou.
- 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:
- Na página "Apps" (Publicar > Apps), clique em keyser_app.
- 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.
- 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
Nesta etapa, você modificará o proxy para procurar a chave de API em um cabeçalho chamado x-apikey
.
Apigee no console do Cloud
- No console do Google Cloud , acesse a página Desenvolvimento de proxy > Proxies de API.
- Selecione o proxy necessário na lista.
- Na página Detalhes do proxy, clique em Desenvolver.
- Modifique o XML da política para que ela procure no cabeçalho e não no queryparam:
- Clique em Salvar para armazenar as mudanças.
- Clique em Implantar.
- Selecione uma Revisão e um Ambiente.
- Clique em Implantar.
-
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
<APIKey ref="request.header.x-apikey"/>
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>
IU clássica
- Edite o proxy de API. Selecione Desenvolver > Proxies de API > helloworld_apikey e acesse a visualização Desenvolver.
-
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 noqueryparam
:<APIKey ref="request.header.x-apikey"/>
- Salve o proxy de API e selecione Implantar.
-
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>
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.