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

Nesta seção, descrevemos os códigos e as mensagens de erro retornados e as variáveis de falha definidas pelo Edge quando a política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

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

Variáveis de falha

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

Exemplo de resposta com falha

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