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

Esta secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. Estas informações são importantes para saber se está a desenvolver regras de falhas para tratar falhas. Para saber mais, consulte o artigo O que precisa de saber acerca dos erros de políticas e Como processar falhas.

Erros de tempo de execução

Estes erros podem ocorrer quando a política é executada.

Código de falha Estado de HTTP Causa Corrigir
accesscontrol.IPDeniedAccess 403 O endereço IP do cliente ou um endereço IP transmitido no pedido de API corresponde a um endereço IP especificado no elemento <SourceAddress> no elemento <MatchRule> da política de controlo de acesso, e o atributo action do elemento <MatchRule> está definido como DENY.
accesscontrol.InvalidIPAddressInVariable 500 A variável de fluxo em <ClientIPVariable> contém um endereço IP inválido.

Variáveis de falha

Estas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte o artigo Variáveis específicas de erros de políticas.

Variáveis Onde Exemplo
fault.name="fault_name" fault_name é o nome da falha, conforme indicado na tabela Erros de tempo de execução acima. O nome da falha é a última parte do código de falha. fault.name Matches "IPDeniedAccess"
acl.policy_name.failed policy_name é o nome especificado pelo utilizador da política que gerou a falha. acl.AC-AllowAccess.failed = true

Exemplo de resposta de falha

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

Exemplo de regra de falha

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