Política AccessControl

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

Confira a documentação da Apigee Edge.

Ícone da política

O que

Com a política AccessControl, é possível permitir ou negar o acesso às APIs por endereços IP específicos.

Esta é uma política padrão e pode ser implantada em qualquer tipo de ambiente. Para informações sobre os tipos de políticas e a disponibilidade de cada tipo de ambiente, consulte Tipos de políticas.

Vídeo: assista a um breve vídeo para saber mais sobre como permitir ou negar o acesso às suas APIs por endereços IP específicos.

É possível anexar essa política em qualquer lugar do fluxo de proxy da API, mas convém verificar os endereços IP no início do fluxo ( Solicitação / ProxyEndpoint / PreFlow), mesmo antes da autenticação ou da verificação de cota.

Considere também o uso do Google Cloud Armor com a Apigee como uma maneira alternativa de proteger suas APIs.

Amostras

Os valores de máscara nas amostras de IPv4 a seguir identificam quais dos quatro octetos (8, 16, 24 e 32 bits) a regra de correspondência considera ao permitir ou negar o acesso. O valor padrão é 32. Para mais informações, consulte o atributo mask na referência de elemento.

Negar 198.51.100.1

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="32">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

Negar todas as solicitações do endereço do cliente: 198.51.100.1

Permitir solicitações de qualquer outro endereço de cliente.

Negar usando variáveis

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="{kvm.mask.value}">{kvm.ip.value}</SourceAddress>
    </MatchRule>
    </IPRules>
</AccessControl>

Suponha que você esteja usando um mapa de valores-chave (KVM) para armazenar valores de mascaramento e IPs. Essa é uma abordagem útil para alterar IPs e mascarar durante o tempo de execução sem precisar atualizar e reimplantar o proxy da API. É possível usar o Política KeyValueMapOperations para recuperar as variáveis que contêm os valores de kvm.mask.value e kvm.ip.value Supondo que seja o que você nomeou as variáveis na política do KVM que contêm os valores da máscara e dos valores IP do seu KVM. Se os valores recuperados fossem 24 para a máscara e 198.51.100.1 para o endereço IP, a política AccessControl negaria todas as solicitações de: 198.51.100.*

Todos os outros endereços de cliente seriam permitidos.

Negar 198.51.100.*

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
    </MatchRule>
    </IPRules>
</AccessControl>

Negar todas as solicitações do endereço do cliente: 198.51.100.*

Permitir solicitações de qualquer outro endereço de cliente.

198.51.*.*

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
       <SourceAddress mask="16">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

Negar todas as solicitações do endereço do cliente: 198.51.*.*

Permitir solicitações de qualquer outro endereço de cliente.

Negar 198.51.100.*, permitir 192.0.2.1

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "ALLOW">
      <SourceAddress mask="32">192.0.2.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

Negar todas as solicitações do endereço do cliente: 198.51.100.*, mas permitir 192.0.2.1.

Permitir solicitações de qualquer outro endereço de cliente.

Permitir 198.51.*.*

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "DENY">
    <MatchRule action = "ALLOW">
      <SourceAddress mask="16">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

Permitir todas as solicitações do endereço: 198.51.*.*

Negar solicitações de qualquer outro endereço de cliente.

Permitir vários IPs

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "DENY">
    <MatchRule action = "ALLOW">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
      <SourceAddress mask="24">192.0.2.1</SourceAddress>
      <SourceAddress mask="24">203.0.113.1</SourceAddress>
     </MatchRule>
  </IPRules>
</AccessControl>

Permitir solicitações de endereços de clientes: 198.51.100.* 192.0.2.* 203.0.113.*

Negar todos os outros endereços.

Negar vários IPs

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
      <SourceAddress mask="24">192.0.2.1</SourceAddress>
      <SourceAddress mask="24">203.0.113.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

Negar solicitações de endereços de clientes: 198.51.100.* 192.0.2.* 203.0.113.*

Permitir todos os outros endereços.

Permitir vários IPs, negar vários IPs

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "DENY">
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
      <SourceAddress mask="24">192.0.2.1</SourceAddress>
      <SourceAddress mask="24">203.0.113.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "ALLOW">
      <SourceAddress mask="16">198.51.100.1</SourceAddress>
      <SourceAddress mask="16">192.0.2.1</SourceAddress>
      <SourceAddress mask="16">203.0.113.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

Permitir: 198.51.*.* 192.0.*.* 203.0.*.*

Negar um subconjunto da lista de permissões: 198.51.100.* 192.0.2.* 203.0.113.*

Observações sobre uso

Além de proteger as APIs contra IPs mal-intencionados, a política AccessControl também oferece controle sobre o acesso de IP legítimo. Por exemplo, para que apenas os computadores com controle da sua empresa acessem as APIs expostas no seu ambiente de teste, permita o intervalo de endereços IP da sua rede interna. Os desenvolvedores que trabalham em casa podem acessar essas APIs usando a VPN.

A configuração e a execução de uma política AccessControl envolvem:

  • Defina um conjunto de regras de correspondência com uma das duas ações (PERMITIR ou NEGAR) associadas a cada uma.
  • Para cada regra de correspondência, especifique o endereço IP (elemento SourceAddress).
  • Especifique a ordem em que as regras são testadas.
  • Todas as regras de correspondência são executadas na ordem especificada. Quando uma regra corresponde, a ação correspondente é executada, e as regras de correspondência a seguir são ignoradas.
    • Se a mesma regra for configurada com as ações ALLOW e DENY, a regra definida primeiro na ordem será acionada e a regra subsequente (com a outra ação) será ignorada.

Como a política escolhe o endereço IP a ser avaliado

Os endereços IP podem vir de várias origens em uma solicitação. Por exemplo, o cabeçalho da mensagem True-Client-IP pode conter um endereço IP e o cabeçalho X-Forwarded-For pode conter um ou mais endereços IP. Nesta seção, descrevemos como configurar a política do AccessControl para avaliar os endereços IP exatos que você quer avaliar.

Veja a seguir a lógica que a política AccessControl usa para decidir qual endereço IP avaliar:

1. Cabeçalho True-Client-IP

A política verifica primeiro um endereço IP no cabeçalho True-Client-IP. Se o cabeçalho contiver um endereço IP válido, a política avaliará o endereço.

2. Cabeçalho X-Forwarded-For

Se não houver True-Client-IP ou, se você tiver definido o elemento <IgnoreTrueClientIPHeader> como verdadeiro, a política avalia os endereços IP no X-Forwarded-For.

A Apigee preenche automaticamente o cabeçalho X-Forwarded-For com o endereço IP que recebeu do último handshake TCP externo, como o IP do cliente ou o roteador. Se houver vários endereços IP no cabeçalho, esses endereços provavelmente são a cadeia de servidores que processaram uma solicitação. No entanto, a lista de endereços também pode conter um endereço IP falsificado. Como a política sabe quais endereços avaliar?

Dimensões X-Forwarded-For na análise do Apigee

O Apigee Analytics grava o valor do cabeçalho X-Forwarded-For na dimensão x_forwarded_for_ip. Para determinar o IP do cliente que fez a solicitação para a Apigee, use os valores na dimensão ax_resolved_client_ip, mas exclua ax_true_client_ip, que não é compatível com a política AccessControl. Consulte a Referência de métricas, dimensões e filtros do Google Analytics.

Sobre a máscara de IP com notação CIDR

A notação CIDR (roteamento entre domínios sem classificação) é uma maneira de indicar um intervalo de endereços IP por meio do mascaramento. Ele se aplica tanto ao IPv4 quanto ao IPv6. Vamos explicar como você pode fazer isso. Usaremos o IPv4 nos nossos exemplos para simplificar.

Endereços IP são grupos de números separados por pontos. Em termos binários, cada grupo é um número específico de bits (8 para IPv4 e 16 para IPv6). O endereço IPv4 198.51.100.1 é assim em binário:

11000110.00110011.01100100.00000001

Ele tem 4 grupos de 8 bits ou 32 bits no total. Com o CIDR, você pode indicar um intervalo adicionando um /number (1-32) ao endereço IP da seguinte maneira:

198.51.100.1/24

Nesse caso, o 24 é o número que você usaria para o valor de atributo mask nesta política.

Essa notação significa que "Manter os primeiros 24 bits exatamente como estão, os bits restantes podem ser qualquer valor de 0 a 255". Exemplo:

Manter essas configurações exatamente como estão Valores possíveis para o último grupo
198.51.100. 0 - 255

Observe que a máscara acontece no final do grupo três. Isso torna as coisas bonitas e organizadas, em essência, criar uma máscara como esta: 198.51.100.*. Na maioria dos casos, o uso de múltiplos de 8 (IPv4) e 16 (IPv6) oferece o nível de mascaramento desejado:

IPv4: 8, 16, 24, 32

IPv6: 16, 32, 48, 64, 80, 96, 112, 128

No entanto, é possível identificar outros números para um controle mais refinado, o que envolve um pouco cálculo de binário. Veja um exemplo com uma máscara de 30, como em 198.51.100.1/30, em que o último 1 é 00000001 em binário:

Manter essas configurações exatamente como estão Valores possíveis
11000110.00110011.01100100.000000 (os primeiros 30 bits) 00000000, 00000001, 00000010 ou 00000011
198.51.100. 0, 1, 2 ou 3

Neste exemplo, com a configuração definida como <SourceAddress mask="30">198.51.100.1</SourceAddress>, os seguintes IPs seriam permitidos (ou negados, dependendo das suas regras):

  • 198.51.100.0
  • 198.51.100.1
  • 198.51.100.2
  • 198.51.100.3

Referência de elemento

A referência descreve os elementos e atributos da política AccessControl.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">
    <DisplayName>Access Control 1</DisplayName>
    <IPRules noRuleMatchAction = "ALLOW">
        <MatchRule action = "ALLOW">
            <SourceAddress mask="32">198.51.100.1</SourceAddress>
        </MatchRule>
        <MatchRule action = "DENY">
            <SourceAddress mask="24">198.51.100.1</SourceAddress>
        </MatchRule>
    </IPRules>
    <ValidateBasedOn>X_FORWARDED_FOR_ALL_IP</ValidateBasedOn>
</AccessControl>

Atributos <AccessControl>

<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">

Elemento <ClientIPVariable>

Especifica uma variável de fluxo que contém um endereço IP que a política verifica nas IPRules. Se a variável de fluxo não contiver um endereço IP válido (ipv4 ou ipv6), a política gerará um erro.

Suponha que a variável de fluxo esteja definida como 12.31.34.52. No exemplo a seguir, o acesso é negado. Se a variável for definida como 10.11.12.13, o acesso será concedido. 

<AccessControl name='ACL'>
   <ClientIPVariable>FLOW_VARIABLE</ClientIPVariable>
   <IPRules noRuleMatchAction = 'DENY'>
     <MatchRule action = 'ALLOW'>
       <SourceAddress mask='32'>10.11.12.13</SourceAddress>
     </MatchRule>
   </IPRules>
</AccessControl>
Padrão N/A
Presence Opcional
Tipo Variável de fluxo

Elemento <IgnoreTrueClientIPHeader>

Quando isso é definido como verdadeiro, a política ignora o cabeçalho True-Client-IP e avalia os endereços IP no cabeçalho X-Forwarded-For, seguindo o comportamento de avaliação X-Forwarded-For. configurado.

<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">
    <DisplayName>Access Control-1</DisplayName>
    <IgnoreTrueClientIPHeader>true</IgnoreTrueClientIPHeader>
    ...
</AccessControl>
Padrão false
Presence Opcional
Tipo Booleano

Elemento <IPRules>

O elemento pai que contém as regras que permitem ou negam endereços IP. O atributo noRuleMatchAction permite que você defina como processar os endereços IP que não são cobertos pelas regras de correspondência.

<IPRules noRuleMatchAction = "ALLOW">
Padrão N/A
Presence Opcional
Tipo N/A

Atributos

Atributo Descrição Tipo Padrão Presence
noRuleMatchAction
A ação a ser tomada (permitir ou negar acesso) se a regra de correspondência especificada não for resolvida (sem correspondência).
Valor válido: PERMITIR ou NEGAR
String PERMITIR Obrigatório

Elemento <IPRules>/<MatchRule>

A ação a ser tomada (permitir ou negar acesso) se o endereço IP corresponder aos SourceAddress(s) definidos por você.

<IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "ALLOW">
        <SourceAddress mask="32">198.51.100.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "DENY">
        <SourceAddress mask="24">198.51.100.1</SourceAddress>
    </MatchRule>
</IPRules>
Padrão N/A
Presence Opcional
Tipo N/A

Atributos

Atributo Descrição Tipo Padrão Presence
ação

A ação a ser tomada (permitir ou negar o acesso) se a regra de correspondência especificada não for resolvida (sem correspondência).

Valor válido: ALLOW ou DENY

 String PERMITIR Obrigatório

Elemento <IPRules>/<MatchRule>/<SourceAddress>

O intervalo de endereços IP de um cliente.

Valor válido: endereço IP válido (notação decimal com pontos). Para o comportamento de caracteres curinga, use o atributo mask.

<IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "ALLOW">
        <SourceAddress mask="{variable}">198.51.100.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "DENY">
        <SourceAddress mask="24">{variable}</SourceAddress>
    </MatchRule>
</IPRules>

Conforme mostrado no exemplo anterior, o elemento SourceAddress também aceita modelos de mensagem para o atributo mask ou endereço IP, o que significa que você pode definir a valores usando variáveis que estão disponíveis atualmente no fluxo de proxy da API.

Por exemplo, é possível armazenar um endereço IP em um mapa de valores-chave (KVM) e usar a política KeyValueMapOperations para recuperar o endereço IP e atribuí-lo a uma variável (como kvm.ip.value). Você pode usar essa variável para o endereço IP:

<SourceAddress mask="24">{kvm.ip.value}</SourceAddress>

Definir máscara e/ou endereço IP com uma variável permite flexibilidade para alterar valores no momento da execução sem ter que modificar e reimplantar o proxy de API.

Padrão N/A
Presence Opcional
Tipo String (somente endereço IP único)

Atributos

Atributo Descrição Tipo Padrão Presence
máscara

O atributo mask é uma maneira de indicar o intervalo de endereços IP para permitir ou negar. Mas é o equivalente a usar a notação CIDR (roteamento entre domínios sem classificação). Exemplo:

<SourceAddress mask="24">198.51.100.1</SourceAddress>

é equivalente à seguinte notação CIDR:

198.51.100.1/24

Valores válidos:

IPv4: 1-32

IPv6: 1-128

Um valor de zero (0) é válido apenas para o IP 0.0.0.0, portanto, impraticável.

Definir a máscara com uma variável

O atributo mask também é compatível com Modelos de mensagem, o que significa que é possível definir o valor com uma variável atualmente disponível no fluxo do proxy da API. Por exemplo, é possível armazenar um valor de máscara em uma KVM e usar a política KeyValueMapOperations para recuperar a máscara e atribuí-la a uma variável. Para definir a máscara de IP com a variável, use o seguinte formato, supondo que a variável seja nomeada kvm.mask.value:

mask="{kvm.mask.value}"

 Número inteiro N/A Obrigatório

Elemento <ValidateBasedOn>

Quando o cabeçalho HTTP X-Forwarded-For tiver vários endereços IP, use este elemento ValidateBasedOn para controlar quais endereços IP são avaliados.

Use essa abordagem para avaliar endereços IP somente se você tiver certeza sobre a validade dos endereços IP que quer avaliar. Por exemplo, se você optar por avaliar todos os endereços IP no cabeçalho X-Forwarded-For, precisará confiar na validade desses endereços e/ou configurar regras DENY ou ALLOW abrangentes para permitir apenas IPs confiáveis chamam o proxy de sua API.

O endereço IP mais à esquerda no cabeçalho pertence ao cliente, e o mais à direita é o servidor que encaminhou a solicitação para o serviço atual. penúltimo ou o último endereço IP é o endereço que a Apigee recebeu do último handshake TCP externo.

O valor inserido nesse elemento permite que você determine se deve verificar todos os endereços IP no cabeçalho (padrão), apenas o primeiro endereço IP ou apenas o último endereço IP.

<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">
    <DisplayName>Access Control 1</DisplayName>
    <IPRules noRuleMatchAction = "ALLOW">
        <MatchRule action = "DENY">
            <SourceAddress mask="32">198.51.100.1</SourceAddress>
        </MatchRule>
    </IPRules>
    <ValidateBasedOn>X_FORWARDED_FOR_ALL_IP</ValidateBasedOn>
</AccessControl>
Padrão X_FORWARDED_FOR_ALL_IP
Presence Opcional
Valores válidos

X_FORWARDED_FOR_ALL_IP (padrão)

X_FORWARDED_FOR_FIRST_IP

X_FORWARDED_FOR_LAST_IP

Esquemas

Cada tipo de política é definido por um esquema XML (.xsd). Para referência, esquemas de políticas estão disponíveis no GitHub.

Referência de erros

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
accesscontrol.IPDeniedAccess 403 The client IP address, or an IP address passed in the API request, matches an IP address specified in the <SourceAddress> element within the <MatchRule> element of the Access Control Policy, and the action attribute of the <MatchRule> element is set to DENY.
accesscontrol.InvalidIPAddressInVariable 500 The flow variable in <ClientIPVariable> contains an invalid IP address.

Fault variables

These variables are set when a runtime error occurs. For more information, see Variables specific to policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "IPDeniedAccess"
acl.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. acl.AC-AllowAccess.failed = true

Example fault response

{
   "fault":{
     "faultstring":"Access Denied for client ip : 52.211.243.3"
      "detail":{
         "errorcode":"steps.accesscontrol.IPDeniedAccess"
      }
   }
}

Example fault rule

<FaultRule name="IPDeniedAccess">
    <Step>
        <Name>AM-IPDeniedAccess</Name>
        <Condition>(fault.name Matches "IPDeniedAccess") </Condition>
    </Step>
    <Condition>(acl.failed = true) </Condition>
</FaultRule>