One Identity Safeguard for Privileged Sessions 6.0.5

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

DNS servers

Basic settings > Network settings > DNS servers

Contains the address of the primary and secondary DNS server.

URL

GET https://<IP-address-of-SPS>/api/configuration/network/dns

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 the configured DNS servers.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/network/dns

Response

The following is a sample response received when listing the configured DNS servers.

For details of the meta object, see Message format.

{
  "body": {
    "primary": "192.168.56.1",
    "secondary": null
  },
  "key": "dns",
  "meta": {
    "first": "/api/configuration/network/dns",
    "href": "/api/configuration/network/dns",
    "last": "/api/configuration/network/routing",
    "next": "/api/configuration/network/ip_forwarding_rule_pairs",
    "parent": "/api/configuration/network",
    "previous": null,
    "transaction": "/api/transaction"
  }
}

Element		Type	Description
key		string	Top level element, contains the ID of the endpoints.
body		Top level element (string)	Contains the addresses of the DNS servers.
	primary	string	The IP address of the primary DNS server.
	secondary	string	The address of the secondary DNS server.

Modify the address of the DNS servers

To modify the address of a DNS server, you have to:

Open a transaction.

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

PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/network/dns endpoint. You can find a detailed description of the available parameters listed in Element .
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.
401	AuthenticationFailure	Authenticating the user with the given credentials has failed.
404	NotFound	The requested object does not exist.

Routing between interfaces

Basic settings > Network settings > Routing between interfaces

Configures routing between network interfaces. To use an interface in single-interface router mode, configure both interface_a and interface_b elements to reference that same interface.

URL

GET https://<IP-address-of-SPS>/api/configuration/network/ip_forwarding_rule_pairs

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 interface routing rules.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/network/ip_forwarding_rule_pairs

Response

The following is a sample response received when listing interface routing rules.

For details of the meta object, see Message format.

{
  "body": [
    {
      "interface_a": {
        "key": "nic1.interfaces.ff7574025754b3df1647001",
        "meta": {
          "href": "/api/configuration/network/nics/nic1/interfaces/ff7574025754b3df1647001"
        }
      },
      "interface_b": {
        "key": "nic1.interfaces.ff7574025754b3df1647001",
        "meta": {
          "href": "/api/configuration/network/nics/nic1/interfaces/ff7574025754b3df1647001"
        }
      }
    }
  ],
  "key": "ip_forwarding_rule_pairs",
  "meta": {
    "first": "/api/configuration/network/dns",
    "href": "/api/configuration/network/ip_forwarding_rule_pairs",
    "last": "/api/configuration/network/routing",
    "next": "/api/configuration/network/naming",
    "parent": "/api/configuration/network",
    "previous": "/api/configuration/network/dns",
    "transaction": "/api/transaction"
  }
}

Element		Type	Description
key		string	Top level element, contains the ID of the endpoint.
body		Top level element (list)	Contains the rules for routing between the network interfaces.
	interface_a	string	References the identifier of the network interface. You can configure network interfaces at the /api/configuration/network/nics/ endpoint. To modify or add a network interface, use the value of the returned key as the value of the interface_a element, and remove any child elements (including the key).
	interface_b	string	References the identifier of the network interface. You can configure network interfaces at the /api/configuration/network/nics/ endpoint. To modify or add a network interface, use the value of the returned key as the value of the interface_b element, and remove any child elements (including the key).

Add a rule for routing between the network interfaces

To add a rule, you have to:

Open a transaction.

For details, see Open a transaction.
Create the JSON object for the new list of rules.

POST the JSON object to the https://<IP-address-of-SPS>/api/configuration/network/ip_forwarding_rule_pairs endpoint. You can find a detailed description of the available parameters listed in Element .

If the POST request is successful, the response includes the key of the new rule.
Commit your changes.

For details, see Commit a transaction.

Modify a rule for routing between the network interfaces

To modify a rule, you have to:

Open a transaction.

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

PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/network/ip_forwarding_rule_pairs endpoint. You can find a detailed description of the available parameters listed in Element .
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.
401	AuthenticationFailure	Authenticating the user with the given credentials has failed.
404	NotFound	The requested object does not exist.

Naming options

Basic settings > Network settings > Naming options

Contains the settings for the DNS search domain, hostname, and appliance nickname.

URL

GET https://<IP-address-of-SPS>/api/configuration/network/naming

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 the naming settings.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/network/naming

Response

The following is a sample response received when listing naming settings.

For details of the meta object, see Message format.

{
  "body": {
    "domainname": "example",
    "hostname": "api-docs",
    "nickname": null
  },
  "key": "naming",
  "meta": {
    "first": "/api/configuration/network/dns",
    "href": "/api/configuration/network/naming",
    "last": "/api/configuration/network/routing",
    "next": "/api/configuration/network/nics",
    "parent": "/api/configuration/network",
    "previous": "/api/configuration/network/ip_forwarding_rule_pairs",
    "transaction": "/api/transaction"
  }
}

Element		Type	Description
key		string	Top level element, contains the ID of the endpoint.
body		Top level element (string)	Contains the naming settings.
	domainname	string	The domain name of the network.
	hostname	string	The hostname of SPS.
	nickname	string	The nickname for the appliance. Use this name to distinguish between multiple SPS appliances on the network. This name is visible in the boot and core login shells.

Modify a name

To modify a name, you have to:

Open a transaction.

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

PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/network/naming endpoint. You can find a detailed description of the available parameters listed in Element .
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.
401	AuthenticationFailure	Authenticating the user with the given credentials has failed.
404	NotFound	The requested object does not exist.

Network addresses

Basic settings > Network settings > Network addresses

Contains the network addresses configured for each physical NIC.

URL

GET https://<IP-address-of-SPS>/api/configuration/network/nics

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 the endpoints for the physical network interfaces.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/network/nics/

The following commands retrieve the properties of a specific physical network interface.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/network/nics/nic1

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/network/nics/nic2

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/network/nics/nic3

Response

The following is a sample response received when listing physical network interfaces.

For details of the meta object, see Message format.

{
  "items": [
    {
      "key": "nic1",
      "meta": {
        "href": "/api/configuration/network/nics/nic1"
      }
    },
    {
      "key": "nic2",
      "meta": {
        "href": "/api/configuration/network/nics/nic2"
      }
    },
    {
      "key": "nic3",
      "meta": {
        "href": "/api/configuration/network/nics/nic3"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/network/dns",
    "href": "/api/configuration/network/nics",
    "last": "/api/configuration/network/routing",
    "next": "/api/configuration/network/routing",
    "parent": "/api/configuration/network",
    "previous": "/api/configuration/network/naming",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific physical network interface, the response is the following.

{
  "body": {
      "interfaces": {
          "@order": ["ff7574025754b3df1647001"],
          "ff7574025754b3df1647001": {
              "addresses": {
                  "1": "198.51.100.123/24",
                  "6001481625b7c21ef97598": "2001:db8:1234::5678/48",
                  "@order": ["1", "6001481625b7c21ef97598"]
              },
              "mtu": 1500,
              "name": "external",
              "source_based_routes": [
                  {
                      "gateway": "198.51.100.1",
                      "target_network": "203.0.113.0/24"
                  },
                  {
                      "gateway": "2001:db8:1234::1",
                      "target_network": "2001:db8:aaaa::/48"
                  }
              ],
              "vlantag": 0
          }
      },
      "name": "eth0",
      "speed": "auto"
  },
  "key": "nic1",
  "meta": {
      "first": "/api/configuration/network/nics/nic1",
      "href": "/api/configuration/network/nics/nic1",
      "last": "/api/configuration/network/nics/nic3",
      "next": "/api/configuration/network/nics/nic2",
      "parent": "/api/configuration/network/nics",
      "previous": null,
      "remaining_seconds": 10800,
      "transaction": "/api/transaction"
  }
}

Element		Type	Description
key		string	Top level element, contains the ID of the physical network interface (nic1, nic2 or nic3).
body		Top level element (string)	Contains the properties of the physical network interface.
	interfaces	Top level item	Contains the configuration of all virtual interfaces on the physical NIC.
	name	string	The system name of the physical network interface (eth0, eth1 or eth2). Do not change this value.
	speed	string	The speed of the physical network interface. The default value is auto. Change this setting only for troubleshooting purposes. Possible values are: auto Negotiate the network speed automatically. This is the default value. 10-half 10BaseT/Half. 100-half 100BaseT/Half. 10-full 10BaseT/Full. 100-full 100BaseT/Full. 1000-full 1000BaseT/Full.

Elements of interfaces

Type

Description

@order

list

Lists the keys of the interfaces in the order they are be displayed on the SPS web UI.

<key-of-an-interface>

string

Contains the addresses, name, and vlantag of the network interface.

Each physical NIC has an automatically created interface key, where the value of the vlanid element is set to 0.

To add a valid virtual network interface to the physical NIC, create an additional interface, and assign a value between 1 and 4094 to its vlanid element.

addresses

string

Contains the addresses of the interface, and their display order.

<key-of-address>

string

Contains the IP address range.

@order

list

Lists the keys of the addresses in the order they are displayed on the SPS web UI.

mtu

integer

Maximum Transmission Unit (MTU) to set per network interface (VLAN or network interface card). Default value: 1500

name

string

The name of the interface, as displayed on the SPS web UI.

source_based_routes

list

Contains details of the network routing rule specific to packets coming out of this particular interface.

vlantag

string

The ID of the interface.

For the physical interface, the value is 0. For virtual interfaces, the value is between 1 and 4094.

Caution:

Do not set the VLAN ID unless your network environment is already configured to use this VLAN. Otherwise, your SPS appliance will be unavailable using this interface.

Elements of source_based_routes	Type	Description
gateway	string	The IPv4 or IPv6 address of the gateway used to access the network set in this routing rule.
target_network	string	The IPv4 or IPv6 address of the host or network accessible via this routing rule.

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
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.
401	AuthenticationFailure	Authenticating the user with the given credentials has failed.
404	NotFound	The requested object does not exist.

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

DNS servers

URL

Cookies

Sample request

Response

Modify the address of the DNS servers

Open a transaction.

Modify the JSON object of the endpoint.

Commit your changes.

Status and error codes

Routing between interfaces

URL

Cookies

Sample request

Response

Add a rule for routing between the network interfaces

Open a transaction.

Create the JSON object for the new list of rules.

Commit your changes.

Modify a rule for routing between the network interfaces

Open a transaction.

Modify the JSON object of the list of rules.

Commit your changes.

Status and error codes

Naming options

URL

Cookies

Sample request

Response

Modify a name

Open a transaction.

Modify the JSON object of the endpoint.

Commit your changes.

Status and error codes

Network addresses

URL

Cookies

Sample request

Response

Status and error codes