Access Restrictions and Trusted Proxy IPs

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

Access Restrictions

Access restrictions are configurable entities and contain up to 8 IPv4 IP addresses or CIDR blocks that specify the source IP addresses of the allowed clients. Only the global Org Owner can manage access restrictions in the organization, while other roles can neither edit nor view them.

The following rules apply to access restrictions:

Each access restriction can be applied to either one or both:
- API requests authenticated by API keys
- API requests 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 updating 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 restricted API access types (those authenticated by API Keys or those authenticated by user session tokens).

The Org Owners create and manage access restrictions in their organizations so that there are 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, a user has no access restriction 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 restriction.	`POST`	`/api/v2/orgs/<org_id>/access_restrictions`
Update an access restriction. Same schema as `POST`, but fields such as `name` or`ips` 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

Manage Access Restrictions

Create an 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 Access 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"
}
}

Trusted Proxy IPs

When a client is connected to the PCE 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 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 at the end of the list.

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. Using this setting, the Org Owner can designate the trusted proxies/intermediaries, and the PCE will consider all others 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`
Interservice 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 quer 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 `max_trusted_proxy_ips_per_region` property)	`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`	IPs or CIDRs trusted (per-region) for handling clients' X-Forwarded-For header; Required: `pce_fqdn`: FQDN of PCE region, or null if not in supercluster `ip:`IP address or CIDR trusted for handling the clients' header X-Forwarded-For	Yes

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

IPs or CIDRs trusted (per-region) for handling clients' X-Forwarded-For header;

Required:

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

ip:IP address or CIDR trusted for handling the clients' header X-Forwarded-For

Yes

Manage Trusted Proxy IPs

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

REST APIs for 23.5