Resolução de IP do cliente

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

Confira a documentação da Apigee Edge.

Identificar com precisão o endereço IP do cliente nas solicitações de API é importante para algumas funcionalidades na Apigee, incluindo Analytics e Segurança avançada de API, como a detecção de abuso e ações de segurança.

O processo de identificação do IP do cliente é desafiador em arquiteturas de rede modernas que empregam proxies e balanceadores de carga, porque esses intermediários podem obscurecer o endereço IP de origem real.

Para superar esse desafio, a Apigee oferece suporte a uma configuração no nível do ambiente que especifica como resolver o endereço IP do cliente do cabeçalho X-Forwarded-For (XFF), identificando o índice no cabeçalho que corresponde ao endereço IP para a topologia de rede e os requisitos de segurança. O uso dessa configuração oferece visibilidade, consistência e controle sobre como os endereços IP do cliente são determinados para todas as solicitações no ambiente e resultam em uma identificação consistente do endereço IP do cliente na segurança avançada da API, nas variáveis de fluxo e nas variáveis de análise no ambiente.

Se a resolução do IP do cliente no nível do ambiente não estiver configurada conforme descrito nesta página, as variáveis do endereço IP do cliente serão preenchidas usando o comportamento de resolução do endereço IP do cliente padrão.

Resolução de endereço IP do cliente padrão

Se a resolução do IP do cliente não estiver configurada no nível do ambiente, o valor padrão da dimensão ax_resolved_client_ip será calculado conforme descrito em Dimensões do Google Analytics.

Se a resolução do IP do cliente for configurada para um ambiente, o fluxo e as variáveis do Google Analytics serão definidas com base na configuração de resolução do IP do cliente. Consulte Definir a resolução de IP do cliente para um ambiente.

Quando definir a resolução de IP do cliente para um ambiente

Embora não seja necessário definir a resolução do IP do cliente, você pode fazer isso se a resolução padrão do endereço IP do cliente não atender às suas necessidades e você quiser substituir essa resolução para fornecer uma resolução de endereço IP do cliente especificada para o Google Analytics, a Advanced API Security ou qualquer outra função que exija informações consistentes e confiáveis sobre endereços IP do cliente.

Entender a sintaxe de configuração da resolução de IP do cliente

A configuração de resolução de IP do cliente tem este formato:

"clientIpResolutionConfig": {
  "headerIndexAlgorithm": {
     "ipHeaderName" : "X-Forwarded-For",
     "ipHeaderIndex": 2
  }
}
 em que
  • ipHeaderName é o cabeçalho a ser usado para o IP do cliente. No momento, X-Forwarded-For é o valor do cabeçalho aceito.
  • ipHeaderIndex é o valor do índice dentro de ipHeaderName.

    Um número positivo seleciona um endereço começando pela esquerda (o primeiro endereço adicionado ao cabeçalho), em que a primeira posição à esquerda é 0 e aumenta em um para cada endereço subsequente (por exemplo, 0, 1, 2). Por exemplo, se a lista for 192.0.2.1, 192.0.2.2, 192.0.2.3, um índice de 1 será resolvido como 192.0.2.2.

    O número negativo seleciona um endereço a partir da direita (o último endereço adicionado ao cabeçalho), em que a primeira posição à direita é -1 e diminui em um para cada endereço subsequente (por exemplo, -3, -2, -1). Por exemplo, se a lista for 192.0.2.1, 192.0.2.2, 192.0.2.3, 192.0.2.4, o índice de -1 será resolvido como 192.0.2.4, e o índice -2 será resolvido como 192.0.2.3.

Consulte a API organizations.environment para mais informações sobre essa configuração.

Conferir as configurações de resolução de IP do cliente

É possível conferir a configuração atual de resolução de IP do cliente para um ambiente usando a interface da Apigee ou as APIs de gerenciamento.

Conferir a configuração de resolução do IP do cliente usando a UI

Para usar a interface da Apigee no console do Cloud e conferir a configuração de resolução de IP do cliente, selecione Gerenciamento > Ambientes, selecione o ambiente e confira Configuração de IP do cliente na guia Sobre.

Resolução de IP do cliente na interface da Apigee

Conferir a configuração de resolução de IP do cliente usando a API

Para usar as APIs Apigee Management para conferir a configuração de resolução de IP do cliente, envie uma solicitação para a API organizations.environments.get.

Definir a resolução do IP do cliente para um ambiente

Depois de definir a configuração de resolução de IP do cliente para um ambiente, a variável de fluxo client.resolved.ip é preenchida usando o algoritmo especificado. Assim como a Resolved Client IP dimensão do Google Analytics.

Depois de definir a configuração de resolução de IP do cliente para um ambiente, as mudanças podem afetar as configurações da Segurança avançada da API para regras de ação de segurança. Analise e, se necessário, gere novamente as regras atuais para usar as novas variáveis e configurações.

Considere estas implicações ao selecionar o índice para a resolução de IP do cliente:

  • As chamadas do Apigee para o Apigee não são tratadas como um caso especial. Confira e ignore o número de IPs de acordo.
  • Como o cabeçalho X-Forwarded-For pode ser falsificado, é melhor usar o índice correto com base no número de saltos esperados entre o cliente e o balanceador de carga da Apigee. Um usuário malicioso pode enviar um cabeçalho X-Forwarded-For preenchido. Embora o primeiro IP no XFF esteja mais próximo do IP do cliente real, o último IP no XFF é mais confiável, já que o balanceador de carga conhece o cliente TCP conectado a ele.

Para definir a resolução do IP do cliente em um ambiente, use uma das APIs de gerenciamento de API da Apigee para definir a resolução do IP do cliente para o ambiente no client_ip_resolution_config. Use organizations.environments.create para novos ambientes. Use updateEnvironment ou modifyEnvironment para ambientes atuais.

Testar a resolução do endereço IP do cliente

Depois de salvar uma nova configuração de IP do cliente, siga estas instruções para testá-la:

  1. Aguarde pelo menos cinco minutos após salvar uma nova configuração.
  2. Inicie uma sessão de depuração. Ative a configuração Mostrar todos os FlowInfos.
  3. Verifique o FlowInfo pouco antes de Proxy Request Flow Started. O endereço IP do cliente configurado será mostrado nessa seção.

Procure estas variáveis no FlowInfo:

  • client_ip_resolution.resolved.ip: o endereço IP do cliente resolvido.
  • client_ip_resolution.used.fallback: booleano. Esse valor é false, a menos que a Apigee tenha retornado à resolução de IP do cliente padrão devido à incapacidade de usar uma resolução de IP do cliente configurada. Por exemplo, se a resolução configurada especificar um índice que não existe no cabeçalho.
  • client_ip_resolution.algorithm: o algoritmo usado para determinar o endereço IP do cliente. Se configurado, será "HeaderIndexAlgorithm{IpHeaderName:header_name, IpHeaderIndex: $header_index}". Caso contrário, ele mostrará default.

Limitações

Estas limitações se aplicam à resolução de IP do cliente no nível do ambiente:

  • As atualizações nas configurações de resolução de IP do cliente podem levar até cinco minutos para entrar em vigor.
  • Evite mudanças frequentes (por exemplo, a cada 5 minutos) na configuração de resolução de IP do cliente, porque isso pode causar degradação de desempenho.
  • No momento, não é possível definir a configuração de resolução de IP do cliente para um ambiente com a Apigee híbrida.
  • A configuração pode ser visualizada no console ou na API do Apigee, mas só pode ser definida pela API.
  • Mesmo na ausência de usuários maliciosos, a lista X-Forwarded-For depende de cada proxy para adicionar as informações corretas à lista. Essa lista completa está fora da supervisão e do controle da Apigee. Portanto, definir a configuração de resolução de IP do cliente não garante a identificação do endereço IP correto da solicitação.