This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

The AccessControl policy lets you allow or deny access to your APIs by specific IP addresses.

While you can attach this policy anywhere in the API proxy flow, you'll most likely want to check IP addresses at the beginning of the flow ( Request / ProxyEndpoint / PreFlow), even before authentication or quota checking.

Also consider usingGoogle Cloud Armor with Apigee as an alternative way to secure your APIs.

This policy is aStandard policy and can be deployed to any environment type. For information on policy types and availability with each environment type, seePolicy types.

Samples

The mask values in the following IPv4 samples identify which of the four octets (8, 16, 24, 32 bits) the match rule considers when allowing or denying access. The default value is 32. See themask attribute in the Element reference for more information.

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

Usage notes

In addition to protecting your APIs against malicious IPs, the AccessControl policy also gives you control over legitimate IP access. For example, if you only want computers under the control of your enterprise to access the APIs exposed in your test environment, you can allow the IP address range for your internal network. Developers working from home can access these APIs using VPN.

The configuration and execution of an AccessControl policy involves the following:

• Define a set ofmatch rules with one of two actions (ALLOW or DENY) associated with each.
• For each match rule, specify the IP address (SourceAddress element).
  • SeeHow the policy chooses which IP address to evaluate to determine which IP address(es) in the message you're configuring rules to handle.
  • Configure a mask for each IP address. You allow or deny access based on a mask value on the IP address. SeeAbout IP masking with CIDR notation.
• Specify the order in which the rules are tested.
• All the match rules are executed in the given order. When a rules matches, the corresponding action is executed and following match rules are skipped.
  • If the same rule is configured with both ALLOW and DENY actions, the rule that is defined first in the order is triggered and the subsequent rule (with the other action) is skipped.

Handling of invalid IP addresses

The AccessControl policy handles invalid IP address strings passed as variables differently from invalid strings parsed through headers.

• Header-Based (no<ClientIPVariable>): When the policy directly parses theX-Forwarded-For (XFF) header, any non-IP string (for example,pwned) in the header being evaluated is silently ignored. The policy proceeds as if the IP address string did not match any rule, and the action specified by<noRuleMatchAction> is taken. This can be a security concern if<noRuleMatchAction> is set toALLOW, as it could be used to bypassblocklist rules.
• Variable-Based (<ClientIPVariable> is used): If a variable specified in<ClientIPVariable> contains an invalid IP address format, the policy will throw an error (for example,accesscontrol.InvalidIPAddressInVariable). This provides a more explicit failure and is the recommended approach for stricter IP validation.

How the policy chooses which IP address to evaluate

IP addresses can come from various sources in a request. For example, theX-Forwarded-For header may contain one or more IP addresses. This section describes how to configure the AccessControl policy to evaluate the exact IP address(es) you want it to evaluate.

Following is the logic the AccessControl policy uses to decide which IP address to evaluate:

X-Forwarded-For header

Apigee automatically populates theX-Forwarded-For header with the IP address it received from the last external TCP handshake (such as the client IP or router). If there are multiple IP addresses in the header, those addresses are likely the chain of servers that processed a request. However, the list of addresses could also contain a spoofed IP address. So how does the policy know which addresses to evaluate?

Apigee specification for XFF header behavior

In Apigee, the presence of Google Cloud Load Balancers (GCLBs) affects the structure of theX-Forwarded-For (XFF) header. The typical format of the header is as follows:

Apigee Analytics writes the value of theX-Forwarded-For header to thex_forwarded_for_ip dimension. To determine the client IP that made the request to Apigee, use the values in theax_resolved_client_ip dimension butexcludeax_true_client_ip, which is not supported with the AccessControl policy. SeeAnalytics metrics, dimensions, and filters reference.

About IP masking with CIDR notation

CIDR notation (Classless Inter-Domain Routing) is a way of indicating a range of IP addresses through masking. It applies to both IPv4 and IPv6. Here's how it works. We'll use IPv4 in our examples for simplicity.

IP addresses are groups of numbers separated by periods. In binary terms, each group is a specific number of bits (8 for IPv4 and 16 for IPv6). The IPv4 address 198.51.100.1 looks like this in binary:

11000110.00110011.01100100.00000001

That's 4 groups of 8 bits, or 32 total bits. With CIDR, you can indicate a range by adding a /number (1-32) to the IP address, like this:

198.51.100.1/24

In this case, the 24 is the number you would use for themask attribute value in this policy.

This notation means, "Keep the first 24 bits exactly as is, the remaining bits can be any value 0 through 255." For example:

Notice that the mask happens at the end of group three. This makes things nice and tidy, in essence creating a mask like this: 198.51.100.*. In most cases, using multiples of 8 (IPv4) and 16 (IPv6) will give you the masking level you want:

IPv4: 8, 16, 24, 32

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

However, you can use other numbers for finer-grained control, which involves a little binary calculation. Here's an example using a mask of 30, as in198.51.100.1/30, where the last 1 is 00000001 in binary:

In this example, with the configuration set to<SourceAddress mask="30">198.51.100.1</SourceAddress>, the following IPs would be allowed (or denied, depending on your rules):

• 198.51.100.0
• 198.51.100.1
• 198.51.100.2
• 198.51.100.3

Element reference

The element reference describes the elements and attributes of the AccessControl policy.

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

<AccessControl> attributes

<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">

<ClientIPVariable> element

Specifies a flow variable containing an IP address that the policy checks against the IPRules. If the flow variable does not contain a valid IP address (ipv4 or ipv6), then the policy throws an error.

Suppose the flow variable is set to the12.31.34.52. In the following example, access is denied. If the variable is set to10.11.12.13, access is granted.

<AccessControl name='ACL'>   <ClientIPVariable>FLOW_VARIABLE</ClientIPVariable>   <IPRules noRuleMatchAction = 'DENY'>     <MatchRule action = 'ALLOW'>       <SourceAddress mask='32'>10.11.12.13</SourceAddress>     </MatchRule>   </IPRules></AccessControl>

<IgnoreTrueClientIPHeader> element

<IPRules noRuleMatchAction = "ALLOW">

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

<IPRulesnoRuleMatchAction="ALLOW"><MatchRuleaction="ALLOW"><SourceAddressmask="{variable}">198.51.100.1</SourceAddress></MatchRule><MatchRuleaction="DENY"><SourceAddressmask="24">{variable}</SourceAddress></MatchRule></IPRules>

As shown in the previous example, theSourceAddress element also supportsMessage templates for themask attribute or IP address, whichmeans you can set the values using variables that are currently available in theAPI proxy flow.

For example, you can store an IP address in a key value map (KVM) and use theKeyValueMapOperations policy to retrieve the IP address and assign it to a variable (such askvm.ip.value). You can then use that variable for the IP address:

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

Setting mask and/or IP address with a variable gives you the flexibility to change values atruntime without having to modify and re-deploy your API proxy.

Attributes

<ValidateBasedOn> element

When theX-Forwarded-For HTTP header contains multiple IP addresses, use thisValidateBasedOn element to control which IP addresses are evaluated.

Use this approach to evaluating a IP addresses only if you're certain about the validity of the IP addresses you want to evaluate. For example, if you choose to evaluate all IP addresses in theX-Forwarded-For header, you have to be able to trust the validity of those addresses, and/or set up comprehensive DENY or ALLOW rules to let only trusted IPs call your API proxy.

The leftmost IP address in the header belongs to the client, and the rightmost is the server which forwarded the request to the current service. The rightmost, or last IP address, is the address Apigee received from the last external TCP handshake.

The value you enter in this element lets you determine whether to check all IP addresses in the header (default), only the first IP address, or only the last IP address.

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

Schemas

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.

Error reference

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, seeWhat you need to know about policy errors andHandling 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, seeVariables specific to policy errors.

Example fault response

{   "fault":{     "faultstring":"Access Denied for client ip : 52.211.243.3"      "detail":{         "errorcode":"steps.accesscontrol.IPDeniedAccess"      }   }}

<FaultRule name="IPDeniedAccess">    <Step>        <Name>AM-IPDeniedAccess</Name>        <Condition>(fault.name Matches "IPDeniedAccess") </Condition>    </Step>    <Condition>(acl.failed = true) </Condition></FaultRule>