Esta página aplica-se ao Apigee e ao Apigee Hybrid.
Veja a documentação do
Apigee Edge.
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).
- Consulte o artigo Como a política escolhe o endereço IP a avaliar para determinar que endereços IP na mensagem está a configurar regras para processar.
- Configure uma máscara para cada endereço IP. Permite ou nega o acesso com base num valor de máscara no endereço IP. Consulte o artigo Acerca da ocultação de IP com a notação CIDR.
- 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çalhoX-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 regrasblocklist
. - 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
é 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
|
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 |
|
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 . |
build |
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>