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 |
|
|
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. 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 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.
| 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.
-
Authenticate on the SPS REST server, and receive a session_id. For details, see Authenticate to the SPS REST API.
-
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.
-
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
-
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.
-
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.
-
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
Introduction > 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.
-
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 ---
-
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 ---
-
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 ---
-
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 ---
-
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.
-
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.
