Skip to main content

REST APIs 25.3

Authentication

Before you can use the Illumio REST API to access the PCE, you need to use the Login Users API to authenticate with the Illumio Login Service and obtain an authentication token.

Authenticate to the Login Service

Before using the Illumio REST API to access the PCE, you need to use the Login Users API to authenticate with the Illumio Login Service and obtain an authentication token. This authentication token expires in 30 seconds.

The URL for the Illumio Login Service for Illumio Core Cloud users is:

  • Login Server: https://login.illum.io:443

  • PCE: scp1.illum.io

For SaaS customers, the PCE URL can be different based on their SaaS PCE:

  • SCP1 & SCP2 (US)

  • SCP3 UK only

  • SCP4 APAC

  • SCP5 (EMEA)

If you have deployed the PCE as software, then the hostname for the PCE is the value you defined for the 'pce_fqdn' parameter in the runtime_env.yml file.

Once obtained, you can pass the authentication token to the PCE you want to access using the Login API. Once you have authenticated with the PCE and received a session token, you can make additional API calls or create an API Key for persistent access to the PCE's API.

URI to Authenticate with the Login Service

POST [api_version]/login_users/authenticate
Create an Authentication Token for the Login Service

To create an authentication token and authenticate with the Login Service, you need to specify the Fully Qualified Domain Name (FQDN) of the PCE you want to access in the call.

Parameter

Description

Type

Required

pce_fqdn

Fully Qualified Domain Name (FQDN) of the PCE

If you are using Illumio Core Cloud, then the FQDN for the PCE is scp1.illum.io.

If you have deployed the PCE virtual appliance in your network, use the FQDN specified during installation.

String

Yes

Curl Commands for Authentication

When you received your invitation, you created your PCE account using an email and password. Use these credentials to make a call and authenticate now.

If you haven't received an invitation, contact your Illumio administrator.

Example (local users only, use SAML ID for remote users):

You also need the FQDN of the Login Server plus the FQDN of the PCE host you want to access:

  • The Login Server FQDN for Illumio Core Cloud users is https://login.illum.io:443

  • The PCE FQDN is scp1.illum.io

Note

The authorization token returned (auth_token) expires after 30 seconds of inactivity. Be ready to call GET users/login to create session credentials immediately after making the call to login_users/authenticate.

Optional Features

This API was introduced to help avoid issues with misconfigured DNS, which can cause problems with VEN connectivity. Likewise, misconfiguring DHCP can cause problems with IP addresses.

Invoke the Optional Features API

You need a key to invoke /optional_features API to enable editable_dns_client_rule or editable_dhcp_client_rule. Such a key involves a portion that is tightly controlled so that it cannot be randomly generated.

Once the key is generated, it cannot be used in more than one place. For example, an API call provided to customer #1 cannot be replayed at customer #2, who must request their key.

An example of the generated key:

secret = 
		'...'   # value embedded in code 
 
data = Base64.strict_encode64({ 
	'pce_fqdn'   => Illumio::RuntimeEnvironment.pce_fqdn, 
	'org_id'   => xorg_id, 
	'optional_feature'   => 
	'editable_dns_client_rule' , 
	'not_valid_after'   => Time.now.utc.iso8601 
}) 
 
key = data + OpenSSL::HMAC.hexdigest( 'SHA256' , secret, data)
Setting Optional Features

Analytics opt-out

The property configurable_label_dimension was added so that the UI users can determine if an organization has enabled user analytics.

Analytics is opt-in by default. If it has been disabled, the UI does not track analytics for that organization.

To set or clear the optional analytics feature, use:

{ 
name: "ui_analytics", enabled: false|true 
}

Illumination Classic opt-out

The property illumination_classic is added to enable or disable the use of that feature.

To set or clear the optional Illumination Classic feature, use:

{ 
name: "illumination_classic", enabled: false|true 
}
Label-Based Network Detection

The APIs

  • POST /api/v2/orgs/{org_id}/networks

  • PUT /api/v2/orgs/{org_id}/networks/:network_id

require that one of the following optional features is enabled :

  • label_based_network_detection

  • cidr_network_detection_enabled

In addition, both APIs are implementing input validation on payload content:

  • If the CIDRs field is provided, the optional feature cidr_network_detection_enabled must be set.

  • If the scopes field is provided, the optional feature label_based_network_detection must be enabled.

The example response for the API optional_features_put with the label_based_network_detection enabled:

"illumination_classic",
		"ransomware_readiness_dashboard",
		"per_rule_flow_log_setting",
		"lightning_default",
		"label_based_network_detection"
		]
	},
	"enabled": {
labels_editing_warning_for_enforcement_mode

In releases 23.2.10 and 23.4, for the required property name a new optional feature flag for label editing was added: labels_editing_warning_for_enforcement_mode.

To enable or disable this flag, use the following CURL command:

curl -u ${your_api_key}: ${your_api_secret} -H "Content-Type: application/json" -X PUT -d '[{"name":"labels_editing_warning_for_enforcement_mode","enabled":true}]' https://${your_pce_server}:8443/api/v2/orgs/${your_ord_id}/optional_features
windows_outbound_process_enforcement

In release 23.5, an optional feature flag for the Windows outbound process was added: windows_outbound_process_enforcement.

This feature flag can be enabled or disabled using the following CURL command:

curl -u ${your_api_key}: ${your_api_secret} -H "Content-Type: application/json" -X PUT -d '[{"name":"windows_outbound_process_enforcement","enabled":true}]' https://${your_pce_server}:8443/api/v2/orgs/${your_ord_id}/optional_features

where you can define the part of the command: "enabled":true or "enabled":false.

container_cluster_label_set_based_kubernetes_workload_instructions

This flag is enabled by default per organization.

When it’s enabled, PCE uses policy de-duplication for Kubernetes Workloads under CLAS Container Clusters. This means that we calculate only one workload instruction for every Kubernetes Workload with the same set of labels.

This reduces the number of calculated instructions in production by 70-95%, depending on the customer.

hybrid_policy

The property hybrid_policy activates the feature flag of the same name.

"properties": {
          "name": {
            "description": "Name of the feature",
            "type": "string",
            "enum": [
              "ip_forwarding_firewall_setting",
              "ui_analytics",
              "illumination_classic",
              "ransomware_readiness_dashboard",
              "per_rule_flow_log_setting",
              "lightning_default",
              "collector_scanner_filters",
              "corporate_ips_groups",
              "labels_editing_warning_for_enforcement_mode",
              "label_based_network_detection",
              "cloudsecure_enabled",
              "windows_outbound_process_enforcement",
              "rule_based_label_mapping",
              "core_insights",
              "rule_info_exposure_to_syslog",
              "hybrid_policy",
              "container_cluster_label_set_based_kubernetes_workload_instructions"

To see more details about using the feature flag hybrid_policy, see Hybrid Policy in the document What's New in release 25.2.10.

After hybrid policies are enabled, your on-premises and applicable cloud networks can use non-overlapping private IP subnets. Any policies between on-premises and cloud workloads are distributed to the appropriate on-premises workloads and cloud resources.

Hybrid policy support is available only to applicable customers.