Política AccessControl

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

O que

A política de controle de acesso permite permitir ou negar o acesso às 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.

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.

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

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

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

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

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

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

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

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

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

Observações sobre o uso

Além de proteger as APIs contra IPs mal-intencionados, a política de controle de acesso também oferece controle sobre o acesso legítimo de IP. 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 de controle de acesso 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).
  • Consulte Como a política escolhe o endereço IP a ser avaliado para determinar quais endereços IP na mensagem você está configurando regras para processar.
  • Configure uma máscara para cada endereço IP. Você permite ou nega o acesso com base em um valor de máscara no endereço IP. Consulte Sobre o mascaramento de IP com a notação CIDR.
• 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.

O Edge 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?

As configurações da sua organização e da política determinam quais endereços X-Forwarded-For são avaliados.

Primeiro, verifique se a propriedade feature.enableMultipleXForwardCheckForACL está configurada na organização. Você pode usar a API Get organização para verificar. Em seguida:

• Se você não vir feature.enableMultipleXForwardCheckForACL na lista de propriedades da sua organização, significa que essa propriedade está definida como false (padrão). Com essa propriedade definida como falsa, a política avalia o último endereço no cabeçalho (visível na caixa Ferramenta de rastreamento ), que é o endereço IP Edge do último handshake de TCP externo.
• Se feature.enableMultipleXForwardCheckForACL na sua organização estiver definido como verdadeiro, configure o elemento <ValidateBasedOn> para determinar quais endereços IP a política avalia.

Como alterar a propriedade feature.enableMultipleXForwardCheckForACL

Os administradores da organização de borda podem usar a Atualizar propriedades da organização para definir a propriedade feature.enableMultipleXForwardCheckForACL.

Veja no exemplo de API a seguir a propriedade no Edge para nuvem privada. Se houver outras propriedades definidas na organização, inclua também elas. Caso contrário, eles serão removidos.

curl -u email:password -X POST -H "Content-type:application/xml" http://host:8080/v1/o/myorg -d \
"<Organization type="trial" name="MyOrganization">
    <DisplayName>MyOrganization</DisplayName>
    <Properties>
        <Property name="feature.enableMultipleXForwardCheckForACL">true</Property>
        <!-- Include other existing properties as well. -->
    </Properties>
</Organization>"

No Edge for Private Cloud, depois de alterar o valor da propriedade feature.enableMultipleXForwardCheckForACL, você precisará reiniciar os processadores de mensagens, conforme descrito em Iniciar/parar/reiniciar componentes individuais para criar um anexo da VLAN de monitoramento.

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

O Edge 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 o Edge, use os valores nas dimensões ax_true_client_ip ou ax_resolved_client_ip. Consulte a referência de métricas, dimensões e filtros do Google Analytics para ver mais informações.

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:

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:

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 de elementos descreve os elementos e atributos da política de controle de acesso.

<?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"> 

A tabela a seguir descreve atributos comuns a todos os elementos pai de políticas:

Elemento <DisplayName>

Use em conjunto com o atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.

<DisplayName>Policy Display Name</DisplayName>

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>

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

Atributos

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>

Atributos

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.

Atributos

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. O lado mais à direita (ou último endereço IP) é o endereço recebido do último handshake de 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>

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 Edge 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 variables

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

Example fault response

{
   "fault":{
     "faultstring":"Access Denied for client ip : 52.211.243.3"
      "detail":{
         "errorcode":"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>