One Identity Safeguard for Privileged Sessions 6.9.2 - REST API Reference Guide

Introduction

Starting with One Identity Safeguard for Privileged Sessions version 4 F2, certain parts and features of SPS can be configured using a RESTful API (Representational State Transfer Application Programming Interface). The REST server conforms to the Hypermedia as the Engine of Application State (HATEOAS).

The SPS REST API uses JSON over HTTPS. The REST server has a single entry point and all resources are available at paths (URLs) returned in the response for a request sent to the entry point. The only path that is guaranteed not to change is /api/authentication. Every other path should be reached by navigating the links returned.

The SPS REST API allows you to create, read, update and delete (CRUD) the configuration resources of SPS.

In this tutorial, all examples are displayed with curl, but you can use any other HTTP client. In the examples it is assumed that the REST server is listening on the default HTTP port of SPS (443).

If you receive the "417 - Expectation Failed" error code when using curl, use curl with the --http1.0 or the -H "Expect:" option.

Message format

Response headers

The following headers are included in every response. Other headers are specific to responses to specific requests.

• Allow: The SPS REST API allows you to create, read, update and delete (CRUD) the configuration resources of SPS. The value of the header lists the available actions for the resource or object.

• Content-Language: The language of the response. Currently only English (en) is supported.

• Content-Type: All messages are JavaScript Object Notation (JSON) objects. The SPS REST server sends all REST API responses in application/json format.

Response body

The response body contains JSON objects. These objects always contain a meta field with links to different parts of the REST service. In most cases, the following entries can be found in the meta object. Error messages are returned in the error element.

{
	"meta": {
	"href": "/api/ssh-host-keys",
	"parent": "/api"
	},
	"items": [
	{
	"key": "ssh-rsa-10.10.100.1:22",
	"meta": {
	"href": "/api/ssh-host-keys/ssh-rsa-10.10.100.1:22"
	}
	},
	{
	"key": "ssh-rsa-10.10.20.35:22",
	"meta": {
	"href": "/api/ssh-host-keys/ssh-rsa-10.10.20.35:22"
	}
	},
	{
	"key": "ssh-rsa-10.40.0.28:22",
	"meta": {
	"href": "/api/ssh-host-keys/ssh-rsa-10.40.0.28:22"
	}
	}
	]
}

For example:

{
			"meta": {
			"href": "/api",
			"next": "/api/configuration"
			}
		}

Error responses

All error responses are JSON objects with the following keys.

• meta: JSON object containing navigation links. For details, see Message format.

• error: JSON object containing information about the error.

"details": {
    "path": "no/such/path"
}

The following is a complete error response.

{
			"error": {
			"type": "NodeNotFound",
			"message": "Unable to locate the requested path",
			"details": {
			"path": "no/such/path"
			}
			},
			"meta": {
			"href": "/api/configuration/no/such/path",
			"parent": "/api/configuration"
			}
		}

How to configure SPS using REST

The SPS REST server uses a transactional model for configuration management.

Certain endpoints require transaction for sending/receiving POST, PUT, GET and so on requests. A transaction creates a "snapshot" of the configuration and will perform all changes on that snapshot. For example, when using transaction in case of a GET request, your requests will be performed on a consistent state of the configuration as opposed to a configuration that might change in the meantime due to user interaction.

The following endpoints require transaction:

• https://<IP-address-of-SPS>/api/configuration/

• https://<IP-address-of-SPS>/api/cluster/

• https://<IP-address-of-SPS>/api/user/password/

• https://<IP-address-of-SPS>/api/upload/

Modifying the configuration has the following main steps. The steps are explained in detail in later sections of the tutorial. You find a simple transaction with detailed requests and responses in How to configure SPS using REST: a sample transaction.

1. Authenticate on the SPS REST server, and receive a session_id. For details, see Authenticate to the SPS REST API.

2. Open a transaction. This transaction will collect the changes and modifications you do, compared to the SPS configuration that is active at the time of opening the transaction. It is similar to a shopping cart, where your modifications are the items in the cart. For details, see Open a transaction.

   Opening a transaction locks the configuration of SPS similarly to accessing SPS from the web interface. At the open transaction stage this step is optional.

3. Change and modify the configuration of SPS as you need. Note that to modify the configuration, you must have the required privileges. For details, see "Managing user rights and usergroups" in the Administration Guide. For details on navigating and modifying the configuration of SPS, see Navigating the configuration of SPS and Modifying the configuration of SPS

4. Commit your transaction to submit your changes to SPS (this is similar to clicking Checkout in a web shop). For details, see Commit a transaction.

   If the Users & Access Control > Settings > Accounting settings > Require commit log option is selected in the SPS web interface, you must include a commit message (a message object) in the request. This message will be visible on the Users & Access Control > Configuration History page of the SPS web interface. Note that on the Users & Access Control > Configuration History page, changes performed using the REST API are listed as changes to the REST server/REST configuration page.

   If you do not want to commit your changes, and would like to restart with the original configuration of SPS, you can simply delete the transaction. This is similar to the rollback transaction in SQL. If your session times out, your transaction is deleted automatically. For details, see Delete a transaction.

   Note that committing a transaction locks the configuration of SPS similarly to accessing SPS from the web interface. For more information, see "Multiple users and locking" in the Administration Guide.

5. SPS checks and validates the changes in your transaction. If other users have changed the configuration of SPS since you opened the transaction, SPS tries to merge your changes to the current configuration.

6. If your changes are valid, SPS applies them and you have successfully changed the configuration of SPS. Otherwise, the REST server returns an error response.

How to configure SPS using REST: a sample transaction

This procedure shows a sample transaction with detailed requests and responses. For details on the transaction model, see How to configure SPS using REST.

1. Authenticate on the SPS REST server, and receive a session_id.

   curl --basic --user <username>:<password> --cookie-jar cookies --insecure https://<SPS-IP-address>/api/authentication
   
   Response status: 200
   --- BEGIN RESPONSE BODY ---
   {
     "meta": {
       "href": "/api",
       "next": "/api",
       "transaction": "/api/transaction"
     }
   }
   --- END RESPONSE BODY ---

2. Open a transaction.

   curl --data "" --cookie cookies --insecure -X POST https://<IP-address-of-SPS>/api/transaction
   
   Response status: 200
   --- BEGIN RESPONSE BODY ---
   {
     "meta": {
       "href": "/api/transaction",
       "parent": "/api"
     }
   }
   --- END RESPONSE BODY ---

3. Retrieve a resource. The following example shows the resource corresponding to the Users & Access Control > Settings page of the SPS web interface.

   curl --cookie cookies --insecure https://<IP-address-of-SPS>/api/configuration/aaa/settings
   
   Response status: 200
   --- BEGIN RESPONSE BODY ---
   {
     "key": "settings",
     "meta": {
       "first": "/api/configuration/aaa/settings",
       "href": "/api/configuration/aaa/settings",
       "last": "/api/configuration/aaa/settings",
       "next": null,
       "parent": "/api/configuration/aaa",
       "previous": null,
       "transaction": "/api/transaction"
     },
     "settings": {
       "backend": {
         "cracklib_enabled": false,
         "expiration_days": 0,
         "minimum_password_strength": "good",
         "remember_previous_passwords": 10,
         "selection": "local"
       },
       "method": {
         "selection": "passwd"
       },
       "require_commitlog": false
     }
   }
   --- END RESPONSE BODY ---

4. Change and modify the configuration of SPS as you need. The following example configures SPS to check the password strength of the passwords for users of the SPS web interface.

   # Body of the PUT request. You can read it from a file, for example, body.json
   {
     "backend": {
   	"cracklib_enabled": true,
   	"expiration_days": 0,
   	"minimum_password_strength": "good",
   	"remember_previous_passwords": 10,
   	"selection": "local"
     },
     "method": {
   	"selection": "passwd"
     },
     "require_commitlog": false
     }
   # Command to use
   curl -H "Content-Type: application/json" -d @body.json --cookie cookies --insecure -X PUT https://<IP-address-of-SPS>/api/configuration/aaa/settings
   
   Response status: 200
   --- BEGIN RESPONSE BODY ---
   {
     "meta": {
       "first": "/api/configuration/aaa/settings",
       "href": "/api/configuration/aaa/settings",
       "last": "/api/configuration/aaa/settings",
       "next": null,
       "parent": "/api/configuration/aaa",
       "previous": null,
       "transaction": "/api/transaction"
     }
   }
   --- END RESPONSE BODY ---

5. Commit your transaction to submit your changes to SPS.

   curl -H "Content-Type: application/json" -d '{"status": "commit","message": "My commit message"}' --cookie cookies --insecure -X PUT https://<IP-address-of-SPS>/api/transaction
   
   Response status: 200
   --- BEGIN RESPONSE BODY ---
   {
     "meta": {
       "href": "/api/transaction",
       "parent": "/api"
     }
   }
   --- END RESPONSE BODY ---

   If the Users & Access Control > Settings > Accounting settings > Require commit log option is selected in the SPS web interface, you must include a commit message (a message object) in the request. This message will be visible on the Users & Access Control > Configuration History page of the SPS web interface. Note that on the Users & Access Control > Configuration History page, changes performed using the REST API are listed as changes to the REST server/REST configuration page.

6. If your changes are valid, SPS applies them and you have successfully changed the configuration of SPS. Otherwise, the REST server returns an error response.