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 to 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. Use those credentials to make other API calls in the script, and then 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_3Your session token:
"session_token":"xxxxxxx563199f92af7b705ddca26854205b5233"
To use the Illumio REST API:
Call
login_users/authenticateusing 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/loginwith the authentication token to obtain temporary session credentials.
Use 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_3Session Token:
xxxxxxx563199f92af7b705ddca26854205b5233
curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/3/labels -H "Accept: application/json" -u user4:'xxxxxxxx628f5773c47b72dbcd437b4a10d85'
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
Login Service authentication token you obtained using the Login Users API.
Login Users API JSON Schema
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"
}
}
}
]
}
}