Sometimes you will find it necessary to limit access to your APIs from a specific network or computer. You might also need to identify specific IP addresses that cannot access your API, such as a network address that has been identified as a malicious actor.

Configuring access control based on IP addresses is a useful way to provide coarse-grained control. 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 (or whitelist) the IP address range for your internal network. Developers working from home can access these APIs using VPN.

Note: If you block a specific address, the computer using that IP address can still directs requests to your API through a proxy. It is also possible to spoof (falsify) the IP address of a request, so the request appears to come from a reputable source.

Apigee Edge enables you to attach an Access Control policy to your APIs (request path), where you can define a range of IPs and allow IPs within the specified range to access an operation or service.

The configuration and execution of an Access Control policy involves the following tasks:

  • Define a set of match rules with one of two actions (ALLOW or DENY) associated with each.
  • For each match rule, specify the IP address (SourceAddress element).
    • Configure a mask for each IP address. You allow or deny access based on a mask value on the IP address. For more information about IP addresses, see IP addresses and dotted notation.
    • If the X-FORWARDED-FOR header is present in the request address, then the header value is considered the source address.
  • Specify the order in which the rules are tested.
  • The system triggers the first matching rule in the ordered list, then subsequent matching 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.

Configuring an AccessControl policy

Configure the AccessControl policy using the following elements.

The name attribute for this policy is restricted to these characters: A-Z0-9._\-$ %. However, the Management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Field Name Description
noRuleMatchAction (Mandatory)
The action to take (allow or deny access) if the match rule specified is not resolved (unmatched).
Valid value: allow or deny
Default value: allow
MatchRule action (Mandatory)
The action to take (allow or deny access) if the match rule specified is resolved (matched).
Valid value: allow or deny
Default value: allow
SourceAddress (Optional)
The IP address range of a client.
Valid value: valid IP address (dotted decimal notation)

Examples - Access Control policy

The mask values in this table identify which of the four bytes (8, 16, 24, 32 bits) the match rule considers when allowing or denying access. The default value is 32. See IP addresses and dotted notation for more information.

Description Code Example
Deny all requests from client address: 10.10.10.10
Allow requests from any other client address.
<AccessControl name="ACL">
  <IPRules noRuleMatchAction="ALLOW">
    <MatchRule action="DENY">
      <SourceAddress mask="32">10.10.10.10</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>
Deny all requests from client address: 10.10.10.*
Allow requests from any other client address.
<AccessControl name="ACL">
  <IPRules noRuleMatchAction="ALLOW">
    <MatchRule action="DENY">
      <SourceAddress mask="24">10.10.10.10</SourceAddress>
    </MatchRule>
    </IPRules>
</AccessControl>
Deny all requests from client address: 10.10.*.*
Allow requests from any other client address.
<AccessControl name="ACL">
  <IPRules noRuleMatchAction="ALLOW">
    <MatchRule action="DENY">
       <SourceAddress mask="16">10.10.10.10</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>
Deny all requests from client address: 10.10.10.* except 10.10.10.20
Allow requests from any other client address.
<AccessControl name="ACL">
  <IPRules noRuleMatchAction="ALLOW">
    <MatchRule action="ALLOW">
      <SourceAddress mask="32">10.10.10.20</SourceAddress>
    </MatchRule>
    <MatchRule action="DENY">
      <SourceAddress mask="24">10.10.10.20</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>
Allow all requests from address: 10.10.*.*
Deny requests from any other client address.
<AccessControl name="ACL">
  <IPRules noRuleMatchAction="DENY">
    <MatchRule action="ALLOW">
      <SourceAddress mask="16">10.10.10.10</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>
Whitelist (allow requests from) client addresses: 10.10.20.* 10.10.30.* 10.10.40.*
Deny all other addresses.
<AccessControl name="ACL">
  <IPRules noRuleMatchAction="DENY">
    <MatchRule action="ALLOW">
      <SourceAddress mask="24">10.10.20.0</SourceAddress>
      <SourceAddress mask="24">10.10.30.0</SourceAddress>
      <SourceAddress mask="24">10.10.40.0</SourceAddress>
     </MatchRule>
  </IPRules>
</AccessControl>
Blacklist (deny requests from) client addresses: 10.10.20.* 10.10.30.* 10.10.40.*
Allow all other addresses.
<AccessControl name="ACL">
  <IPRules noRuleMatchAction="ALLOW">
    <MatchRule action="DENY">
      <SourceAddress mask="24">10.10.20.0</SourceAddress>
      <SourceAddress mask="24">10.10.30.0</SourceAddress>
      <SourceAddress mask="24">10.10.40.0</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>
Whitelist: 10.10.*.* 10.20.*.* 10.30.*.*
Blacklist a subset of the whitelist: 10.10.0.* 10.20.0.* 10.30.0.*
<AccessControl name="ACL">
  <IPRules noRuleMatchAction="DENY">
    <MatchRule action="DENY">
      <SourceAddress mask="24">10.10.0.0</SourceAddress>
      <SourceAddress mask="24">10.20.0.0</SourceAddress>
      <SourceAddress mask="24">10.30.0.0</SourceAddress>
    </MatchRule>
    <MatchRule action="ALLOW">
      <SourceAddress mask="16">10.10.0.0</SourceAddress>
      <SourceAddress mask="16">10.20.0.0</SourceAddress>
      <SourceAddress mask="16">10.30.0.0</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

IP addresses and dotted notation

An IPv4 address consists of four bytes (32 bits). These bytes are also known as octets. To aid with readability, humans typically work with IP addresses in dotted decimal notation. In this notation, there are periods between each of the four numbers (octets) that make up an IP address. For example, an IP address that computers see as:

00001010 00001010 00001010 00001010

is written in dotted decimal notation as 10.10.10.10

The mask value as shown in the examples above identifies which of the four bytes (8, 16, 24, 32 bits) the match rule considers when allowing or denying access.

Policy-specific error codes

The default format for error codes returned by Policies is:

{
  "code" : " {ErrorCode} ",
  "message" : " {Error message} ",
  "contexts" : [ ]
}

The AccessControl Policy type returns the following error codes:

Error Code Message
accesscontrol.ClientIpExtractionFailed Client IP extraction failed
IPDeniedAccess Access Denied for client ip : {0}
InvalidIPAddress {0} is not a valid IP address
InvalidIPv4Address {0} is not a valid IPv4 address
InvalidIPv6Address {0} is not a valid IPv6 address
InvalidRulePattern Invalid rule pattern {0}

Policy schema

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

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)