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

Introduction

Starting with One Identity Safeguard for Privileged Sessions version 4 F2, certain parts and features of Safeguard for Privileged Sessions 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 Safeguard for Privileged Sessions 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 Safeguard for Privileged Sessions REST API allows you to create, read, update and delete (CRUD) the configuration resources of Safeguard for Privileged Sessions.

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 Safeguard for Privileged Sessions (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 Safeguard for Privileged Sessions REST API allows you to create, read, update and delete (CRUD) the configuration resources of Safeguard for Privileged Sessions. 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 Safeguard for Privileged Sessions 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 Introduction.

• 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 Safeguard for Privileged Sessions using REST

The Safeguard for Privileged Sessions REST server uses a transactional model for configuration management. 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 Safeguard for Privileged Sessions using REST: a sample transaction.

1. Authenticate on the Safeguard for Privileged Sessions REST server, and receive a session_id. For details, see Authenticate to the Safeguard for Privileged Sessions REST API.

2. Open a transaction. This transaction will collect the changes and modifications you do, compared to the Safeguard for Privileged Sessions 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 Using the Safeguard for Privileged Sessions REST API.

   Note that opening a transaction locks the configuration of Safeguard for Privileged Sessions similarly to accessing Safeguard for Privileged Sessions from the web interface. For details, see "Multiple users and locking" in the Administration Guide.

3. Change and modify the configuration of Safeguard for Privileged Sessions 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 Safeguard for Privileged Sessions, see Using the Safeguard for Privileged Sessions REST API and Using the Safeguard for Privileged Sessions REST API

4. Commit your transaction to submit your changes to Safeguard for Privileged Sessions (this is similar to clicking Checkout in a web shop). For details, see Using the Safeguard for Privileged Sessions REST API.

   If the AAA > Settings > Accounting settings > Require commit log option is selected in the Safeguard for Privileged Sessions web interface, you must include a commit message (a message object) in the request. This message will be visible on the AAA > Accounting page of the Safeguard for Privileged Sessions web interface. Note that on the AAA > Accounting 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 Safeguard for Privileged Sessions, 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 Using the Safeguard for Privileged Sessions REST API.

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

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

How to configure Safeguard for Privileged Sessions 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 Safeguard for Privileged Sessions using REST.

1. Authenticate on the Safeguard for Privileged Sessions REST server, and receive a session_id.

   curl --basic --user <username>:<password> --cookie-jar cookies --insecure https://<Safeguard for Privileged Sessions-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-Safeguard for Privileged Sessions>/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 AAA > Settings page of the Safeguard for Privileged Sessions web interface.

   curl --cookie cookies --insecure https://<IP-address-of-Safeguard for Privileged Sessions>/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 Safeguard for Privileged Sessions as you need. The following example configures Safeguard for Privileged Sessions to check the password strength of the passwords for users of the Safeguard for Privileged Sessions 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-Safeguard for Privileged Sessions>/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 Safeguard for Privileged Sessions.

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

   If the AAA > Settings > Accounting settings > Require commit log option is selected in the Safeguard for Privileged Sessions web interface, you must include a commit message (a message object) in the request. This message will be visible on the AAA > Accounting page of the Safeguard for Privileged Sessions web interface. Note that on the AAA > Accounting page, changes performed using the REST API are listed as changes to the REST server/REST configuration page.

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