One Identity Safeguard for Privileged Sessions 6.0.10

Message format How to configure SPS using REST How to configure SPS using REST: a sample transaction

Authenticate to the SPS REST API Authenticate to the SPS REST API using X.509 certificate Retrieve user information Checking the transaction status Open a transaction Commit a transaction Delete a transaction Reviewing the changelog of a transaction Application level error codes Navigating the configuration of SPS Modifying the configuration of SPS

Delete an object Create a new object Change an object

Basic settings

Retrieve basic firmware and host information Network settings

Web interface Network configuration options DNS servers Routing between interfaces Naming options Network addresses Routing table Local services of SPS Local services: Web login for administrators Local services: Web login for users Local services: cluster interface

Date and time

Date & time NTP servers Timezone

Logs, monitoring and alerts

Management options Syslog server settings Disk fill-up prevention Mail settings Health monitoring SNMP settings SNMP traps Local services: access for SNMP agents Alerting System alerts Traffic alerts

User management and access control

User management and access control Authentication and user database settings Privileges of usergroups Audit data access rules Active sessions Manage users and usergroups locally on SPS Manage usergroups locally on SPS Manage users locally on SPS

Managing SPS

Troubleshooting options Internal certificates Passwords stored on SPS Private keys stored on SPS Certificates stored on SPS Local services: enabling SSH access to the SPS host RPC API Manage the SPS license Change contact information Splunk integration Splunk integration Manage Safeguard for Privileged Sessions clusters

Promote a Safeguard for Privileged Sessions node to be the Central Management node in a new cluster Join node(s) to the cluster Query join status Assign a role to a node Query nodes Query one particular node Query the status of all nodes in the cluster Query the status of one particular node Upload and enable a configuration synchronization plugin Disable a configuration synchronization plugin

General connection settings

Channel policy Policies Archive/Cleanup policy Audit policies Backup policy Real-time content monitoring with Content Policies LDAP servers Signing CA policies Time policy Trusted Certificate Authorities Local user databases User lists

HTTP connections

HTTP connections HTTP connection policies HTTP authentication policies Global HTTP options HTTP settings policies

Citrix ICA connections

ICA connections ICA connection policies ICA channels Global ICA options ICA settings policies

RDP connections

RDP connections RDP connection policies RDP channels Configuring domain membership Global RDP options RDP settings policies

SSH connections

SSH connections SSH connection policies SSH channels SSH authentication policies Global SSH options SSH settings policies SSH host keys and certificates

Telnet connections

Telnet connections Telnet connection policies Global Telnet options

VNC connections

VNC connections VNC connection policies Global VNC options

Search, download, and index sessions

Audited sessions Download audit trails Searching in the session database Searching in connection content Session statistics Session histogram Session alerts Session events Indexing sessions Session audit trail downloads Local services: configuring the indexer Indexer policies

Reporting

Reporting Reports Built-in subchapters Pre-defined reports Content subchapters Custom subchapters Connection statistics subchapters

Health and maintenance

Monitor appliance health status

Advanced authentication and authorization

Usermapping policy Plugins Authentication and authorization plugins Credential store plugins Credential stores

Completing the Welcome Wizard using REST

Enable and configure analytics using REST

Enable One Identity Safeguard for Privileged Analytics Configure One Identity Safeguard for Privileged Analytics

Query one particular node

Managing SPS > Manage Safeguard for Privileged Sessions clusters > Query one particular node

To query one particular node, complete the following steps.

Query the /api/cluster/nodes/<node-id-of-node-to-be-queried> endpoint on the node that you want to query.

curl --cookie cookies https://<IP-address-of-node-to-be-queried>/api/cluster/nodes/<node-id-of-node-to-be-queried>

The following is a sample response received.

For details of the meta object, see Message format.

{
    "body": {
        "address": "<IP-address-of-node-to-be-queried>",
        "roles": [
            "central-management"
        ]
    },
    "key": "b35c54da-b556-4f91-ade5-d26283d68277",
    "meta": {
        "href": "/api/cluster/nodes/b35c54da-b556-4f91-ade5-d26283d68277",
        "parent": "/api/cluster/nodes",
        "remaining_seconds": 28800,
        "status": "/api/cluster/status/b35c54da-b556-4f91-ade5-d26283d68277"
    }
}

Elements		Type	Description
body		Top-level element (JSON object)	Contains the JSON object of the node.
	address	string	The IP address of the node.
	roles	string	The role assigned to the node.
key		string	The ID of the node.

Query the status of all nodes in the cluster

Managing SPS > Manage Safeguard for Privileged Sessions clusters > Query the status of all nodes in the cluster

To query the status of all nodes in your cluster, complete the following steps.

Query the /api/cluster/status endpoint on the Central Management node.

curl --cookie cookies https://<IP-address-of-Central-Management-node>/api/cluster/status

The following is a sample response received.

For details of the meta object, see Message format.

{
  "items": [
    {
      "key": "b35c54da-b556-4f91-ade5-d26283d68277",
      "fqdn": "sps.example.com",
      "health_status": null,
      "sync_status": "n/a",
      "meta": {
        "configuration": "/api/cluster/nodes/b35c54da-b556-4f91-ade5-d26283d68277",
        "href": "/api/cluster/status/b35c54da-b556-4f91-ade5-d26283d68277"
      }
    },
    {
      "key": "46f97a58-4028-467d-9a22-9cfe78ae3e1c",
      "last_seen": "2018-02-08T10:00:30Z",
      "fqdn": "managed-host.cluster",
      "health_status": {
        "memory": 62.5,
        "disk": 1.9,
        "swap": 0,
        "load1": 0.53,
        "load5": 0.68,
        "load15": 0.37,
        "sessions": {
          "ssh": 3,
          "rdp": 4
        },
        "total_sessions": 7
      },
      "sync_status": "pending",
      "configuration_sync": {
        "last_updated": "2018-02-08T09:59:00Z",
        "last_checked": "2018-02-08T09:59:00Z",
        "downloaded_xml_hash": "2853830f4aa0a90a63e75bab1b22e513",
        "issues": {
          "warnings": [
           {
              "message": "Connection 'simple_ssh_connection' and local service 'SSH' conflict on 10.30.42.42:22",
              "paths": [
                "/api/configuration/ssh/connections/12345",
                "/api/configuration/local_services/ssh"
              ]
            }
          ]
        }
      },
      "meta": {
        "configuration": "/api/cluster/nodes/46f97a58-4028-467d-9a22-9cfe78ae3e1c",
        "href": "/api/cluster/status/46f97a58-4028-467d-9a22-9cfe78ae3e1c"
      }
    }
  ],
  "meta": {
    "href": "/api/cluster/status",
    "parent":  "/api/cluster",
    "self": "/api/cluster/status/b35c54da-b556-4f91-ade5-d26283d68277"
  }
}

Elements			Type	Description
items			Top-level element (list of JSON objects)	List of endpoints (objects) available from the current endpoint.
	key		string	The ID of the node.
	fqdn		string	The address of the node as a fully qualified domain name.
	health_status		null or object	The health status of a node. If the node is down, the value is null. Otherwise, the health-related data is listed.
		memory	floating point integer (percent)	Memory use
		disk	floating point integer (percent)	Hard disk use
		swap	floating point integer (percent)	Swap use
		load1	floating point integer	The average system load during the last one minute. The values mean the following: < 1: low system load 1-5: high system load > 5: extremely high system load
		load5	floating point integer	The average system load during the last five-minute period. The values mean the following: < 1: low system load 1-5: high system load > 5: extremely high system load
		load15	floating point integer	The average system load during the last fifteen-minute period. The values mean the following: < 1: low system load 1-5: high system load > 5: extremely high system load
		sessions	string	The protocol type and the number of ongoing sessions. For example: "sessions": { "ssh": 3, "rdp": 4 },
		total_sessions	integer (number of)	The total number of ongoing sessions.
	sync_status		string	Indicates the status of configuration synchronization. It has the following values: up-to-date: The node has fetched the latest configuration from the Central Management node, and has applied it. It is in sync with the Central Management node. pending: There has been a configuration change on the Central Management node, and the change has not been synchronized yet to the node. outdated: There has been some error on the node and therefore it is running an old configuration. not-fetched: The node has not fetched any configuration yet. n/a: The node is the Central Management node, so it is not fetching its configuration from any other node.
	meta		Top-level item (JSON object)	Contains links to different parts of the REST service.
		configuration	string (relative path)	The path to the configuration of the node that returned the response.
		href	string (relative path)	The path to the node that returned the response.
	last_seen		string	The last time the node sent status information to the Central Management node, in ISO 8601 format.
	configuration_sync		Top-level item (JSON object)
		downloaded_xml_hash	string	The hash of the latest downloaded configuration file (used for configuration synchronization). If no configuration file has been downloaded yet, it says null.
		last_updated	string	The last time the node's configuration was synchronized, in ISO 8601 format.
		last_checked	string	The last time the node attempted to fetch a new configuration, in ISO 8601 format.
		issues	Top-level item (JSON object)	The issues that occurred during configuration synchronization.

Elements of issues		Type	Description
warning		Top-level item (JSON object)
	message	string	Human-readable text explaining why the warning occurred.
	details	array	List of additional information about the warning (for example, the path where the warning occurred).
error		Top-level item (JSON object)
	type	string	The type of the error.
	message	string	Human-readable text explaining why the error occurred.
	details	JSON object	List of additional information about the error (for example, the path where the error occurred).

Query the status of one particular node

Managing SPS > Manage Safeguard for Privileged Sessions clusters > Query the status of one particular node

To query the status of one particular node in your cluster, complete the following steps.

Query the /api/cluster/status/<node-id-of-node-to-be-queried> endpoint on the Central Management node.

curl --cookie cookies https://<IP-address-of-Central-Management-node>/api/cluster/status/<node-id-of-node-to-be-queried>

The following is a sample response received.

For details of the meta object, see Message format.

For details of the other objects, see tables Cluster status details and "issues" object details.

{
    "fqdn": "managed-host.cluster",
    "key": "46f97a58-4028-467d-9a22-9cfe78ae3e1c",
    "configuration_sync": {
        "downloaded_xml_hash": "2853830f4aa0a90a63e75bab1b22e513",			
        "last_updated": "2018-02-08T09:59:30Z",
        "last_checked": "2018-02-08T09:59:30Z",
        "issues": {}
    },
    "health_status": {
        "memory": 62.5,
        "disk": 1.9,
        "swap": 0,
        "load1": 0.53,
        "load5": 0.68,
        "load15": 0.37,
        "sessions": {
            "ssh": 3,
            "rdp": 4
        },
        "total_sessions": 7
    },
    "sync_status": "up-to-date",
    "last_seen": "2018-02-08T10:00:00Z",
    "meta": {
        "configuration": "/api/cluster/nodes/46f97a58-4028-467d-9a22-9cfe78ae3e1c",
        "href": "/api/cluster/status/46f97a58-4028-467d-9a22-9cfe78ae3e1c"
    }
}

Elements			Type	Description
items			Top-level element (list of JSON objects)	List of endpoints (objects) available from the current endpoint.
	key		string	The ID of the node.
	fqdn		string	The address of the node as a fully qualified domain name.
	health_status		null or object	The health status of a node. If the node is down, the value is null. Otherwise, the health-related data is listed.
		memory	floating point integer (percent)	Memory use
		disk	floating point integer (percent)	Hard disk use
		swap	floating point integer (percent)	Swap use
		load1	floating point integer	The average system load during the last one minute. The values mean the following: < 1: low system load 1-5: high system load > 5: extremely high system load
		load5	floating point integer	The average system load during the last five-minute period. The values mean the following: < 1: low system load 1-5: high system load > 5: extremely high system load
		load15	floating point integer	The average system load during the last fifteen-minute period. The values mean the following: < 1: low system load 1-5: high system load > 5: extremely high system load
		sessions	string	The protocol type and the number of ongoing sessions. For example: "sessions": { "ssh": 3, "rdp": 4 },
		total_sessions	integer (number of)	The total number of ongoing sessions.
	sync_status		string	Indicates the status of configuration synchronization. It has the following values: up-to-date: The node has fetched the latest configuration from the Central Management node, and has applied it. It is in sync with the Central Management node. pending: There has been a configuration change on the Central Management node, and the change has not been synchronized yet to the node. outdated: There has been some error on the node and therefore it is running an old configuration. not-fetched: The node has not fetched any configuration yet. n/a: The node is the Central Management node, so it is not fetching its configuration from any other node.
	meta		Top-level item (JSON object)	Contains links to different parts of the REST service.
		configuration	string (relative path)	The path to the configuration of the node that returned the response.
		href	string (relative path)	The path to the node that returned the response.
	last_seen		string	The last time the node sent status information to the Central Management node, in ISO 8601 format.
	configuration_sync		Top-level item (JSON object)
		downloaded_xml_hash	string	The hash of the latest downloaded configuration file (used for configuration synchronization). If no configuration file has been downloaded yet, it says null.
		last_updated	string	The last time the node's configuration was synchronized, in ISO 8601 format.
		last_checked	string	The last time the node attempted to fetch a new configuration, in ISO 8601 format.
		issues	Top-level item (JSON object)	The issues that occurred during configuration synchronization.

Elements of issues		Type	Description
warning		Top-level item (JSON object)
	message	string	Human-readable text explaining why the warning occurred.
	details	array	List of additional information about the warning (for example, the path where the warning occurred).
error		Top-level item (JSON object)
	type	string	The type of the error.
	message	string	Human-readable text explaining why the error occurred.
	details	JSON object	List of additional information about the error (for example, the path where the error occurred).

Upload and enable a configuration synchronization plugin

Managing SPS > Manage Safeguard for Privileged Sessions clusters > Upload and enable a configuration synchronization plugin

Nodes fetch their configuration from the Central Management node, and merge it into their own configuration. Depending on their role, nodes may merge the whole configuration into their own (Managed Host nodes), or only the cluster-specific parts (nodes with no roles assigned). Whenever a configuration change is made on the Central Management node and the change is committed, it is synchronized to all nodes in the cluster as soon as the nodes fetch the latest configuration from the Central Management node.

When synchronizing the central configuration across nodes, you may want to:

Keep certain parts in the configuration of individual nodes as-is.
Tailor certain parts of the central configuration to specific needs of individual nodes in the cluster (for example, your nodes may access external services at different network addresses).

You can achieve all of these by using a configuration synchronization plugin that contains transformations for the problematic parts. The plugin only runs on nodes that have the Managed Host role.

Customizing certain parts or features of a node using a configuration synchronization plugin has the same limitations as configuring SPS through the REST API. In other words, whatever you can configure through the REST API, you can configure the exact same settings using the plugin. One notable difference between the REST API and the plugin is that using the REST API, you can only read certain types of data (such as keys and passwords), while using the configuration synchronization plugin, you can write these types of data as well.

Data structures in the plugin are represented as nested JSON objects. For object references, the plugin uses keys.

The plugin works with the following key parameters:

local_config: The current configuration of a Managed Host node (those parts that can be configured through the REST API).
merged_config: The configuration of the Central Management node that is about to be synced to the Managed Host node (those parts that can be configured through the REST API), with settings related to networking, local services, management, and the license of SPS whitelisted. These settings are never overwritten by configuration synchronization.
node_id: The unique ID of the Managed Host node in the cluster (you can retrieve this identifier by querying the /api/cluster/nodes endpoint through the REST API).
plugin_config: The configuration of the plugin provided as free-form text. Specifying the configuration of the plugin is optional. It enables you to run configuration synchronization on each cluster with different parameters if you have multiple clusters.

Example: Customizing an IP address in a connection policy

For example, an RDP connection policy on a Managed Host node specifies the following client and target addresses:

$ curl ... https://<url-of-Central-Management-node>/api/configuration/rdp/connections/<id-of-the-connection-policy>

{
    "body": {
        "network": {
            "clients": [
                "0.0.0.0/0"
                ],
            "ports": [
                3389
                ],
           "targets": [
               "10.30.255.28/24"
               ]
        },
    },
    ...
}

Let's suppose that on the Central Management node, an RDP connection policy is configured with these details:

$ curl ... https://<url-of-Managed-Node>/api/configuration/rdp/connections/<id-of-the-connection-policy>

{
    "body": {
        "network": {
            "clients": [
                "0.0.0.0/0"
                ],
            "ports": [
                3389
                ],
           "targets": [
               "10.30.255.8/24"
               ]
        },
    },
    ...
}

To ensure that the details of the connection policy on the Managed Host node are kept as-is after configuration synchronization, add the following lines to the plugin main.py file:

$ cat main.py
def merge(local_config: dict, merged_config: dict, node_id: str, plugin_config: str, **kwargs):
    merged_config['rdp']['connections'][<id-of-the-connection-policy>]['network']['targets'][0] = "10.30.255.8/24"
    return merged_config

Due to possible new (as yet undefined) parameters, it is good practice to close the parameter list of the merge function with **kwargs.

In case you need assistance with writing customized transformations, contact our Professional Services Team, and a One Identity Service Delivery Engineer will be able to help you.

NOTE:

Configuration settings related to networking (/api/configuration/network), local services (/api/configuration/local_services), and the management of SPS (/api/configuration/management) are not overwritten on the nodes by configuration synchronization even when not using a plugin.

To upload a configuration synchronization plugin to the Central Management node, complete the following steps.

Open a transaction.

For details, see Open a transaction.

Upload the plugin file.

POST the plugin as a zip file (application/zip) to the https://<IP-address-of-Central-Management-node>/api/upload/pluginsendpoint, for example:

curl -X POST -H "Content-Type: application/zip" --cookie cookies https://<IP-address-of-Central-Management-node>/api/upload/plugins --data-binary @<path-to-plugin.zip>

The following is a sample response received.

For details of the meta object, see Message format.

{
    "body": {
        "api": "1.0",
        "default_configuration": "",
        "description": "Whitelist the list of paths when merging the configuration",
        "name": "whitelist",
        "path": "/opt/scb/var/plugins/configuration_sync/whitelist",
        "scb_max_version": "",
        "scb_min_version": "",
        "version": "1.0"
    },
    "key": "794a5e17-b8be-4426-8596-0dfc129c06ef",
    "meta": {
        "href": "/api/configuration/plugins/configuration_sync/794a5e17-b8be-4426-8596-0dfc129c06ef",
        "parent": "/api/configuration/plugins/configuration_sync",
        "remaining_seconds": 599
    }
}

Elements		Type	Description
body		Top-level element (JSON object)
	api	string	Always "1.0".
	default_configuration	string	Contains the default configuration of the plugin if there is one.
	description	string	The description of what the plugin does.
	name	string	The name of the plugin.
	path	string	The path to the plugin.
	scb_max_version	string	The plugin is compatible with SPS versions not later than this one.
	scb_min_version	string	The plugin is compatible with SPS versions not earlier than this one.
	version	string	The version number of the plugin.
key		string	The ID of the plugin.

To enable the plugin, replace `/api/cluster/configuration_sync_plugin` with:

{
    "enabled": true,
    "plugin": "<'key' from-response-of-last-creation>",
    "configuration": ""
}

For example:

curl -X POST -H "Content-Type: application/json" --cookie cookies https://<IP-address-of-Central-Management-node>/api/cluster/configuration_sync_plugin --data '{"enabled": true, "plugin": "794a5e17-b8be-4426-8596-0dfc129c06ef", "configuration": ""}'

The following is a sample response received:

{
    "plugin": {
        "key": "794a5e17-b8be-4426-8596-0dfc129c06ef",
        "meta": {
            "href": "/api/configuration/plugins/configuration_sync/794a5e17-b8be-4426-8596-0dfc129c06ef"
        }
    }
}

Commit your changes.

For details, see Commit a transaction.

Please select your product:

To serve you better, please complete the Purpose of your Chat:

Recommended Solutions for Your Problem

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

Query one particular node

Query the /api/cluster/nodes/<node-id-of-node-to-be-queried> endpoint on the node that you want to query.

Query the status of all nodes in the cluster

Query the /api/cluster/status endpoint on the Central Management node.

Query the status of one particular node

Query the /api/cluster/status/<node-id-of-node-to-be-queried> endpoint on the Central Management node.

Upload and enable a configuration synchronization plugin

Example: Customizing an IP address in a connection policy

Open a transaction.

Upload the plugin file.

To enable the plugin, replace /api/cluster/configuration_sync_plugin with:

Commit your changes.

To enable the plugin, replace `/api/cluster/configuration_sync_plugin` with: