Política AccessControl

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Ícone de política

O quê

A política AccessControl permite-lhe conceder ou negar o acesso às suas APIs por endereços IP específicos.

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

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

Embora possa anexar esta política em qualquer parte do fluxo do proxy de API, é mais provável que queira verificar os endereços IP no início do fluxo ( Request / ProxyEndpoint / PreFlow), mesmo antes da autenticação ou da verificação de quotas.

Também deve considerar usar o Google Cloud Armor com o Apigee como uma forma alternativa de proteger as suas APIs.

Amostras

Os valores de máscara nos seguintes exemplos de IPv4 identificam qual dos quatro octetos (8, 16, 24, 32 bits) a regra de correspondência considera ao permitir ou negar o acesso. O valor predefinido é 32. Consulte o atributo mask na referência de elementos para mais informações.

Recusar 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 todos os pedidos do endereço do cliente: 198.51.100.1

Permitir pedidos de qualquer outro endereço de cliente.

Recuse a utilização de variáveis

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

Suponhamos que está a usar um mapa de chave-valor (KVM) para armazenar valores para a ocultação e os IPs. Esta é uma abordagem útil para alterar os IPs e a ocultação durante a execução sem ter de atualizar e reimplementar o proxy de API. Pode usar a política KeyValueMapOperations para obter as variáveis que contêm os valores de kvm.mask.value e kvm.ip.value (partindo do princípio de que foi assim que denominou as variáveis na sua política KVM que contêm os valores da máscara e os valores de IP do seu KVM). Se os valores que obteve foram 24 para a máscara e 198.51.100.1 para o endereço IP, a política AccessControl recusaria todos os pedidos de: 198.51.100.*

Todos os outros endereços de cliente seriam permitidos.

Recusar 198.51.100.*

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

Negar todos os pedidos do endereço do cliente: 198.51.100.*

Permitir pedidos 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 todos os pedidos do endereço do cliente: 198.51.*.*

Permitir pedidos de qualquer outro endereço de cliente.

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

Recusar todos os pedidos do endereço do cliente: 198.51.100.*, mas permitir 192.0.2.1.

Permitir pedidos de qualquer outro endereço de cliente.

Allow 198.51.*.*

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

Permitir todos os pedidos do endereço: 198.51.*.*

Recusar pedidos 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 pedidos de endereços de clientes: 198.51.100.* 192.0.2.* 203.0.113.*

Negar todos os outros endereços.

Recuse 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 pedidos de endereços de clientes: 198.51.100.* 192.0.2.* 203.0.113.*

Permitir todos os outros endereços.

Permitir vários IPs, recusar 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>

Allow: 198.51.*.* 192.0.*.* 203.0.*.*

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

Notas de utilização

Além de proteger as suas APIs contra IPs maliciosos, a política AccessControl também lhe permite controlar o acesso de IPs legítimos. Por exemplo, se quiser que apenas os computadores sob o controlo da sua empresa acedam às APIs expostas no seu ambiente de teste, pode permitir o intervalo de endereços IP da sua rede interna. Os programadores que trabalham a partir de casa podem aceder a estas APIs através de uma VPN.

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

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

Processamento de endereços IP inválidos

A política AccessControl processa strings de endereços IP inválidas transmitidas como variáveis de forma diferente das strings inválidas analisadas através de cabeçalhos.

  • Com base no cabeçalho (sem <ClientIPVariable>): quando a política analisa diretamente o cabeçalho X-Forwarded-For (XFF), qualquer string que não seja um IP (por exemplo, pwned) no cabeçalho que está a ser avaliado é ignorada silenciosamente. A política prossegue como se a string do endereço IP não correspondesse a nenhuma regra, e é realizada a ação especificada por <noRuleMatchAction>. Isto pode ser um problema de segurança se <noRuleMatchAction> estiver definido como ALLOW, uma vez que pode ser usado para ignorar as regras blocklist.
  • Com base em variáveis (é usado <ClientIPVariable>): se uma variável especificada em <ClientIPVariable> contiver um formato de endereço IP inválido, a política gera um erro (por exemplo, accesscontrol.InvalidIPAddressInVariable). Isto fornece uma falha mais explícita e é a abordagem recomendada para uma validação de IP mais rigorosa.

Como a política escolhe o endereço IP a avaliar

Os endereços IP podem ser provenientes de várias origens num pedido. Por exemplo, o cabeçalho X-Forwarded-For pode conter um ou mais endereços IP. Esta secção descreve como configurar a política AccessControl para avaliar os endereços IP exatos que quer que sejam avaliados.

Segue-se a lógica que a política AccessControl usa para decidir que endereço IP avaliar:

Cabeçalho X-Forwarded-For

O Apigee preenche automaticamente o cabeçalho X-Forwarded-For com o endereço IP que recebeu da última confirmação de TCP externa (como o IP do cliente ou o router). Se existirem vários endereços IP no cabeçalho, é provável que esses endereços sejam a cadeia de servidores que processaram um pedido. No entanto, a lista de endereços também pode conter um endereço IP roubado. Como é que a política sabe que endereços deve avaliar?

Especificação do Apigee para o comportamento do cabeçalho XFF

No Apigee, a presença de equilibradores de carga do Google Cloud (GCLBs) afeta a estrutura do cabeçalho X-Forwarded-For (XFF). O formato típico do cabeçalho é o seguinte:

X-Forwarded-For: <client_ip>, <GCLB1_ip>, <internal_ingress_ip>

É fundamental compreender as implicações desta estrutura quando usar o elemento ValidateBasedOn:

  • X_FORWARDED_FOR_LAST_IP: no Apigee, a utilização desta definição avalia o endereço IP interno do segundo GCLB e não o IP do cliente original. Isto pode levar a um comportamento inesperado das políticas.
  • X_FORWARDED_FOR_FIRST_IP: Embora esta definição avalie corretamente o <client_ip> original, deve ter em atenção que o <client_ip> pode ser facilmente falsificado pelo cliente, o que o torna menos fiável para exemplos de utilização sensíveis à segurança.

Dimensões X-Forwarded-For nas estatísticas do Apigee

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

Acerca da ocultação de IP com a notação CIDR

A notação CIDR (Classless Inter-Domain Routing) é uma forma de indicar um intervalo de endereços IP através da ocultação. Aplica-se a IPv4 e IPv6. Eis como funciona. Vamos usar o IPv4 nos nossos exemplos para simplificar.

As moradas 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 tem o seguinte aspeto em binário:

11000110.00110011.01100100.00000001

São 4 grupos de 8 bits, ou um total de 32 bits. Com a notação CIDR, pode indicar um intervalo adicionando um /número (1 a 32) ao endereço IP, da seguinte forma:

198.51.100.1/24

Neste caso, 24 é o número que usaria para o valor do atributo mask nesta política.

Esta notação significa "Mantenha os primeiros 24 bits exatamente como estão. Os restantes bits podem ser qualquer valor de 0 a 255". Por exemplo:

Mantenha-os exatamente como estão Valores possíveis para o último grupo
198.51.100. 0 - 255

Repare que a máscara ocorre no final do grupo três. Isto torna as coisas mais organizadas e, na essência, cria uma máscara como esta: 198.51.100.*. Na maioria dos casos, a utilização de múltiplos de 8 (IPv4) e 16 (IPv6) dá-lhe o nível de ocultação pretendido:

IPv4: 8, 16, 24, 32

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

No entanto, pode usar outros números para um controlo mais detalhado, o que envolve um pequeno cálculo binário. Segue-se um exemplo com uma máscara de 30, como em 198.51.100.1/30, em que o último 1 é 00000001 em binário:

Mantenha-os exatamente como estão Valores possíveis
11000110.00110011.01100100.000000 (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, consoante as suas regras):

  • 198.51.100.0
  • 198.51.100.1
  • 198.51.100.2
  • 198.51.100.3

Referência do elemento

A referência de elementos descreve os elementos e os 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 em relação às IPRules. Se a variável de fluxo não contiver um endereço IP válido (ipv4 ou ipv6), a política gera um erro.

Suponhamos que a variável de fluxo está definida como 12.31.34.52. No exemplo seguinte, o acesso é negado. Se a variável estiver definida como 10.11.12.13, o acesso é 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>
Predefinição N/A
Presença Opcional
Tipo Variável de fluxo

Elemento <IgnoreTrueClientIPHeader>

Elemento <IPRules>

O elemento principal que contém as regras que permitem ou recusam endereços IP. O atributo noRuleMatchAction permite-lhe definir como processar quaisquer endereços IP que não sejam abrangidos pelas suas regras de correspondência.

<IPRules noRuleMatchAction = "ALLOW">
Predefinição N/A
Presença Opcional
Tipo N/A

Atributos

Atributo Descrição Tipo Predefinição Presença
noRuleMatchAction
A ação a realizar (permitir ou negar acesso) se a regra de correspondência especificada não for resolvida (sem correspondência).
Valor válido: ALLOW ou DENY
String PERMITIR Obrigatória

Elemento <IPRules>/<MatchRule>

A ação a realizar (permitir ou negar acesso) se o endereço IP corresponder aos SourceAddress(es) que definir.

<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>
Predefinição N/A
Presença Opcional
Tipo N/A

Atributos

Atributo Descrição Tipo Predefinição Presença
ação

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

Valor válido: ALLOW ou DENY

 String PERMITIR Obrigatória

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

O intervalo de endereços IP de um cliente.

Valor válido: endereço IP válido (notação decimal pontuada). Para o comportamento de carateres universais, 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 suporta modelos de mensagens para o atributo mask ou o endereço IP, o que significa que pode definir os valores através de variáveis atualmente disponíveis no fluxo do proxy da API.

Por exemplo, pode armazenar um endereço IP num mapa de chave-valor (KVM) e usar a política KeyValueMapOperations para obter o endereço IP e atribuí-lo a uma variável (como kvm.ip.value). Em seguida, pode usar essa variável para o endereço IP:

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

A definição da máscara e/ou do endereço IP com uma variável dá-lhe a flexibilidade de alterar os valores no tempo de execução sem ter de modificar e voltar a implementar o proxy da API.

Predefinição N/A
Presença Opcional
Tipo String (apenas um endereço IP)

Atributos

Atributo Descrição Tipo Predefinição Presença
máscara

O atributo mask é uma forma de indicar o intervalo de endereços IP a permitir ou recusar. A máscara é o equivalente a usar a notação CIDR (Classless Inter-Domain Routing). Por 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) só é válido para o IP 0.0.0.0 e, por isso, é impraticável.

Defina a máscara com uma variável

O atributo mask também suporta modelos de mensagens, o que significa que pode definir o valor com uma variável atualmente disponível no fluxo do proxy da API. Por exemplo, pode armazenar um valor de máscara num KVM e usar a política KeyValueMapOperations para obter 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, partindo do princípio de que a variável se chama kvm.mask.value:

mask="{kvm.mask.value}"

 Número inteiro N/A Obrigatória

Elemento <ValidateBasedOn>

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

Use esta abordagem para avaliar endereços IP apenas se tiver a certeza da validade dos endereços IP que quer avaliar. Por exemplo, se optar por avaliar todos os endereços IP no cabeçalho X-Forwarded-For, tem de poder confiar na validade desses endereços e/ou configurar regras de NEGAR ou PERMITIR abrangentes para permitir que apenas IPs fidedignos chamem o seu proxy de API.

O endereço IP mais à esquerda no cabeçalho pertence ao cliente e o mais à direita é o servidor que encaminhou o pedido para o serviço atual. O endereço IP mais à direita ou o último endereço IP é o endereço que o Apigee recebeu da última confirmação de TCP externa.

O valor que introduz neste elemento permite-lhe determinar se deve verificar todos os endereços IP no cabeçalho (predefiniçã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>
Predefinição X_FORWARDED_FOR_ALL_IP
Presença Opcional
Valores válidos

X_FORWARDED_FOR_ALL_IP (predefiniçã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, os esquemas de políticas estão disponíveis no GitHub.

Referência de erro

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>