Session Credentials

While API keys provide a persistent means of authenticating with the PCE, session credentials provide a temporary means of authenticating so you can make Illumio REST API calls.

Important

Any tooling that parses the HTTP headers should be changed to allow case-insensitive header name matching and remain compatible with future PCE releases. For more information, refer to RFC 7230, section 3.2, "Header Fields," which states that field names should be case-insensitive.

Choose a session token or an API key, depending on your programming needs.

Session Credentials and Tokens

When you create session credentials, an auth_username and session token are returned, which function as temporary usernames and passwords for making API calls.

Session credentials are used to make all Illumio REST API calls that require authentication and are composed of an auth_username and a token. They expire after not being used for 30 minutes and reset for another 30 minutes if used within the 30-minute window.

The session token expires after 10 minutes of inactivity.

When to Use a Session Token

An auth_username and a session token are useful for one-time use of the API or testing the API. To write a script that performs a one-time use of the API with a session token, use the Login API to create the auth_username and session token. Then, use those credentials to make other API calls in the script. Once the script has run, the session token immediately expires when the user logs out.

What Does a Session Token Look Like?

When you authenticate with the PCE using the Login API, the response returns the credentials needed to make other API calls:

Your username: "auth_username": user_3
Your session token: "session_token":"xxxxxxx563199f92af7b705ddca26854205b5233"

To use the Illumio REST API:

Call login_users/authenticate using the e-mail address and password you used to create your PCE account to obtain an authentication token.
Note
The authorization token expires after 30 seconds, so have the next call formed and ready to paste onto the terminal window before calling login_users/authenticate.
Call users/login with the authentication token to obtain temporary session credentials.

Use the Login API to Create Session Credentials

Unless you're using persistent API credentials, whenever you want to access the Illumio REST API, you must authenticate with the PCE using an auth username and a session token. To create these session credentials, call GET /users/login with the authentication token previously returned by a call to POST /login_users/authenticate.

URI

GET [api_version]/users/login

API Call Using Session Credentials

Once you obtain an auth_username and session token from the PCE, you use them to make API calls.

For example, suppose you want to use this session token to get a collection of labels in an organization using the Labels API. In that case, the curl command can be written as shown below using the following authentication:

auth_username: user_3
Session Token: xxxxxxx563199f92af7b705ddca26854205b5233

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/3/labels -H "Accept: application/json" -u user4:'xxxxxxxx628f5773c47b72dbcd437b4a10d85'

No Log Rules

The No Log Rules feature reduces data volume (and cost) by ignoring traffic not worth inspecting from a security perspective, like 443/80 from the internet to public-facing web servers.

The No Log Rules feature enables you to mark rules as "no log," meaning any flows matching those rules will not be logged in the vTap logs on the VEN and will not be reported to the PCE.

To use this feature, you need to enable the flag:

[{ "name": "per_rule_flow_log_setting", "enabled": true }]

Implementing the No Log Rules Feature

To implement the No Log Rules feature, follow these steps:

Enable the flag per_rule_flow_log_setting by setting it to true.
Write segmentation rules for the flows you want to allow without logging.
Use the API to flip the property log_flow on these rules.

When using the No Log Feature:

In cases where "regular" and "no log" rules overlap, the "no log" rule will always be evaluated first, and the flows will not be logged.
These rules will only be sent to VENs 22.5.0 or newer.
If the feature flag is disabled, the "log_flow" property will not be returned in the API responses, and it will not be possible to set the property using the API.
There is currently no UI support for this feature, so there will be no visual indication that the rules are set to "log_flow: false."

Enabling the Feature Flag

To enable the No Log feature flag, execute the cURL command:

curl -X PUT -u $API_USER:$API_PASS -H 'Content-type: application/json' --data-raw '[{"name": "per_rule_flow_log_setting", "enabled": true}]' $PCE_URL/api/v2/orgs/1/optional_features

Verify that the flag was enabled:

curl -u $API_USER:$API_PASS $PCE_URL/api/v2/orgs/1/optional_features | jq '.' | grep "per_rule_flow_log_setting" -C

If the commands were successful, you will see the following:

{    
    "name": "per_rule_flow_log_setting",    
    "enabled": true  
},

Writing Segmentation Rules

When writing rules to implement the No Log Rules feature, do not provision them immediately.

You might create a separate ruleset for these rules and clarify that these are No Log Rules in the name because there is currently no UI indication of whether or not the flag is enabled on the rules.

Once you've created the rules, you must get the rule HREFs. You can do that by making an API call to the rule sets API for this rule set or using the developer console.

Disabling Flow Logging

Disable flow logging for the given rule by making a PUT request to the sec_rules API with the property llog_flow set to false.

Execute a cURL and an HREF:

curl -X PUT -u $API_USER:$API_PASS -H 'Content-type: application/json' --data-raw '{ "log_flow": false }' $PCE_URL/api/v2/orgs/1/sec_policy/draft/rule_sets/3/sec_rules/

Use a GET command to verify that the property is now false.

curl -u $API_USER:$API_PASS -H 'Content-type: application/json' $PCE_URL/api/v2/orgs/1/sec_policy/draft/rule_sets/3/sec_rules/3 | jq '.'

Provision the ruleset, and the No Log rules will be sent to the relevant VENs.

Showing Rule ID in Syslog

For large customers handling 10K+ messages per second, including rule IDs in the Syslog events will substantially increase the volume of recorded data.

New Feature: Added the organization-level feature flag rule_info_exposure_to_syslog (disabled by default) in release 25.1.0. This flag controls whether rule ID information is included in syslog messages.

Adding the Rule ID to Syslog Events

To add the rule IDs to the syslog events, the API optional_features was changed by adding the new property rule_info_exposure_to_syslog:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "oneOf": [
      {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "enabled"
        ],
        "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"
            ]
  ==============================================

To enable this feature flag, set the firewall_settings.enable_all_rule_hit_count_enabled option. This will instruct the VEN to send the rule IDs and the traffic flow payload to the PCE.

PUT /api/v2/orgs/:org_id/optional_features
payload
[  
    {    
        "name":"rule_info_exposure_to_syslog",    
        "enabled":*true*  
    }
]

Enabling the Rule Data

Before implementing the property rule_info_exposure_to_syslog , you must update the firewall settings and set the flag enable_all_rule_hit_count_enabled=true;.

This can be done using the API or the PCE console.

Setting the flag via the PCE console is explained in Events Administration Guide.

To set the flag enable_all_rule_hit_count_enabled via API, use the following command:

curl -u api_${ILO_API_KEY_ID}:${ILO_API_KEY_SECRET} -H "Content-Type: application/json" -X PUT -d '{"rule_hit_count_enabled_scopes": [[]]}' https://${ILO_SERVER}/api/v2/orgs/${ILO_ORG_ID}/sec_policy/draft/firewall_settings

Session Credentials Reference

This topic provides examples of session credentials use.

Examples

Retrieve a Token

This curl example shows how SaaS local users can use the Illumio Login Service (SAML ID for Remote Users)

curl -i -X POST https://login.illum.io:443/api/v2/login_users/authenticate?pce_fqdn=scp1.illum.io -u [email protected]:'password' -H "Content-Type: application/json"

Illumio on-premises solutions do not use a login server, so the curl command will look like this:

curl -i -X POST -u [email protected]:password https://pce.my-company.com:8443/api/v2/login_users/authenticate?pce_fqdn=pce.my-company.com -H "Content-Type: application/json"

Response Body to Authenticate with Login Service

The response for the Login Users API is an authentication token (in blue font):

{ "auth_token":"xxxxxxxxxxxxxxxxxxxxxw89QutJ5WLntqz5jUrI2guA1rZJXKfcbwuF" }

Parameters to create session credentials

This API uses the Illumio Core schema users_login_get.schema.json.

Create Session Token

curl -i -X GET https://pce.my-company.com:8443/api/v2/users/login -H "Authorization: Token token=ntqz5jUrI2guA1XzUiLCJlbmMiOiJBMTI4Q0JDLUhZJ"

Response Body

GET /users/login returns a temporary auth_username and session_token.

These are used in the curl examples as $KEY:$TOKEN respectively (if you're not using persistent API credentials).

Example: -u user_4:'xxxxxxxx628f5773c47b72dbcd437b4a10d85a06a'

{
    "full_name": "Buford T. Justice",
    "local": true,
    "type": "local",
    "href": "/users/4",
    "auth_username": "user_4",
    "inactivity_expiration_minutes": 10,
    "start": "2017-10-12 16:49:49 UTC",
    "time_zone": "America/Los_Angeles",
    "last_login_ip_address": "209.37.96.18",
    "last_login_on": "2020-10-12T16:49:49.000Z",
    "certificate": {
        "expiration": "2020-11-27T03:09:00.000Z",
        "generated": false
    },
    "login_url": "https://devtest166.ilabs.io:8443/login",
    "orgs": [
        {
            "org_id": 1,
            "org_href": "/orgs/1",
            "display_name": "illum.io",
            "role_scopes": [
                {
                    "role": {
                        "href": "/orgs/1/roles/owner"
                    },
                    "scope": [],
                    "href": "/orgs/1/users/4/role_scopes/4"
                }
            ]
        }
    ],
    "session_token": "xxxxxxxx628f5773c47b72dbcd437b4a10d85a0",
    "version_tag": "60.1.0-9701f78bef46f521e3d6dd98f70cd8c220940885",
    "version_date": "Tue Sep 12 11:12:46 2020 -0700",
    "product_version": {
        "version": "17.1.1",
        "build": "6168",
        "long_display": "17.1.1-6168",
        "short_display": "17.1.1"
    }
}

Optional Feature Schema: optional_feature.schema.json

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"type": "object",
	"additionalProperties": false,
	"description": "PCE Feature",
	"required": [
		"name",
		"enabled"
		],
	"properties": {
		"name": {
			"type": "string",
			"description": "The name of the feature"
		},
		"preview": {
			"type": "boolean",
			"description": "Is this a preview feature"
		},
		"enabled": {
			"type": "boolean",
			"description": "Is this feature enabled"
		}
	}
}

Get the optional features collection: optional_features_get

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"type": "array",
	"items": {
			"$ref": "optional_feature.schema.json"
		}
	}

Set the optional features for an organization: optional_features_put

The example shows the properties available in the release 24.1.1, which includes the property rule_based_label_mapping.

This property was added to support the new APIs presented in Rule-Based Label Mapping.

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "array",
    "items": {
	   "oneOf": [
		{
		"type": "object",
		"additionalProperties": false,
		"required": [
		    "name",
		    "enabled"
		],
		"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"
			]
		},
		"enabled": {
		    "description": "Enable or disable this feature",
		    "type": "boolean"
		}
	   }
	},
	{
	    "type": "object",
	    "additionalProperties": false,
	    "required": [
	        "name",
		"enabled"
	    ],
	    "properties": {
		"name": {
		    "description": "Name of the feature",
		    "type": "string",
		    "enum": [
			"editable_dns_client_rule",
			"editable_dhcp_client_rule"
		    ]
		},
		"enabled": {
		    "description": "Enable or disable this feature",
		    "type": "boolean"
		},
		"key": {
		    "description": "Key required to enable the feature. Contact Illumio Support for more details.",
				"type": "string"
			    }
			}
		    }
		]
	    }
	}

Illumio REST APIs 25.4