Overview

REST methods determine the HTTP method for manipulating the resources defined in the service operation. The kind of operations available include those predefined by the HTTP verbs GET, POST, PUT, DELETE and so on. The response may confirm that some alteration has been made to the stored resource, and it may provide hypertext links to other related resources or collections of resources. By making use of a stateless protocol and standard operations, REST systems aim for fast performance, reliability, and the ability to grow, by re-using components that can be managed and updated without affecting the system as a whole, even while it is running.

REST API Support for Ivanti Connect Secure/Ivanti Policy Secure involves only Configuration APIs. Also, Ivanti Connect Secure/Ivanti Policy Secure supports only the GET, POST, PUT and DELETE APIs. Ivanti qualifies REST API queries through Postman or Curl commands only.

The valid and supported values are described in the following Valid and Supported Values table:

HTTP Verb

Definition

DELETE

Delete an existing resource.

GET

Retrieve a representation of a resource.

POST

Create a new resource

PUT

Create a new resource to a new URL or modify an existing resource to an existing URL.

The error codes supported are described in the following Error Codes Supported table:

HTTP Verb

Definition

200 OK

Requesting for resource information successful using GET

Resource update successful using PUT

201 Created

Resource creation successful using POST

204 No Content

Deletion of resource successful with no body. Even PUT, POST may return 204 if no errors or warnings seen

400 – Bad Request 

 

 

 

 

Any Request (GET/PUT/POST/DELETE, and so on) is invalid.

Example: Incorrect JSON format

401 – Unauthorized

Any REST Call with invalid credentials

403 – Forbidden

REST Call with valid credentials but no permission

404 – Not found

Requested resource in URI does not exist

422 – Unprocessable Entity

Any validation/referential integrity errors that would result in failure of PUT/POST/DELETE request

500 Server Error

When Ivanti Connect Secure/Ivanti Policy Secure rest server is not responding

URL Encoding

A URL can be from a limited set of characters belonging to the US-ASCII character set. Characters outside these character set are not allowed to be placed directly within URLs, but their encoded value preceded by % can be used in the URLs.

The following table demonstrates URL Encoding:

Character

URL Encoding

(UTF-8)

<space>

%20

#

%23

$

%24

%

%25

&

%26

*

%2A

/

%2F

@

%40

\

%5C

Example:

•To get active session details of user "admin user"

curl -k -u <api-key>: https://<ICS-ip>/api/v1/system/activeusers?name= admin%20user

•To get active session details of user "admin@user"

curl -k -u <api-key>: https://<ICS-ip>/api/v1/system/activeusers?name= admin%40user

For more details, refer https://www.urlencoder.io/learn/.

Authentication for REST APIs

Basic authentication using the HTTP authorization header is used to authenticate username/password on the Administrators auth. server. It is expected that the user is already configured in the Administrators auth. server. On a successful login, a random token (api_key) is generated once and sent back as a JSON response. Further access to APIs can use this api_key value as username and password as empty in their Authorization header for access.

A new random api_key is generated on a successful login. The user can continue to use this key till the administrator:

•Enables/disables the user account

•Enables/disables the Allow REST API feature for that user

Basic Authentication using the HTTP Authorization Header

Configurations for REST APIs

The configuration of Ivanti Connect Secure/Ivanti Policy Secure can be accessed using REST APIs. The Ivanti Connect Secure/Ivanti Policy Secure configuration is represented in a json form when accessed using REST APIs. The structure of the JSON representation is very similar to the structure of Ivanti Connect Secure/Ivanti Policy Secure XML configuration.

A new admin UI option for users under "Administrators" authserver has been added. REST API authentication would be successful only for those users who have this option enabled.

REST API access can be enabled from Ivanti Connect Secure Admin console as shown below or from Ivanti Connect Secure serial console.

To enable this check box in Ivanti Connect Secure Admin Console:

1.Go to Authentication > Auth. Servers >Administrators > Update Administrator admin1.

2.Select the Allow access to REST APIs check box. See figure below.

3.Click Save Changes.

Enabling REST API Access for an Administrator from the Serial Console

REST API access for an administrator user can be enabled during initial configuration and while creating a new administrator user.

Ivanti recommends using realm-based authentication with an option to choose a different auth server for Admin realm to log in to use REST API.

During initial provisioning, there are no administrator accounts configured and the system prompts to create a new administrator user. For the option "Do you want to enable REST API access for this administrator (y/n):", enter y.

Any characters other than "y" or "n" are invalid responses.

When creating a new administrator user from the console using the option "2. Create admin username and password", for the option "Do you want to enable REST API access for this administrator (y/n):", enter y.

The entire communication is over TLS. An example is explained below:

Request

GET /api/v1/auth HTTP/1.1

Host: 10.209.112.106

Authorization: Basic YWRtaW5kYjpkYW5hMTIz

Content-Type: application/json

Response

HTTP/1.1 200 OK

Content-Type: application/json

Expires: -1

Keep-Alive: timeout=15

{ "api_key": "p5mMlc7RQu81R2NvssLCCZhP05kf0N2ONFeYeLXX6aU=" }

Equivalent Curl Command

While using curl command, ensure appropriate server CA certs is installed in the cert store recognized by curl. The sample curl commands provided in this document assumes you have appropriate server CA certs installed.

Command

curl -i -u admindb:dana123 -G https://<hostname>/api/v1/auth

Response

HTTP/1.1 200 OK

Content-Type: application/json

{"api_key":"p9/h85ytEmkDzvkGSmQ4z77p6Ya7aLIC42vh0F9CGaQ="}

 

api_key received in response to authentication request should be used as Username with EMPTY password in all future requests. Refer to the examples in Sample GET/POST/PUT/DELETE Request and Responses in ICS.

Realm-based Authentication (Recommended)

Ivanti recommends realm-based authentication instead of basic authentication using the HTTPS authorization header.

Request

POST /api/v1/realm_auth HTTP/1.1

Host: 10.209.116.214

Content-Type: application/json

Authorization: Basic YWRtaW46ZGFuYTEyMw==

{

  "realm": "adminrealm"

}

Response

HTTP/1.1 200 OK

content-type →application/json

{

    "api_key": "NjQzOGU0N2I5MDUyMWZhZWM0NmZiMTMxY2U3M2YyM2Q="

}

Authorization header for all future requests should perform Basic Auth using above api_key value as username and password as empty.

Request

GET /api/v1/configuration HTTP/1.1

Host: 10.209.112.106

Authorization: Basic cDVtTWxjN1JRdTgxUjJOdnNzTENDWmhQMDVrZjBOMk9ORmVZZUxYWDZhVT06

Response

HTTP/1.1 200 OK

Content-Length →283

Content-Type →application/json

{

"administrators":

{ "href": "/api/v1/configuration/administrators" }

,

"authentication":

{ "href": "/api/v1/configuration/authentication" }

,

"system":

{ "href": "/api/v1/configuration/system" }

,

"users":

{ "href": "/api/v1/configuration/users" }

}

Sample GET/POST/PUT/DELETE Request and Responses in ICS

Below is a sample of GET/POST/PUT/DELETE request and responses:

GET API Call: Fetch the Specific User under Local Authentication Server

Request

GET /api/v1/configuration/authentication/auth-servers/auth-server/Sys-Local/local/users/user/user0001 HTTP/1.1

Host: 10.209.112.106

Authorization: Basic cDkvaDg1eXRFbWtEenZrR1NtUTR6NzdwNllhN2FMSUM0MnZoMEY5Q0dhUT06

Content-Type: application/json

Response

HTTP/1.1 200 OK

Content-Length: 309

Content-Type: application/json

{

    "change-password-at-signin": "false",

    "console-access": "false",

    "enabled": "true",

    "fullname": "user0001",

    "one-time-use": "false",

    "password-cleartext": "'Ivanti1234$",

    "username": "user0001"

}

Equivalent Curl Command

Command

curl -i -u p9/h85ytEmkDzvkGSmQ4z77p6Ya7aLIC42vh0F9CGaQ=: -X GET https://<hostname>/api/v1/configuration/authentication/auth-servers/auth-server/System%20Local/local/users/user/user0001

Response

HTTP/1.1 200 OK

Content-Type: application/json

Content-Length: 303

{

  "change-password-at-signin": "false",

  "console-access": "false",

  "enabled": "true",

  "fullname": "user0001",

  "one-time-use": "false",

  "password-cleartext": "'Ivanti1234$",

  "username": "user0001"

}

POST API Call: Create User for Existing Local Authentication Server

Request

POST /api/v1/configuration/authentication/auth-servers/auth-server/Sys-Local/local/users/user HTTP/1.1

Host: 10.209.112.106

Authorization: Basic cDkvaDg1eXRFbWtEenZrR1NtUTR6NzdwNllhN2FMSUM0MnZoMEY5Q0dhUT06

Content-Type: application/json

{

  "change-password-at-signin": "false",

  "console-access": "false",

  "enabled": "true",

  "fullname": "user0001",

  "one-time-use": "false",

  "password-cleartext": "'Ivanti1234$",

  "username": "user0001"

}

Response

HTTP/1.1 200 OK

Content-Length: 122

Content-Type: application/json

{

    "result": {

        "info": [

            {

                "message": "Operation succeed without warning or error!"

            }

        ]

    }

}

Equivalent Curl Command

Command

curl -i -u hv5uaqOWF5kuISVnUiGEabOL8fsczsK98zVwpHYWgKE=: -X POST https://<hostname>/api/v1/configuration/authentication/auth-servers/auth-server/System%20Local/local/users/user -H 'Content-Type: application/json' -d '{"change-password-at-signin": "false", "console-access": "false", "enabled": "true", "fullname": "user0001", "one-time-use": "false", "password-cleartext": "'Ivanti1234$", "abc123", "username": "user0002"}'

Response

HTTP/1.1 201 CREATED

Content-Type: application/json

Content-Length: 128

 

{

  "result": {

    "warnings": [

      {

        "message": "The configuration has been implicitly changed"

      }

    ]

  }

}

PUT API Call:  Update Full name field of Specific user

Request

PUT /api/v1/configuration/authentication/auth-servers/auth-server/Sys-Local/local/users/user/user0001/fullname HTTP/1.1

Host: 10.209.112.106

Authorization: Basic cDkvaDg1eXRFbWtEenZrR1NtUTR6NzdwNllhN2FMSUM0MnZoMEY5Q0dhUT06

Content-Type: application/json

Cache-Control: no-cache

{

  "fullname":"REST API test for user0001"

}

Response

HTTP/1.1 200 OK

Content-Length: 122

Content-Type: application/json

{

  "result": {

    "info": [

      {

        "message": "Operation succeed without warning or error!"

      }

    ]

  }

}

Equivalent Curl Command

Command

curl -i -u hv5uaqOWF5kuISVnUiGEabOL8fsczsK98zVwpHYWgKE=: -X PUT https://<hostname>/api/v1/configuration/authentication/auth-servers/auth-server/System%20Local/local/users/user/user0001/fullname -H 'Content-Type: application/json' -d '{"fullname": "user0001"}'

Response

HTTP/1.1 200 OK

Content-Type: application/json

Content-Length: 124

{

  "result": {

    "info": [

      {

        "message": "Operation succeeded without warning or error!"

      }

    ]

  }

}

After updating, fetch the User details and observe the fullname field updated:

Request

GET /api/v1/configuration/authentication/auth-servers/auth-server/Sys-Local/local/users/user/user0001 HTTP/1.1

Host: 10.209.112.106

Authorization: Basic cDkvaDg1eXRFbWtEenZrR1NtUTR6NzdwNllhN2FMSUM0MnZoMEY5Q0dhUT06

Content-Type: application/json

Response

HTTP/1.1 200 OK

Content-Length →327

Content-Type →application/json

{

  "change-password-at-signin": "false",

  "console-access": "false",

  "enabled": "true",

  "fullname": "REST API test for user0001",

  "one-time-use": "false",

  "password-cleartext": "'Ivanti1234$",

  "username": "user0001"

}

DELETE API Call: DELETE Specific User

Request

DELETE /api/v1/configuration/authentication/auth-servers/auth-server/Sys-Local/local/users/user/user0001 HTTP/1.1

Host: 10.209.112.106

Authorization: Basic cDkvaDg1eXRFbWtEenZrR1NtUTR6NzdwNllhN2FMSUM0MnZoMEY5Q0dhUT06

Content-Type: application/json

Response

HTTP/1.1 200 OK

Content-Length →122

Content-Type →application/json

{

  "result": {

    "info": [

      {

        "message": "Operation succeed without warning or error!"

      }

    ]

  }

}

Equivalent Curl Command

Command

curl -i -u hv5uaqOWF5kuISVnUiGEabOL8fsczsK98zVwpHYWgKE=: -X DELETE https://<hostname>/api/v1/configuration/authentication/auth-servers/auth-server/System%20Local/local/users/user/user0002/

Response

HTTP/1.1 204 NO CONTENT

Content-Type: application/json

Content-Length: 0

After deleting, try to fetch the resource and you would observe 404 response.

Request

GET /api/v1/configuration/authentication/auth-servers/auth-server/Sys-Local/local/users/user/user0001 HTTP/1.1

Host: 10.209.112.106

Authorization: Basic cDkvaDg1eXRFbWtEenZrR1NtUTR6NzdwNllhN2FMSUM0MnZoMEY5Q0dhUT06

Content-Type: application/json

Cache-Control: no-cache

Response

404 NOT FOUND

Content-Length: 105

Content-Type: application/json

{

  "result": {

    "errors": [

      {

        "message": "Resource does not exist."

      }

    ]

  }

}

Representing Configuration Resources Using Links

When performing a GET request on a configuration resource, the json response may have "href" attributes to represent smaller resources within.

As an example, "GET /api/v1/configuration" returns:

{

  "users": {

    "href": "/api/v1/configuration/users"

  },

  "system": {

    "href": "/api/v1/configuration/system"

  },

  "authentication": {

    "href": "/api/v1/configuration/authentication"

  },

  "administrators": {

    "href": "/api/v1/configuration/administrators"

  }

}

The href values can be used to access smaller resources.

Sample GET/POST/PUT/DELETE Request and Responses in IPS

Below is a sample of GET/POST/PUT/DELETE request and responses:

GET API Call: Fetch the Details under Endpoint Policy

This example shows how to fetch the details under endpoint policy in IPS.

Request

GET /api/v1/configuration/uac HTTP/1.1

 

Host xx.xx.xx.xx

 

Authorization: Basic

VU9qSTlGTzNrYVk5d0t2aXpBN1dPZ0FyZlN1S3FmTkNnQUh0R0ZuR0xSbz06

 

Content-Type: application/json

 

{

    "admissionControl": {

        "href": "/api/v1/configuration/uac/admissionControl"

    },

    "host-enforcer": {

        "href": "/api/v1/configuration/uac/host-enforcer"

    },

    "infranet-enforcer": {

        "href": "/api/v1/configuration/uac/infranet-enforcer"

    },

    "mac-address-realms": {

        "href": "/api/v1/configuration/uac/mac-address-realms"

    },

    "network-access": {

        "href": "/api/v1/configuration/uac/network-access"

    },

    "snmpEnforcement": {

        "href": "/api/v1/configuration/uac/snmpEnforcement"

    }

}

Response

HTTP/1.1 200 OK

 

Content-Length: 340

 

Content-Type: application/json

Equivalent Curl Command

Command

curl -i -u g4dncT4699c+IWip/+8urgXM0Luy1vQdj9zNxEFWEbM=: -X GET https://<hostname>/api/v1/configuration/uac

Response

HTTP/1.1 200 OK

Content-Type: application/json

Content-Length: 620

{

  "admissionControl": {

    "href": "/api/v1/configuration/uac/admissionControl"

  },

  "host-enforcer": {

    "href": "/api/v1/configuration/uac/host-enforcer"

  },

  "infranet-enforcer": {

    "href": "/api/v1/configuration/uac/infranet-enforcer"

  },

  "mac-address-realms": {

    "href": "/api/v1/configuration/uac/mac-address-realms"

  },

  "network-access": {

    "href": "/api/v1/configuration/uac/network-access"

  },

  "networkDeviceAdministration": {

    "href": "/api/v1/configuration/uac/networkDeviceAdministration"

  },

  "snmpEnforcement": {

    "href": "/api/v1/configuration/uac/snmpEnforcement"

  }

POST API Call: Create an SRX Enforcer in Infranet Enforcer Connection

This example shows how to create an SRX Enforcer in Infranet Enforcer connection.

Request

POST /api/v1/configuration/uac/infranet-enforcer/connections/infranet-enforcer/ HTTP/1.1

Host xx.xx.xx.xx

Authorization: Basic

VU9qSTlGTzNrYVk5d0t2aXpBN1dPZ0FyZlN1S3FmTkNnQUh0R0ZuR0xSbz06

Content-Type: application/json

{

"idp-for-local-sessions-only": "true",

"junos": {

"location-group": "- No 802.1X -",

"password-cleartext": "'Ivanti1234$",

"name": "SRX",

"serial-number": [

"SJFIOQJI4KNM"

],

"severity-filter": "medium",

"use-idp": "false"

}

Response

HTTP/1.1 201 OK

Content-Length: 122

Content-Type: application/json

{

"result": {

"info": [

{

"message": "Operation succeed without warning or error!"

}

]

}

}

Equivalent Curl Command

Command

curl -i -u g4dncT4699c+IWip/+8urgXM0Luy1vQdj9zNxEFWEbM=: -X POST https://<hostname>/api/v1/configuration/uac/infranet-enforcer/connections/infranet-enforcer -H 'Content-Type: application/json' -d '{"idp-for-local-sessions-only": "true", "junos": { "location-group": "- No 802.1X -", "password-cleartext": "'Ivanti1234$","name": "SRX","serial-number": ["SJFIOQJI4KNM"],"severity-filter": "medium", "use-idp": "false"}'

Response

HTTP/1.1 201 CREATED

 

Content-Type: application/json

Content-Length: 124

 

{

  "result": {

    "info": [

      {

        "message": "Operation succeeded without warning or error!"

      }

    ]

  }

}

PUT API Call: Update Existing Configuration Where In Initial Location Group is Configured as Guest

This example updates the existing configuration where in the initial Location Group is configured as "Guest" and then later updated to "Default" Location group.

Before Updating the Location Group

Request

GET api/v1/configuration/uac/network-access/radius-clients/radius-client/Radius%20Client HTTP/1.1

Host xx.xx.xx.xx

Authorization: Basic

VU9qSTlGTzNrYVk5d0t2aXpBN1dPZ0FyZlN1S3FmTkNnQUh0R0ZuR0xSbz06

Content-Type: application/json

{

    "location-group": "Guest",

    "name": "Radius Client",

}

Response

HTTP/1.1 200 OK

Content-Length: 122

Content-Type: application/json

Equivalent Curl Command

Command

curl -i -u g4dncT4699c+IWip/+8urgXM0Luy1vQdj9zNxEFWEbM=: -X PUT https://<hostname>/api/v1/configuration/uac/network-access/radius-clients/radius-client/Radius%20Client -H 'Content-Type: application/json' -d '{"location-group": "Default","name": "Radius Client"}’

Response

HTTP/1.1 200 OK

Content-Type: application/json

Content-Length: 124

{

  "result": {

    "info": [

      {

        "message": "Operation succeeded without warning or error!"

      }

    ]

  }

}

After Updating the Location Group

Request

PUT api/v1/configuration/uac/network-access/radius-clients/radius-client/Radius%20Client HTTP/1.1

Host xx.xx.xx.xx

Authorization: Basic

VU9qSTlGTzNrYVk5d0t2aXpBN1dPZ0FyZlN1S3FmTkNnQUh0R0ZuR0xSbz06

Content-Type: application/json

{

"location-group": "Default",

   

    "name": "Radius Client",

   

}

Response

HTTP/1.1 200 OK

Content-Length: 122

Content-Type: application/json

{

"result": {

        "info": [

            {

                "message": "Operation succeed without warning or error!"

            }

        ]

    }

}

DELETE API Call: Delete an SNMP Device

This example shows how to delete SNMP device from IPS.

Request

DELETE api/v1/configuration/uac/snmpEnforcement/clients/client/ruckus HTTP/1.1

Host 10.96.73.37

Authorization: Basic

VU9qSTlGTzNrYVk5d0t2aXpBN1dPZ0FyZlN1S3FmTkNnQUh0R0ZuR0xSbz06

Content-Type: application/json

Response

HTTP/1.1 204 NO CONTENT

Content-Length: 0

Content-Type: application/json

Equivalent Curl Command

Command

curl -I -u g4dncT4699c+IWip/+8urgXM0Luy1vQdj9zNxEFWEbM=: -X DELETE https://<hostname>/api/v1/configuration/uac/snmpEnforcement/clients/client/ruckus

Response

HTTP/1.1 204 NO CONTENT

Content-Type: application/json

Content-Length: 0