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.

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.

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 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).
  • 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:

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

Atributo Descrição Padrão Presença
name

O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres.

Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.

N/A Obrigatório
continueOnError

Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas.

Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar.

falso Opcional
enabled

Defina como true para aplicar a política.

Defina como false para desativar a política. A política não será aplicada mesmo se ela permanecer anexada a um fluxo.

true Opcional
async

Esse atributo está obsoleto.

falso Obsoleto

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>
Padrão

N/A

Se você omitir esse elemento, será usado o valor do atributo name da política.

Presença Opcional
Tipo String

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

Atributos

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

Atributos

Atributo Descrição Tipo Padrão Presença
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
Presença Opcional
Tipo String (somente endereço IP único)

Atributos

Atributo Descrição Tipo Padrão Presença
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. 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>
Padrão X_FORWARDED_FOR_ALL_IP
Presença 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

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.

Código de falha Status HTTP Causa Correção
accesscontrol.IPDeniedAccess 403 O endereço IP do cliente, ou um endereço IP transmitido na solicitação de API, corresponde a um endereço IP especificado no elemento <SourceAddress> dentro do elemento <MatchRule> da política de controle de acesso e o atributo action do elemento <MatchRule> está definido como DENY.

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.

Variáveis Onde Exemplo
fault.name="fault_name" fault_name é o nome da falha, conforme listado na tabela Erros de ambiente 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 da política especificada pelo usuário que gerou a falha. acl.AC-AllowAccess.failed = true

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>