REST APIs for 22.2

An auth_username and session token are useful for a one-time use of the API or for 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 for making other API calls in the script, and then once the script has run, the session token immediately expires when the user logs out.

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

To use the Illumio REST API:

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.

When you received your invitation, you used an e-mail and password to create your PCE account. Use these credentials now to make a call to authenticate.

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:

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

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.

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

GET /users/login returns a temporary auth_username and session_tokes shown below in blue. 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"
    }
}

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

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

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

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.

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, which means that an API call provided to customer #1 cannot be replayed at customer #2 who must request their own 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)

A new schema as well as two endpoints were added.

Get the optional features collection

Set the optional features for an organization

PUT /orgs/ 1 /optional_features 
[ 
    { "name" : 
        "editable_dns_client_rule,"enabled":true, key":<key as generated above>} 
]