“Welcome, Balabit customers to One Identity Support Portal click here for for frequently asked questions regarding servicing your supported assets.”

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

Introduction Using the Safeguard for Privileged Sessions REST API Basic settings User management and access control Managing Safeguard for Privileged Sessions General connection settings HTTP connections Citrix ICA connections RDP connections SSH connections Telnet connections VNC connections Search, download, and index sessions Reporting Advanced authentication and authorization Completing the Welcome Wizard using REST Enable and configure analytics using REST About us Third-party contributions

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.


Was this topic helpful?

[Select Rating]



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.

Element Type Description Notes
meta Top level element, contains links to different parts of the REST service
changes string Path to the transaction changelog This value is always /api/transaction/changes. For details, see Using the Safeguard for Privileged Sessions REST API.
remaining_seconds integer Time left until the session times out in seconds Safeguard for Privileged Sessions closes idle sessions after a period of inactivity. This value shows the number of seconds left until the timeout. For details on setting the session timeout, see Web interface.
href string (relative path) Path of the resource that returned the response. When creating a new object, this is the URL of the created object. For example, /api/authentication
parent string (relative path)
next string (relative path) Path of the next sibling of the current resource For example, /api/configuration
prev string (relative path) Path of the previous sibling of the current resource
first string (relative path) Path of the first sibling of the current resource
last string (relative path) Path of the last sibling of the current resource
transaction string (/api/transaction) The endpoint of the transaction log For details on how Safeguard for Privileged Sessions handles transactions, see How to configure Safeguard for Privileged Sessions using REST.
items list of JSON objects List of endpoints (objects) available from the current endpoint

Each object in the list contains a key and a meta object for the endpoint. For example:

{
	"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.

Element Type Description Notes
error Top level element, contains links to different parts of the REST service
type string The type of the error that occurred For example, Unauthenticated, or NodeNotFound. For a complete list, see Using the Safeguard for Privileged Sessions REST API.
message string A textual message that describes the error For example, Unable to locate the requested path.
details JSON object List of additional information about the error (for example, the path where the error occurred)

For example:

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

Was this topic helpful?

[Select Rating]



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.


Was this topic helpful?

[Select Rating]



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.


Was this topic helpful?

[Select Rating]



Self Service Tools
Knowledge Base
Notifications & Alerts
Product Support
Software Downloads
Technical Documentation
User Forums
Video Tutorials
Contact Us
Licensing Assistance
Technical Support
View All
Related Documents