Chat now with support
Chat with Support

One Identity Safeguard for Privileged Sessions 7.0.2 LTS - REST API Reference Guide

Introduction Using the SPS REST API Basic settings User management and access control Managing SPS General connection settings HTTP connections Citrix ICA connections MSSQL connections RDP connections SSH connections Telnet connections VNC connections Search, download, and index sessions Reporting Health and maintenance Advanced authentication and authorization Completing the Welcome Wizard using REST Enable and configure analytics using REST

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.

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 Reviewing the changelog of a transaction.
remaining_seconds integer Time left until the session times out in seconds SPS closes idle sessions after a period of inactivity. This value shows the number of seconds left until the timeout.
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 SPS handles transactions, see How to configure SPS 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 Message format.

  • 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 Application level error codes.
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": {
     "details": {
       "path": "password"
     },
    "message": "Syntax error: The given password is too short. Minimum password length: 10",
    "type": "SyntacticError"
   }
}
,
   "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.

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

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating