Política AccessControl

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

ícono de política

Qué

La política AccessControl te permite admitir o denegar el acceso a tus APIs según direcciones IP específicas.

Esta es una política estándar y se puede implementar en cualquier tipo de entorno. Para obtener información sobre los tipos de políticas y la disponibilidad con cada tipo de entorno, consulta Tipos de políticas.

Video: Mira un video breve para obtener más información sobre cómo permitir o denegar el acceso a tus API según direcciones IP específicas.

Si bien puedes adjuntar esta política en cualquier lugar del flujo de proxy de API, es probable que quieras verificar las direcciones IP al comienzo del flujo (solicitud/ProxyEndpoint/PreFlow), incluso antes de la autenticación o la verificación de cuotas.

También debes considerar usar Google Cloud Armor con Apigee como una forma alternativa de proteger tus API.

Muestras

Los valores de la máscara en las siguientes muestras de IPv4 identifican cuáles de los cuatro octetos (8, 16, 24, 32 bits) considera la regla de coincidencia cuando permite o rechaza el acceso. El valor predeterminado es 32. Consulta el atributo mask en la referencia de elemento para obtener más información.

Rechaza 198.51.100.1

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

Rechaza todas las solicitudes desde la dirección del cliente: 198.51.100.1

Permite solicitudes de cualquier otra dirección de cliente.

Denega con variables

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

Supongamos que usas un mapa de clave-valor (KVM) para almacenar valores de IP y enmascaramiento. Este es un enfoque útil para cambiar las IP y enmascarar durante el entorno de ejecución sin tener que actualizar y volver a implementar el proxy de API. Puedes usar la política KeyValueMapOperations para recuperar las variables que contienen los valores de kvm.mask.value y kvm.ip.value (si suponemos que las variables que nombraste en tu política de KVM contienen los valores de la máscara y los valores de IP del KVM). Si los valores que recuperaste eran 24 para la máscara y 198.51.100.1 para la dirección IP, la política AccessControl negaría todas las solicitudes de: 198.51.100.*

Todas las demás direcciones de cliente se permitirán.

Rechaza 198.51.100.*

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

Rechaza todas las solicitudes desde la dirección del cliente: 198.51.100.*

Permite solicitudes de cualquier otra dirección de cliente.

198.51.*.*

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

Rechaza todas las solicitudes desde la dirección del cliente: 198.51.*.*

Permite solicitudes de cualquier otra dirección de cliente.

Denega 198.51.100.*, permite 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>

Rechaza todas las solicitudes de la dirección del cliente: 198.51.100.*, pero permite 192.0.2.1.

Permite solicitudes de cualquier otra dirección de cliente.

Permite 198.51.*.*

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

Permite todas las solicitudes de la dirección: 198.51.*.*

Rechaza solicitudes de cualquier otra dirección de cliente.

Permite varias direcciones IP

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

Permite solicitudes de direcciones de cliente: 198.51.100.* 192.0.2.* 203.0.113.*

Rechazar todas las demás direcciones.

Rechaza varias IP

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

Rechaza solicitudes de direcciones de cliente: 198.51.100.* 192.0.2.* 203.0.113.*

Permite todas las demás direcciones.

Permite varias IP y rechaza varias IP

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

Permite: 198.51.*.* 192.0.*.* 203.0.*.*

Denega un subconjunto de la lista de permiso: 198.51.100.* 192.0.2.* 203.0.113.*

Notas de uso

Además de proteger tus API contra IP maliciosas, la política AccessControl también te permite controlar el acceso IP legítimo. Por ejemplo, si solo quieres que las computadoras bajo el control de tu empresa accedan a las API expuestas en tu entorno de pruebas, puedes permitir el rango de direcciones IP para la red interna. Los desarrolladores que trabajan desde casa pueden acceder a estas API mediante VPN.

La configuración y ejecución de una política de AccessControl incluye lo siguiente:

  • Define un conjunto de reglas de coincidencia con una de dos acciones (PERMITIR o RECHAZAR) asociadas con cada una.
  • Para cada regla de coincidencia, especifica la dirección IP (elemento SourceAddress).
  • Especifica el orden en el que se prueban las reglas.
  • Todas las reglas de coincidencia se ejecutan en el orden especificado. Cuando una regla coincide, se ejecuta la acción correspondiente y se omiten las siguientes reglas de coincidencia.
    • Si la misma regla se configura con acciones PERMITIR y RECHAZAR, la regla que se define primero en el orden se activa y se omite la regla posterior (con la otra acción).

Cómo elige la política qué direcciones IP se evaluarán

Las direcciones IP pueden provenir de varias fuentes en una solicitud. Por ejemplo, el encabezado del mensaje True-Client-IP puede contener una dirección IP, y el encabezado X-Forwarded-For puede contener una o más direcciones IP. En esta sección, se describe cómo configurar la política AccessControl para evaluar las direcciones IP exactas que deseas evaluar.

A continuación, se muestra la lógica que usa la política de AccessControl para decidir qué dirección IP evaluar:

1. Encabezado True-Client-IP

La política primero verifica si hay una dirección IP en el encabezado True-Client-IP. Si el encabezado contiene una dirección IP válida, la política la evalúa.

2. Encabezado X-Forwarded-For

Si no hay encabezado True-Client-IP o si configuró el elemento <IgnoreTrueClientIPHeader> verdadero, la política evalúa las direcciones IP en el X-Forwarded-For.

Apigee propaga automáticamente el encabezado X-Forwarded-For con la dirección IP que recibió del último protocolo de enlace TCP externo (como la IP de cliente o el router). Si existen varias direcciones IP en el encabezado, es probable que esas direcciones sean la cadena de servidores que procesaron una solicitud. Sin embargo, la lista de direcciones también puede contener una dirección IP de falsificación de identidad. ¿Cómo sabe la política qué direcciones debe evaluar?

Dimensiones X-Forwarded-For en las estadísticas de Apigee

Las estadísticas de Apigee escriben el valor del encabezado X-Forwarded-For en la dimensión x_forwarded_for_ip. Para determinar la IP de cliente que realizó la solicitud a Apigee, usa los valores de la dimensión ax_resolved_client_ip, pero excluye ax_true_client_ip, que no es compatible con la política AccessControl. Consulta Referencia sobre las métricas, las dimensiones y los filtros de Analytics.

Información acerca del enmascaramiento de IP con la notación de CIDR

La notación CIDR (enrutamiento entre dominios sin clases) es una forma de indicar un rango de direcciones IP a través del enmascaramiento. Se aplica a IPv4 y .IPv6 Así es cómo funciona. Usaremos IPv4 en nuestros ejemplos para simplificar.

Las direcciones IP son grupos de números separados por puntos. En términos binarios, cada grupo es una cantidad específica de bits (8 para IPv4 y 16 para IPv6). La dirección IPv4 198.51.100.1 se ve de esta manera en el objeto binario:

11000110.00110011.01100100.00000001

Son 4 grupos de 8 bits o 32 bits en total. Con CIDR, puedes indicar un rango si agregas un /number (1-32) a la dirección IP, de la siguiente manera:

198.51.100.1/24

En este caso, el valor 24 es el número que se usa para el valor del atributo mask en esta política.

Esta notación significa “mantiene los primeros 24 bits exactamente como están, los bits restantes pueden ser cualquier valor entre 0 y 255”. Por ejemplo:

Mantenlos tal como están Valores posibles para el último grupo
198.51.100. 0 - 255

Observa que la máscara ocurre al final del grupo tres. Esto hace que todo sea agradable y ordenado, en esencia mediante la creación de una máscara como esta: 198.51.100.* En la mayoría de los casos, el uso de múltiplos de 8 (IPv4) y de 16 (IPv6) te brindará el nivel de enmascaramiento que deseas:

IPv4: 8, 16, 24, 32

IPv6: 16, 32, 48, 64, 80, 96, 112, 128

Sin embargo, puedes usar otros números para un control más detallado, lo que implica un pequeño cálculo del objeto binario. A continuación, puedes ver un ejemplo con una máscara de 30, como en 198.51.100.1/30, en la que el último 1 es 00000001 en el objeto binario:

Mantenlos tal como están Valores posibles
11000110.00110011.01100100.000000 (primeros 30 bits) 00000000, 00000001, 00000010 o 00000011
198.51.100. 0, 1, 2 o 3

En este ejemplo, con la configuración establecida en <SourceAddress mask="30">198.51.100.1</SourceAddress>, se permitirán (o se rechazarán según tus reglas) las siguientes IP:

  • 198.51.100.0
  • 198.51.100.1
  • 198.51.100.2
  • 198.51.100.3

Referencia del elemento

En la referencia del elemento, se describen los elementos y atributos de la 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 una variable de flujo que contiene una dirección IP que la política verifica con las reglas IP. La política mostrará un error si la variable de flujo no contiene una dirección IP válida (ipv4 o ipv6).

Supongamos que la variable de flujo se configura como 12.31.34.52. En el siguiente ejemplo, se denegó el acceso. Si la variable se configura como 10.11.12.13, se otorga el acceso. 

<AccessControl name='ACL'>
   <ClientIPVariable>FLOW_VARIABLE</ClientIPVariable>
   <IPRules noRuleMatchAction = 'DENY'>
     <MatchRule action = 'ALLOW'>
       <SourceAddress mask='32'>10.11.12.13</SourceAddress>
     </MatchRule>
   </IPRules>
</AccessControl>
Predeterminado N/A
Presence Opcional
Tipo Variable de flujo

Elemento <IgnoreTrueClientIPHeader>

Cuando se establece esto como verdadero, la política ignora el encabezado True-Client-IP y evalúa las direcciones IP en el encabezado X-Forwarded-For, con el comportamiento de evaluación X-Forwarded-For que hayas configurado.

<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">
    <DisplayName>Access Control-1</DisplayName>
    <IgnoreTrueClientIPHeader>true</IgnoreTrueClientIPHeader>
    ...
</AccessControl>
Predeterminado false
Presence Opcional
Tipo Booleano

Elemento <IPRules>

El elemento superior que contiene las reglas que permiten o rechazan las direcciones IP. El atributo noRuleMatchAction te permite definir cómo manejar cualquier dirección IP que tus reglas coincidentes no cubran.

<IPRules noRuleMatchAction = "ALLOW">
Predeterminado N/A
Presence Opcional
Tipo N/A

Atributos

Atributo Descripción Tipo Predeterminado Presence
noRuleMatchAction
La acción a realizar (permitir o denegar el acceso) si no se resuelve la regla de coincidencia especificada (sin coincidencia).
Valor válido: PERMITIR o RECHAZAR
 String PERMITIR Obligatorio

Elemento <IPRules>/<MatchRule>

La acción que se debe tomar (permitir o denegar el acceso) si la dirección IP coincide con las SourceAddress que defines.

<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>
Predeterminado N/A
Presence Opcional
Tipo N/A

Atributos

Atributo Descripción Tipo Predeterminado Presence
acción

La acción a realizar (permitir o denegar el acceso) si no se resuelve la regla de coincidencia especificada (sin coincidencia).

Valor válido: PERMITIR o RECHAZAR

 String PERMITIR Obligatorio

Elemento <IPRules>/<MatchRule>/<SourceAddress>

El rango de direcciones IP de un cliente.

Valor válido: Dirección IP válida (notación decimal con puntos). Para el comportamiento comodín, usa el 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>

Como se muestra en el ejemplo anterior, el elemento SourceAddress también admite plantillas de mensajes para el atributo mask o la dirección IP, lo que significa que puedes establecer los valores que usan variables que están disponibles actualmente en el flujo del proxy de API.

Por ejemplo, puedes almacenar una dirección IP en un mapa de valor clave (KVM) y usar la política KeyValueMapOperations para recuperar la dirección IP y asignarla a una variable (como kvm.ip.value). Luego, podrás usar esa variable para la dirección IP:

<SourceAddress mask="24">{kvm.ip.value}</SourceAddress>

Configura la máscara o la dirección IP con una variable te brinda la flexibilidad para cambiar los valores en el entorno de ejecución sin tener que modificar y volver a implementar el proxy de API

Predeterminado N/A
Presence Opcional
Tipo String (solo la dirección IP única)

Atributos

Atributo Descripción Tipo Predeterminado Presence
máscara

El atributo mask es una forma de indicar el rango de direcciones IP que deseas permitir o rechazar. La máscara equivale a usar la notación de CIDR (enrutamiento entre dominios sin clases). Por ejemplo:

<SourceAddress mask="24">198.51.100.1</SourceAddress>

es equivalente a la siguiente notación de CIDR:

198.51.100.1/24

Valores válidos:

IPv4: 1-32

IPv6: 1-128

Un valor de cero (0) solo es válido para la IP 0.0.0.0, por lo que no es práctico.

Configura la máscara con una variable

El atributo mask también admite plantillas de mensajes, lo que significa que puedes establecer el valor con una variable que actualmente está disponible en el flujo del proxy de API. Por ejemplo, puedes almacenar un valor de máscara en un KVM y usar la política KeyValueMapOperations para recuperar la máscara y asignarla a una variable. Para establecer la máscara de IP con la variable, usa el siguiente formato, si suponemos que la variable se llama kvm.mask.value:

mask="{kvm.mask.value}"

 Entero N/A Obligatorio

Elemento <ValidateBasedOn>

Cuando el encabezado HTTP X-Forwarded-For contiene varias direcciones IP, usa este elemento ValidateBasedOn para controlar qué direcciones IP se evalúan.

Usa este enfoque para evaluar una dirección IP solo si estás seguro de la validez de las direcciones IP que deseas evaluar. Por ejemplo, si eliges evaluar todas las direcciones IP en el encabezado X-Forwarded-For, debes poder confiar en la validez de esas direcciones o configurar las reglas DENY o ALLOW para permitir que solo las IP de confianza llaman al proxy de API.

La dirección IP que se encuentra más a la izquierda del encabezado pertenece al cliente, y la que está más a la derecha es el servidor que reenvió la solicitud al servicio actual. La dirección IP más a la derecha o la última es la dirección que recibió Apigee del último protocolo de enlace TCP externo.

El valor que ingreses en este elemento te permite determinar si se deben verificar todas las direcciones IP en el encabezado (predeterminado), solo la primera dirección IP o solo la última dirección 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>
Predeterminado X_FORWARDED_FOR_ALL_IP
Presence Opcional
Valores válidos

X_FORWARDED_FOR_ALL_IP (predeterminada)

X_FORWARDED_FOR_FIRST_IP

X_FORWARDED_FOR_LAST_IP

Esquemas

Un esquema XML (.xsd) define cada tipo de política. Como referencia, los esquemas de políticas están disponibles en GitHub.

Referencia de errores

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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 code HTTP status Cause Fix
accesscontrol.IPDeniedAccess 403 The client IP address, or an IP address passed in the API request, matches an IP address specified in the <SourceAddress> element within the <MatchRule> element of the Access Control Policy, and the action attribute of the <MatchRule> element is set to DENY.
accesscontrol.InvalidIPAddressInVariable 500 The flow variable in <ClientIPVariable> contains an invalid IP address.

Fault variables

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

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "IPDeniedAccess"
acl.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. acl.AC-AllowAccess.failed = true

Example fault response

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