One Identity Safeguard for Privileged Sessions 7.2.1

Contains the configuration endpoints for managing SPS.

URL

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

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 more information 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 management configuration endpoints.

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

Response

The following is a sample response received when listing management endpoints.

For more information on the meta object, see Message format.

{
  "items": [
    {
      "key": "certificates",
      "meta": {
        "href": "/api/configuration/management/certificates"
      }
    },
    {
      "key": "disk_fillup_prevention",
      "meta": {
        "href": "/api/configuration/management/disk_fillup_prevention"
      }
    },
    {
      "key": "email",
      "meta": {
        "href": "/api/configuration/management/email"
      }
    },
    {
      "key": "exported_configuration_encryption",
      "meta": {
        "href": "/api/configuration/management/exported_configuration_encryption"
      }
    },
    {
      "key": "health_monitoring",
      "meta": {
        "href": "/api/configuration/management/health_monitoring"
      }
    },
    {
      "key": "license",
      "meta": {
        "href": "/api/configuration/management/license"
      }
    },
    {
      "key": "root_password",
      "meta": {
        "href": "/api/configuration/management/root_password"
      }
    },
    {
      "key": "snmp",
      "meta": {
        "href": "/api/configuration/management/snmp"
      }
    },
    {
      "key": "splunk_forwarder",
      "meta": {
        "href": "/api/configuration/management/splunk_forwarder"
      }
    },
    {
      "key": "support_info",
      "meta": {
        "href": "/api/configuration/management/support_info"
      }
    },
    {
      "key": "syslog",
      "meta": {
        "href": "/api/configuration/management/syslog"
      }
    },
    {
      "key": "system_backup",
      "meta": {
        "href": "/api/configuration/management/system_backup"
      }
    },
    {
      "key": "universal_siem_forwarder",
      "meta": {
        "href": "/api/configuration/management/universal_siem_forwarder"
      }
    },
    {
      "key": "web_gateway_authentication",
      "meta": {
        "href": /api/configuration/management/web_gateway_authentication"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/management",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/network",
    "parent": "/api/configuration",
    "previous": "/api/configuration/local_services",
    "transaction": "/api/transaction"
  }
}

Endpoints	Description
certificates	References the certificates of SPS's internal Certificate Authority, Timestamping Authority, and the SSL certificate of the web interface.
disk_fillup_prevention	Disk fill-up prevention.
email	SMTP server address and authentication, administrator e-mail, and e-mail addresses for alerts and reports.
exported_configuration_encryption	SMTP server address and authentication, administrator e-mail, and e-mail addresses for alerts and reports.
health_monitoring	Configuration settings for monitoring the utilization of SPS.
snmp	SNMP settings.
syslog	Syslog server address and authentication.
web_gateway_authentication	Configuration of the banner on the login screen before web gateway authentication.

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

Web gateway authentication

Use the /web_gateway_authentication endpoint to configure tha banner on the login screen before web gateway authentication in order to make users aware of being audited before logging in, or that they are accessing a government website, and so on.

URL

PUT https://<IP-address-of-SPS>/api/configuration/management/web_gateway_authentication

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 more information 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).

Operations with the /web_gateway_authentication endpoint include:

Operation	HTTP method	URL
Configuring the web gateway authentication banner	PUT	/api/configure/management/web_gateway_authentication
Querying the web gateway authentication banner	GET	/api/configure/management/web_gateway_authentication

Sample request

The following command configures the web gateway authentication banner.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/management/web_gateway_authentication

Response

The following is a sample response when the configured web gateway authentication banner is queried.

For more information on the meta object, see Message format.

{
      "key": "web_gateway_authentication",
      "body": {
        "auto_assign": false,
        "banner": {
          "enabled": true,
          "text": "Web gateway\nBANNER"
        }
      }
    }

Elements of the response message body include:

Element	Type	Description
key	string	Top level element, contains the ID of the endpoint.
body	object	Top level element.
body.auto_assign	boolean	Enable auto-assign to permit your users to authenticate on the SPS web interface once, and open sessions without repeating the gateway authentication.
body.banner	object	Top level element.
body.banner.enabled	boolean	Shows whether the banner is enabled or not.
body.banner.text	string	The text of the banner.

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
400	InvalidRequestBody	The request body sent by the user has an invalid format. This may be an error with the encoding or the body is not a properly encoded JSON value.
400	SemanticError	The configuration contains semantic errors, inconsistencies or other problems that would put the system into an unreliable state if the configuration had been applied. The details section contains the errors that were found in the configuration.
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.

Syslog server settings

SPS can send its system log messages to remote syslog servers, for example, syslog-ng Premium Edition, syslog-ng Store Box, Splunk, or HPE ArcSight Data Platform.

URL

GET https://<IP-address-of-SPS>/api/configuration/management/syslog

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 more information 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 the syslog server settings.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/management/syslog

Response

The following is a sample response received when listing syslog server settings.

For more information on the meta object, see Message format.

{
  "body": {
    "certificates": {
      "ca": "<ca-cert>",
      "client": {
        "key": "191725ec-b71b-47ab-9e87-561a5d9e2bb7",
        "meta": {
          "href": "/api/configuration/x509/191725ec-b71b-47ab-9e87-561a5d9e2bb7"
        }
      }
    },
    "include_node_id": true,
    "receivers": [
      {
        "address": {
          "selection": "ip",
          "value": "10.20.30.40"
        },
        "port": 514,
        "protocol": {
          "ip_protocol": "tcp",
          "protocol_type": "legacy-bsd",
          "tls_enabled": false
        }
      }
    ],
    "server_key_check": "optional-trusted"
  },
  "key": "syslog",
  "meta": {
    "first": "/api/configuration/management/certificates",
    "href": "/api/configuration/management/syslog",
    "last": "/api/configuration/management/webinterface",
    "next": "/api/configuration/management/webinterface",
    "parent": "/api/configuration/management",
    "previous": "/api/configuration/management/snmp",
    "transaction": "/api/transaction"
  }
}

Element			Type	Description
key			string	Top level element, contains the ID of the endpoint.
body			Top level element (string)	Contains the syslog server configuration settings.
	certificates		Top level item	Contains the certificates of the client (SPS), and the certificate of the CA.
		ca	string	The CA certificate of the Certificate Authority. Configure this option if the value of the tls_enabled element is set to true.
		client	string	Configure this option if the value of the tls_enabled element is set to true, and the syslog server requires mutual authentication. Otherwise, set its value to null. References the identifier of the client's (SPS's) X.509 certificate. You can configure certificates at the /api/configuration/x509/ endpoint. To modify or add an X.509 certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).
	include_node_id		boolean	Set to true to display separate hostnames for syslog messages sent by the nodes of a SPS HA cluster. The node ID included in the hostname filed of the syslog message is the MAC address of the node's HA interface. Messages of the core firmware are always sent by the master node.
	receivers		Top level list	Contains the addresses of the syslog servers.
	server_key_check		string	Configures validating the syslog server's certificate with the CA. The following values are possible: optional-trusted If the server sends a certificate, SPS checks if it is valid (not expired) and that the Common Name of the certificate contains the domain name or the IP address of the server. If these checks fail, SPS rejects the connection. However, SPS accepts the connection if the server does not send a certificate. optional-untrusted SPS accepts any certificate shown by the server. required-trusted SPS verifies the certificate shown by the server. required-untrusted SPS requests a certificate from the server, and rejects the connection if no certificate is received, if the certificate is not valid (expired), or if the Common Name of the certificate does not contain the domain name or the IP address of the server.

Elements of receivers		Type	Description
address		Top level item	Contains the address of the syslog server.
	selection	string	Defines the address type (IP or domain name). Possible values are: fqdn The server address is provided as a fully qualified domain name. ip The server address is provided as an IP address.
	value	string	The address of the syslog server, corresponding to the format set in the selection field.
port		int	The port of the syslog server.
protocol		Top level item	Contains the syslog protocol settings.
	ip_protocol	string	Configures the IP protocol. The following options are available: tcp TCP protocol. udp UDP protocol.
	protocol_type	string	Configures the syslog protocol. The following options are available: legacy-bsd BSD-syslog protocol. syslog IETF-syslog protocol.
	tls_enabled	string	Set to true to enable TLS encryption. If TLS is enabled, the value of the ca and client elements cannot be null.

Examples:

Default settings: no external syslog servers.

{
  "certificates": {
    "ca": null,
    "client": null
  },
  "include_node_id": true,
  "receivers": [],
  "server_key_check": "optional-untrusted"
}

Upload CA certificates

SPS uses only the key part of the CA certificate.

You can choose to upload a single certificate or a certificate chain.

To use a certificate with the SPS API, remove all data, and substitute line breaks with \n. The same is true for a certificate chain: copy individual certificates one after the other, and substitute line breaks with \n.

The following is an example certificate, as used on the SPS web interface:

The same certificate, as accepted by the SPS API:

"certificate": "-----BEGIN CERTIFICATE-----\nMIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC\nQ0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT\nB0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi\naXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2\nMDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP\nbnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD\nVQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN\nAQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC\nAQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS\n59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw\n0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc\n3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs\nX5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX\nhJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA\nR5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP\nAB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy\n0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB\nuNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc\nN5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt\nqYyyD1ld89OUEYZ+aJQd/A==\n-----END CERTIFICATE-----\n"

Modify syslog server settings

To modify the syslog server settings, you have to:

Open a transaction

For more information, 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/management/syslog endpoint. You can find a detailed description of the available parameters listed in Element.
Commit your changes

For more information, 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.

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

Logs, monitoring and alerts

Management options

URL

Cookies

Sample request

Response

Status and error codes

Web gateway authentication

URL

Cookies

Sample request

Response

Status and error codes

Syslog server settings

URL

Cookies

Sample request

Response

Examples:

Upload CA certificates

Modify syslog server settings

Open a transaction

Modify the JSON object of the endpoint.

Commit your changes

Status and error codes

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

Logs, monitoring and alerts

Management options

URL

Cookies

Sample request

Response

Status and error codes

Web gateway authentication

URL

Cookies

Sample request

Response

Status and error codes

Syslog server settings

URL

Cookies

Sample request

Response

Examples:

Upload CA certificates

Modify syslog server settings

Open a transaction

Modify the JSON object of the endpoint.

Commit your changes

Status and error codes