Chat now with support
Chat with Support

Safeguard for Privileged Sessions On Demand Hosted - 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

Query the status of one particular node

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

  1. 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

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 unchanged.

  • Customize certain parts of the central configuration to specific needs of individual nodes in the cluster (for example, your nodes may access external services through 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 One Identity Safeguard for Privileged Sessions (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"
               ]
        },
    },
    ...
}

In the following example, an RDP connection policy is configured with the following details on the Central management node:

$ 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.

  1. Open a transaction.

    For more information, see Open a transaction.

  2. Upload the plugin file.

    POST the plugin as a zip file (application/zip) to the https://<IP-address-of-Central-Management-node>/api/upload/plugins endpoint, 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.
  3. 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"
        }
    }
}
  4. Commit your changes.

    For more information, see Commit a transaction.

Disable a configuration synchronization plugin

To disable a configuration synchronization plugin on the Central Management node, complete the following steps.

  1. Open a transaction.

    For more information, see Open a transaction.

  2. To disable the plugin, replace /api/cluster/configuration_sync_plugin with:
    {
    "enabled": false
}

    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": false}'

    The following is a sample response received:

    {
    "plugin": {
        "key": null,
        "meta": {}
    }
}
  3. Commit your changes.

    For more information, see Commit a transaction.

Configuration tools in SPS

A list of tools that can help with the configuration of SPS.

URL
GET https://<IP-address-of-SPS>/api/tools/
Cookies
Cookie name Description Required Values
session_id Contains the authentication token of the user Required

The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Authenticate to the SPS REST API.

NOTE: This session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS records (and which also have a session ID, but in a different format)..
Sample request

The following command lists available configuration tools in SPS.

curl -X GET -b "${COOKIE_PATH}" https://<IP-address-of-SPS>/api/tools/
Response

The following is a sample response received when the available configuration tools are listed.

For details of the meta object, see Message format.

{
     "items": [
       {
         "key": "hosts-by-name",
         "meta": {
           "href": "/api/tools/hosts-by-name"
         }
       },
       {
         "key": "ldaptest",
         "meta": {
           "href": "/api/tools/ldaptest"
         }
       }
     ],
     }
Item

Description
Resolving hostnames to IP addresses

Resolve the hostname of a computer or server to IP addresses.

Testing LDAP server connection Test LDAP server connection.
HTTP response codes

For more information and a list of standard HTTP response codes, see Application level error codes.

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating