Manage client access using IP-based access control

There are many ways to approach access control for APIs. Of these, using OAuth or HTTP basic authentication is often sufficient (best used with SSL). But at times, it is important to limit access to your APIs from a specific network or computer. You might even need to identify specific IP addresses that cannot access your API under any circumstances, such as an address that submits malformed or malicious requests to your API.

You can deal with an attack by configuring access control for the IP address of the computer making the request, but this approach has limitations. 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.

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.

The API Platform 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 Access Control policy

Configure the Access Control policy using the following elements.

Policy schema

Each policy must conform to a policy schema. All policy constructs such as elements and attributes mentioned above are defined in a schema. To download the schema, click here.

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.

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

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

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

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

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

<AccessControl name="ACL">
    <IPRules noRuleMatchAction="/docs/DENY">
        <MatchRule action="/docs/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>

<AccessControl name="ACL">
    <IPRules noRuleMatchAction="/docs/ALLOW">
        <MatchRule action="/docs/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>

<AccessControl name="ACL">
    <IPRules noRuleMatchAction="/docs/DENY">
        <MatchRule action="/docs/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="/docs/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 comprise 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.