Skip to main content

REST APIs 25.2.10

Access Restrictions and Trusted Proxy IPs

To employ automation for managing the PCE environment, you can use API Keys created by an admin user and automate the PCE management tasks. Illumio provides a way to restrict the use of these API keys by IP address, allowing you to block API requests from non-authorized IP addresses.

Access Restrictions

Access restrictions are configurable entities that contain a list of up to 8 IPv4 IP addresses or CIDR blocks, specifying the source IP addresses of allowed clients. Only the global Org Owner can manage access restrictions within the organization, while other roles are unable to edit or view them.

The following rules apply to access restrictions:

  • Each access restriction can be applied to either one or both:

    • API requests are authenticated by API keys

    • API requests are authenticated by Username/Password credentials

  • The global Org Owners can edit an access restriction after it has been created by modifying the allowed IP list or the options. They can also assign access restrictions to Local and External Users. The API supports the update of access restrictions for a list of users.

  • Access restrictions are leader-owned configuration objects that are replicated to all supercluster regions.

  • Access restrictions are enforced as follows:

    • To enforce an API request, determine the user account for that API request using the API key or the user session token, and then find the access restriction that is configured for that user. If no access restriction is assigned to the user, the API request proceeds.

    • If the client IP address for an API request does not satisfy the corresponding user's access restrictions, the request is rejected with a 401 error message.

    • Access restrictions are not enforced on some URLs (node_available, static JS/CSS content).

  • When a request is rejected due to unsatisfied access restrictions, it generates an Event that specifies a failure caused by an invalid source IP address, including the actual IP address and an appropriate error code (403).

Assignment to Users

Each Access Restriction is a configuration object that specifies a set of allow-list IP addresses or CIDR blocks, designating the allowed client IP address. It also specifies the types of API accesses that are restricted (those authenticated by API Keys or those authenticated by user session tokens).

The Org Owners create and manage access restrictions within their organizations, ensuring a maximum of 50 access restrictions per organization. The Org Owners can assign a single access restriction to each Local or External User (by default, no access restriction is assigned).

Access Restriction Methods

Functionality

HTTP

URI

Get a list of access restrictions.

GET

/api/v2/orgs/<org_id>/ access_restrictions

Get a specific access restriction.

Get

/api/v2/orgs/<org_id>/ access_restrictions/<id>

Create an access restrictio.n

POST

/api/v2/orgs/<org_id>/ access_restrictions

Update an access restriction.

Same schema as for POST,

but fields such as name orips might not be required

PUT

/api/v2/orgs/<org_id>/ access_restrictions/<id>

The DELETE endpoint should return an error.

if the specified access_restriction is referenced

by any User or Group.

The existing access_restrictions from all Users

and Groups must be removed before they can be deleted.

DELETE

/api/v2/orgs/<org_id>/ access_restrictions/<id>

Return Values for Access Restriction

These are the return values for the Access Restriction methods:

Property

Method

Description

Required

href

GET

URI of access restriction

Yes

name

GET, POST,

User assigned name of the access restriction

(No GET)(Yes POST)

description

GET, POST

User assigned description of the access restriction

No

ips

GET, POST

Array of ip addresses or CIDR blocks

Yes

enforcement_ exclusions

GET, POST

The types of API access methods that are excluded

from access restriction enforcement

No

Trusted Proxy IPs

When a client is connected to the PCE's haproxy server, this connection can traverse one or more load balancers or proxies. Therefore, the source IP address of a client connection to haproxy might not be the actual public IP address of the client.

Proxies and intermediaries often use the X-Forwarded-For header (and some other custom headers, like X-Client-IP) to pass along the client IP address. The value of this header is a comma-separated list of one or more IP addresses, where the source IP address seen by the most recent proxy is listed last.

The client IP address used for API requests and Web UI connections comes from the value of the X-Forwarded-For header that haproxy sets on the back-end request to the web service. It is set to one of these values:

  • Value of the X-Forwarded-For header on the incoming request (when trust_upstream_x_forwarded_for is true)

  • Source IP address of the client connection to haproxy (when trust_upstream_x_forwarded_for is false)

Configurable trusted proxy IPs allow Org Owners to configure a list of IPv4 addresses or CIDR blocks that are considered trusted for setting a client's X-Forwarded-For header.

The Org Owner can designate the trusted proxies/intermediaries using this setting. The PCE will consider all others to be untrusted when setting the X-Forwarded-For header.

The haproxy is configured to always put the client's source IP address in the X-Real-IP header on the back-end request and to pass along any X-Forwarded-For headers in the front-end request.

Trusted Proxy IP Methods

Functionality

HTTP

URI

Get a list of trusted IP proxies

GET

/api/v2/orgs/<org_id>/ settings/trusted_proxy_ips

Inter-service API for fetching an orgs' trusted_proxy_ips settings, so that it may be cached locally.

It uses the same schema as the GET endpoint above;

It receives the org_id as a query input

GET

/api/v2/org_trusted_ proxy_ips?org_id=<id>

Update trusted_proxy_ips settings for a given org,

with the same schema as the GET endpoint (except without the property)

max_trusted_proxy_ips_per_region

PUT

/api/v2/orgs/<org_id>/ settings/trusted_proxy_ips

Trusted Proxy IPs

These are the return values for the Trusted Proxy methods:

Parameter

Method

Description

Req

max_trusted_proxy_ ips_per_region

GET

Maximum number of Trusted Proxy IPs allowed for each PCE

Yes

trusted_proxy_ips

GET, PUT

Required:

pce_fqdn: FQDN of PCE region, or null if not in supercluster

ip:IP address or CIDR trusted for handling

Yes

Organization Access

Changes to the organization access introduced a new common schema:

common ipv4_ipv6_subnet

This common schema is replacing the one that is now deleted: common ipv4_subnet

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"type": "string",
	"pattern": "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.)
			{3}(25[0-5]|2[0-4][0-9]|[01]?[0-9]
                       [0-9]?)(\\/(3[0-2]|[0-2]?[0-9]))?$"
}

Three organization access APIs have been changed to substitute common/ipv4_subnet.schema with common/ipv4_ipv6_subnet.schema:

  • orgs_access_restrictions_post

  • orgs_access_restrictions_put

Access Restrictions Reference

This topic covers examples of access restriction.

Examples

Create Access Restrictions

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/1/access_restrictions/

Response

{
	"name": "sample Access Restriction payload",
	"description": "example",
	"ips": [ "192.168.33.1/16" ],
	"enforcement_exclusions": [ "user_sessions" ]
}

Read an Access Restriction

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/1/access_restrictions/

Update an Access Restriction

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/1/access_restrictions/1
{
	"name": "modified Access Restriction payload",
	"description": "example",
	"ips": [ "192.168.33.1/16" ],
	"enforcement_exclusions": [ "user_sessions" ]
}

Delete the Acess Restriction

curl -i -X DELETE https://pce.my-company.com:8443/api/v2/orgs/1/access_restrictions/1

Curl Command to associate an Access Restriction with an Org Auth Sec Principal (PUT)

curl -i -X -PUT https://pce.my-company.com:8443/api/v2/orgs/1/auth_security_principals/76a0607b-6961-4c74-a98a-8b10775c8a9b
{
	"name": "[email protected]",
	"display_name": "test",
	"type": "user",
	"access_restriction": {
	"href": "/orgs/1/access_restrictions/1"
}
}

Read a Trusted Proxy IP

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/1/access_restrictions/

Update a Trusted Proxy IP

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/1/settings/trusted_proxy_ips/
{
	"trusted_proxy_ips": [
		{
			"pce_fqdn": null,
			"ip": "66.151.147.0/24"
		},
		{
			"pce_fqdn": null,
			"ip": "192.168.34.0/24"
		}
	]
}
Organization Access

Changes to the organization access introduced a new common schema:

common ipv4_ipv6_subnet

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"type": "string",
	"oneOf": [
		{ "format": "ipv4" },
		{ "format": "ipv6" }
	]
}

This common schema is replacing the one that is now deleted: common ipv4_subnet

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"type": "string",
	"pattern": "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.)
			{3}(25[0-5]|2[0-4][0-9]|[01]?[0-9]
                       [0-9]?)(\\/(3[0-2]|[0-2]?[0-9]))?$"
}

Three organization access APIs have been changed to substitute

common/ipv4_subnet.schema with

common/ipv4_ipv6_subnet.schema:

  • orgs_access_restrictions_post

  • orgs_access_restrictions_put

{
	"properties": {
	    "ips": {
		"items": {
		    "$ref": {
			"__old": "../common/ipv4_subnet.schema.json",
                        "__new": "../common/ipv4_ipv6_subnet.schema.json"
		    }
		}
	     }
	}
}

settings_trusted_proxy_ips_put

{
	"properties": {
	    "trusted_proxy_ips": {
		"items": {
		    "properties": {
			"ip": {
			"$ref": {
			"__old": "../common/ipv4_subnet.schema.json",
                        "__new": "../common/ipv4_ipv6_subnet.schema.json"
		    }
		}
	    }
	}
    }