One Identity Safeguard for Privileged Sessions 6.9.3

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 System backup policy Encrypting system backup policy

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

Trust stores

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 channels 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

MSSQL connections

Limitations in handling MSSQL connections MSSQL connections MSSQL connection policies MSSQL channels MSSQL authentication policies Global MSSQL options MSSQL 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 Telnet channels Telnet authentication policies Global Telnet options Telnet pattern sets

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 Generate and retrieve screenshot for content search 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

Upload a plugin Delete a plugin Check the integrity of a plugin

Authentication and authorization plugins

Configuring Authentication and Authorization plugin instances

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

Global ICA options

Citrix ICA connections > Global ICA options

List of options that affect all ICA connections.

URL

GET https://<IP-address-of-SPS>/api/configuration/ica/options

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 that 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).

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 that 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 global ICA options.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/ica/options

Response

The following is a sample response received when listing global ICA options.

For details of the meta object, see Message format.

{
  "body": {
    "audit": {
      "cleanup": {
        "enabled": false
      },
      "timestamping": {
        "selection": "local",
        "signing_interval": 30
      }
    },
    "service": {
      "enabled": true,
      "log_level": 4
    }
  },
  "key": "options",
  "meta": {
    "first": "/api/configuration/ica/channel_policies",
    "href": "/api/configuration/ica/options",
    "last": "/api/configuration/ica/settings_policies",
    "next": "/api/configuration/ica/settings_policies",
    "parent": "/api/configuration/ica",
    "previous": "/api/configuration/ica/channel_policies",
    "transaction": "/api/transaction"
  }
}

Element			Type	Description
key			Top level item	Contains the ID of the endpoint.
body			Top level item	Contains the elements of the global ICA options.
	audit		Top level item	Contains settings for timestamping and cleanup.
	service		Top level item	Global setting to enable ICA connections, and specify the logging detail.
		enabled	boolean	Set to true to enable ICA connections.
		log_level	int	Defines the logging detail of ICA connections.

Elements of audit			Type	Description
cleanup			Top level item	Global retention settings for ICA connection metadata. To configure retention time for a specific connection policy, use the archive_cleanup_policy element at the endpoint of the policy instead.
	channel_database_cleanup_days		int	Global retention time for the metadata of ICA connections, in days. Must exceed the retention time of the archiving policy (or policies) used for ICA connections, and the connection-specific database cleanup times (if configured).
	enabled		boolean	To enable the global cleanup of ICA connection metadata, set this element to true.
timestamping			Top level item	Global timestamping settings for ICA connections.
	selection		string	Configures local or remote timestamping. Set local to use SPS for timestamping. Set remote to configure a remote timestamping server.
	server_url		string	Required for remote timestamping. The URL of the timestamping server. Note that HTTPS and password-protected connections are not supported.
	oid		Top level item	The Object Identifier of the policy used for timestamping.
		enabled	boolean	Required for remote timestamping. Set to true to configure the Object Identifier of the timestamping policy on the timestamping remote server.
		policy_oid	string	Required if the oid is enabled. The Object Identifier of the timestamping policy on the remote timestamping server.
	signing_interval		int	Time interval for timestamping open connections, in seconds.

Examples:

Set SPS as the timestamping server:

{
  "audit": {
    "cleanup": {
      "enabled": false
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Enable cleanup, and set it to occur every 10 days:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, without specifying a timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": false
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, and specify the 1.2.3 timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": true,
          "policy_oid": "1.2.3"
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Modify global ICA settings

To modify global ICA settings, you have to:

Open a transaction.

For details, see Open a transaction.
Modify the JSON object of the global ICA settings endpoint.

PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/ica/options endpoint. You can find a detailed description of the available parameters listed in Element . The elements of the audit item are described in Elements of audit.
Commit your changes.

For details, see Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Application level error codes.

Code	Description	Notes
201	Created	The new resource was successfully created.
401	Unauthenticated	The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
403	Unauthorized	The requested resource cannot be retrieved because the client is not authorized to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
404	NotFound	The requested object does not exist.

ICA settings policies

Citrix ICA connections > ICA settings policies

ICA settings policies define protocol-level settings (timeout, reliability). You can create multiple policies, and choose the appropriate one for each ICA connection.

URL

GET https://<IP-address-of-SPS>/api/configuration/ica/settings_policies

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 that 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).

Cookie name

Description

Required

Values

session_id

Contains the authentication token of the user

Required

Sample request

The following command lists ICA settings policies.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/ica/settings_policies

The following command retrieves the properties of a specific policy.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/ica/settings_policies/<policy-id>

Response

The following is a sample response received when listing ICA settings policies.

For details of the meta object, see Message format.

{
  "items": [
    {
      "key": "-301101020",
      "meta": {
        "href": "/api/configuration/ica/settings_policies/-301101020"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/ica/channel_policies",
    "href": "/api/configuration/ica/settings_policies",
    "last": "/api/configuration/ica/settings_policies",
    "next": null,
    "parent": "/api/configuration/ica",
    "previous": "/api/configuration/ica/options",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific policy, the response is the following.

{
  "body": {
    "name": "default",
    "timeout": 600,
    "inactivity_timeout": {
      "enabled": true
      "value": 13000
    },
    "preconnect_channel_check": false,
    "reliability": {
      "reconnect_attempts": 30,
      "reconnect_sleep": 2,
      "reconnect_timeout": 600
    },
    "timeout": 600
  },
  "key": "-301101020",
  "meta": {
    "first": "/api/configuration/ica/settings_policies/-301101020",
    "href": "/api/configuration/ica/settings_policies/-301101020",
    "last": "/api/configuration/ica/settings_policies/-301101020",
    "next": null,
    "parent": "/api/configuration/ica/settings_policies",
    "previous": null,
    "transaction": "/api/transaction"
  }
}

Element			Type	Description
key			string	Top level element, contains the ID of the policy.
body			Top level element (string)	The elements of the ICA settings policy.
	name		string	Name of the ICA settings policy. Cannot contain whitespace.
	preconnect_channel_check		boolean	Before establishing the server-side connection, SPS can evaluate the connection and channel policies to determine if the connection might be permitted at all. The server-side connection is established only if the evaluated policies permit the client to access the server. To enable this function, set the parameter to true.
	reliability		Top level item	Settings for ICA connection attempts.
	timeout		int	Connection timeout, in seconds.
	inactivity_timeout		Top level element
		enabled	boolean	true: If no user activity is detected, it terminates the session after the configured time has passed since the last user activity. false: No user inactivity timeout.
		value	int	Only if enabled is true The value of user activity timeout. Must be greater than or equal to the value of timeout

Elements of reliability	Type	Description
reconnect_attempts	int	The number of times SPS attempts to connect to the target server.
reconnect_sleep	int	The number of seconds SPS waits between connection attempts.
reconnect_timeout	int	The number of seconds SPS waits after exhausting the number of reconnect_attempts.

Add ICA settings policies

To add a settings policy, you have to:

Open a transaction.

For details, see Open a transaction.
Create the JSON object for the new policy.

POST the JSON object to the https://<IP-address-of-SPS>/api/configuration/ica/settings_policies/ endpoint. You can find a detailed description of the available parameters listed in the parameter list table.

If the POST request is successful, the response includes the key of the new policy. For example:
```
{
  "key": "dcd58077-98b3-4c73-8f0b-b34147863028",
  "meta": {
    "href": "/api/configuration/ica/settings_policies/dcd58077-98b3-4c73-8f0b-b34147863028",
    "parent": "/api/configuration/ica/settings_policies",
    "transaction": "/api/transaction"
  }
}
```
Commit your changes.

For details, see Commit a transaction.

Modify ICA settings policies

To modify a settings policy, you have to:

Open a transaction.

For details, see Open a transaction.
Modify the JSON object of the policy.

PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/ica/settings_policies/<key-of-the-object> endpoint. You can find a detailed description of the available parameters listed in the parameter list table.
Commit your changes.

For details, see Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Application level error codes.

Code	Description	Notes
201	Created	The new resource was successfully created.
401	Unauthenticated	The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
403	Unauthorized	The requested resource cannot be retrieved because the client is not authorized to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
404	NotFound	The requested object does not exist.

MSSQL connections

Topics:

Limitations in handling MSSQL connections

MSSQL connections

MSSQL connection policies

MSSQL channels

MSSQL authentication policies

Global MSSQL options

MSSQL settings policies

Limitations in handling MSSQL connections

MSSQL connections > Limitations in handling MSSQL connections

The current version of One Identity Safeguard for Privileged Sessions (SPS) has the following limitations:

TDS protocol version 7.3 or later is required.
Due to the TDS protocol version requirement, Microsoft® SQL Server® 2008, or later, is recommended.
The Require Gateway Authentication on the SPS Web Interface option in MSSQL Control > Connections does not work in case of MSSQL connections.
MSSQL server with TCP dynamic port settings is not supported.

You must specify a static TCP port for every instance in the SQL Server Configuration Manager you want to audit. By doing so, you can configure the access to multiple MSSQL instances with multiple connection policies and specify the instances with inband or fixed targets and ports. You can also create and assign different Credential Store policies to check out SQL users' passwords of the instances.

In the MSSQL client program, always specify the address with the port number of the SPS connection policy you want to connect to.

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.9.3 - REST API Reference Guide

Global ICA options

URL

Cookies

Sample request

Response

Examples:

Modify global ICA settings

Open a transaction.

Modify the JSON object of the global ICA settings endpoint.

Commit your changes.

Status and error codes

ICA settings policies

URL

Cookies

Sample request

Response

Add ICA settings policies

Open a transaction.

Create the JSON object for the new policy.

Commit your changes.

Modify ICA settings policies

Open a transaction.

Modify the JSON object of the policy.

Commit your changes.

Status and error codes

MSSQL connections

Topics:

Limitations in handling MSSQL connections