Chat now with support
Chat with Support

One Identity Safeguard for Privileged Sessions 7.0.5.1 LTS - 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

Alerting

Contains the endpoints for configuring alerting on SPS.

URL
GET https://<IP-address-of-SPS>/api/configuration/alerting
Sample request

The following command lists alerting configuration endpoints.

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

The following is a sample response received when listing alerting configuration endpoints.

{
  "items": [
    {
      "key": "system_alerts",
      "meta": {
        "href": "/api/configuration/alerting/system_alerts"
      }
    },
    {
      "key": "traffic_alerts",
      "meta": {
        "href": "/api/configuration/alerting/traffic_alerts"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/alerting",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/datetime",
    "parent": "/api/configuration",
    "previous": "/api/configuration/aaa",
    "transaction": "/api/transaction"
  }
}
Element Description
system_alerts Configuration options for system-related alerts.
traffic_alerts Configuration options for traffic-related alerts.
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.

System alerts

Configuration options for sending system-related alerts.

E-mail alerts, when enabled, are sent to the e-mail address configured in the alerting_address element of the /api/configuration/management/email endoint.

SNMP alerts, when enabled, are sent to the SNMP server configured at the /api/configuration/management/snmp/trap endpoint.

URL
GET https://<IP-address-of-SPS>/api/configuration/alerting/system_alerts
Sample request

The following command lists configuration options for system-related alerts.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/alerting/system_alerts
Response

The following is a sample response received when listing configuration options for system-related alerts.

{
  "body": {
    "xcbAlert": {
      "email": false,
      "snmp": false
    },
    "xcbArchiveFailed": {
      "email": false,
      "snmp": false
    },
    "xcbBackupFailed": {
      "email": false,
      "snmp": false
    },
    "xcbBruteForceAttempt": {
      "email": false,
      "snmp": false
    },
    "xcbConfigChange": {
      "email": false,
      "snmp": false
    },
    "xcbDBError": {
      "email": false,
      "snmp": false
    },
    "xcbDiskFull": {
      "email": false,
      "snmp": false
    },
    "xcbError": {
      "email": false,
      "snmp": false
    },
    "xcbFirmwareTainted": {
      "email": false,
      "snmp": false
    },
    "xcbHWError": {
      "email": false,
      "snmp": false
    },
    "xcbHaNodeChanged": {
      "email": false,
      "snmp": false
    },
    "xcbLicenseAlmostExpired": {
      "email": false,
      "snmp": false
    },
    "xcbLimitReached": {
      "email": false,
      "snmp": false
    },
    "xcbLoadAvgHigh": {
      "email": false,
      "snmp": false
    },
    "xcbLogin": {
      "email": false,
      "snmp": false
    },
    "xcbLoginFailure": {
      "email": false,
      "snmp": false
    },
    "xcbLogout": {
      "email": false,
      "snmp": false
    },
    "xcbRaidStatus": {
      "email": false,
      "snmp": false
    },
    "xcbSwapFull": {
      "email": false,
      "snmp": false
    },
    "xcbTimeSyncLost": {
      "email": false,
      "snmp": false
    },
    "xcbTimestampError": {
      "email": false,
      "snmp": false
    }
  },
  "key": "system_alerts",
  "meta": {
    "first": "/api/configuration/alerting/system_alerts",
    "href": "/api/configuration/alerting/system_alerts",
    "last": "/api/configuration/alerting/traffic_alerts",
    "next": "/api/configuration/alerting/traffic_alerts",
    "parent": "/api/configuration/alerting",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key string Top level element, contains the ID of the endpoint.
body Top level element (string) Contains the configuration options for system-related alerts.
xcbAlert Top level item General alert.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbArchiveFailed Top level item Data archiving failure.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbBackupFailed Top level item Data and configuration backup failure.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbBruteForceAttempt Top level item Too many successive failed login attempts.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbConfigChange Top level item Configuration change.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbDBError Top level item Database error occured.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbDiskFull Top level item Disk utilization reached the percentage configured in the maximum_disk_utilization_ratio element of the api/configuration/management/monitoring endpoint.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbError Top level item General error.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbFirmwareTainted Top level item The firmware is tainted.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbHWError Top level item Hardware error.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbHaNodeChanged Top level item HA node state changed.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbLicenseAlmostExpired Top level item License expires soon.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbLimitReached Top level item License limit reached.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbLoadAvgHigh Top level item The average load exceeded any of the values configured in the maximum_load1, maximum_load5 or maximum_load15 elements of the api/configuration/management/monitoring endpoint.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbLogin Top level item Successful login.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbLoginFailure Top level item Failed login.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbLogout Top level item Logout from the web configuration interface.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbRaidStatus Top level item RAID status changed.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbSwapFull Top level item The utilization of the swap exceeded the value configured in the maximum_swap_utilization_ratio element of the api/configuration/management/monitoring endpoint.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbTimeSyncLost Top level item Time sync lost.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
xcbTimestampError Top level item Time stamping error.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
Modify a system-related alert

To enable or disable an alert, you have to:

  1. Modify the JSON object of the endpoint.

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

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.

Traffic alerts

Configuration options for sending traffic-related alerts.

E-mail alerts, when enabled, are sent to the e-mail address configured in the alerting_address element of the /api/configuration/management/email endoint.

SNMP alerts, when enabled, are sent to the SNMP server configured at the /api/configuration/management/snmp/trap endpoint.

URL
GET https://<IP-address-of-SPS>/api/configuration/alerting/traffic_alerts
Sample request

The following command lists the configuration options for traffic-related alerts..

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/alerting/traffic_alerts
Response

The following is a sample response received when listing the configuration options for traffic-related alerts.

{
  "body": {
    "scbAuthFailure": {
      "email": false,
      "snmp": false
    },
    "scbAuthSuccess": {
      "email": false,
      "snmp": false
    },
    "scbChannelDenied": {
      "email": false,
      "snmp": false
    },
    "scbConnectionDenied": {
      "email": false,
      "snmp": false
    },
    "scbConnectionFailed": {
      "email": false,
      "snmp": false
    },
    "scbConnectionTimedout": {
      "email": false,
      "snmp": false
    },
    "scbCredStoreClosed": {
      "email": false,
      "snmp": false
    },
    "scbCredStoreDecryptError": {
      "email": false,
      "snmp": false
    },
    "scbCredStoreUnlockFailure": {
      "email": false,
      "snmp": false
    },
    "scbGWAuthFailure": {
      "email": false,
      "snmp": false
    },
    "scbGWAuthSuccess": {
      "email": false,
      "snmp": false
    },
    "scbProtocolViolation": {
      "email": false,
      "snmp": false
    },
    "scbRealTimeAlert": {
      "email": false,
      "snmp": false
    },
    "scbSshHostKeyLearned": {
      "email": false,
      "snmp": false
    },
    "scbSshHostKeyMismatch": {
      "email": false,
      "snmp": false
    },
    "scbUserMappingFailure": {
      "email": false,
      "snmp": false
    }
  },
  "key": "traffic_alerts",
  "meta": {
    "first": "/api/configuration/alerting/system_alerts",
    "href": "/api/configuration/alerting/traffic_alerts",
    "last": "/api/configuration/alerting/traffic_alerts",
    "next": null,
    "parent": "/api/configuration/alerting",
    "previous": "/api/configuration/alerting/system_alerts",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key string Top level element, contains the ID of the endpoint.
body Top level element (string) Contains the configuration options for traffic-related alerts.
scbAuthFailure Top level item User authentication failed.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbAuthSuccess Top level item Successful user authentication.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbChannelDenied Top level item Channel opening denied.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbConnectionDenied Top level item Connection denied.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbConnectionFailed Top level item Connection to the server failed.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbConnectionTimedout Top level item Connection timed out.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbCredStoreClosed Top level item The requested credential store is closed.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbCredStoreDecryptError Top level item Failure to decrypt a credential.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbCredStoreUnlockFailure Top level item Failure to unlock the credential store.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbGWAuthFailure Top level item The user failed to authenticate on the gateway.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbGWAuthSuccess Top level item Successful authentication on the gateway.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbProtocolViolation Top level item Protocol violation.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbRealTimeAlert Top level item Real-time audit event detected.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbSshHostKeyLearned Top level item New SSH host key learned.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbSshHostKeyMismatch Top level item SSH host key mismatch.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbUserMappingFailure Top level item User mapping failed on the gateway.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
Modify a traffic-related alert

To enable or disable an alert, you have to:

  1. Modify the JSON object of the endpoint.

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

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.

Trust stores

Trust stores serve as local certificate storages where users can store the certificate chains of trusted Certificate Authorities (CAs). These certificates are then used to ensure secure communication between external parties and the SPS.

There are two types of trust stores: built-in and custom.

The built-in trust store has well known root CAs (such as Google, Microsoft, Verisign, etc.), and it is not modifiable.

Before establishing secure communication (TLS), SPS verifies the certificate of the other party using the assigned trust store. Only certificates signed by any of the CAs in the trust store are accepted.

NOTE: CRL URLs must be listed explicitly in the appropriate field, as those CRL URLs that are embedded in the extensions of the certificates, will be ignored.

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

Operations with the trust_stores endpoint include:

Operation

 

 HTTP method

URL

 Notes
Create a trust store POST /api/configuration/trust_stores The name of the trust store must be unique.
List trust stores GET /api/configuration/trust_stores

Users who were not given read access to the trust_stores endpoint explicitly, are still able to retrieve information from it, if they have access to other /configuration related endpoints, which reference trust stores.

Examples of trust store referrer ACL (read access):

  • /pages/starlingjoin
  • /config/xcb/aaa/settings
  • /config/scb/pol_ldaps

Query a trust store GET /api/configuration/trust_stores/<id of the trust store>  
Query the built-in trust store GET /api/configuration/trust_stores/-7001  
Update a trust store PUT /api/configuration/trust_stores/<id of the trust store>

Users who were not given access to the trust_stores endpoint explicitly, but are still able to retrieve information from it because they have access to configuration endpoints which reference trust stores, are unable to modify trust stores.

With the exception of /config/xcb/management, where the same access level is granted to the trust stores for the user as they have for /config/xcb/management.

Delete a trust store DELETE /api/configuration/trust_stores/<id of the trust store>  
Sample request

The following command lists the trust stores:

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

The following is a sample response received when listing trust stores.

 

{
                "items": [
                    {
                        "key": "-7001",
                        "meta": {
                            "href": "/api/configuration/trust_stores/-7001"
                        },
                        "body": {
                            "name": "Built-in",
                            "revocation_check": "none",
                            "trust_store_type": "built-in"
                        }
                    },
                    {
                        "key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
                        "meta": {
                            "href": "/api/configuration/trust_stores/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
                        },
                        "body": {
                            "name": "My_Custom_Trust_Store",
                            "authorities": [
                                {
                                    "fingerprint": {
                                        "digest": "01:25:1f:a2:df:2a:31:1a:29:7a:ba:43:c4:03:42:a5:d7:30:ec:2d:e0:d7:7a:72:a7:1b:c3:99:c5:6c:10:ea",
                                        "hash_algorithm": "sha256"
                                    },
                                    "issuer": "C=HU/ST=Budapest/L=None/O=Internet Widgits Pty Ltd/OU=None/CN=None/emailAddress=None",
                                    "pem": "-----BEGIN CERTIFICATE-----\nMIIDZzCCAk+gAwIBAgIUMlI5+EgTDAh2zqRDGYrzFRyozI8wDQYJKoZIhvcNAQEL\nBQAwQzELMAkGA1UEBhMCSFUxETAPBgNVBAgMCEJ1ZGFwZXN0MSEwHwYDVQQKDBhJ\nbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQwHhcNMTQwODEyMTIzNjQ4WhcNMzQwNjE4\nMTIzNjQ4WjBDMQswCQYDVQQGEwJIVTERMA8GA1UECAwIQnVkYXBlc3QxITAfBgNV\nBAoMGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDCCASIwDQYJKoZIhvcNAQEBBQAD\nggEPADCCAQoCggEBALffJBDD6A/ZGBTgFbyLXHulU+hGnMW3DoPo2q4HY1/FfbkS\nrzmK+Fiz+3EwJCWi+EwK9mqve/nh6YRRw/VaAVQ7CkA7f7to+I7gP647Bq1wk0lh\nBVEJNlN0jfYYSumGxzPotw/fon1MkXuMbLc0Pr/vFX3NQC7/STAV5dZFcdboXDA7\nZZ3rzBIr93ThObsGj01MRO6wrS3rfE7Px9D7C2u9YSkP3OQ1Sfm/jqyLNaT6xt4i\nhrLnfYEc8mClnrlvILi+q/D6mIUSjb4IGvergAyl4jgPjO02UcvBzOIA9tDlBJBi\nQxZx+T620ubmEwOl9Q0G8RAWKz7szrBcXEjXhYUCAwEAAaNTMFEwHQYDVR0OBBYE\nFCDfEeq5Hsm8jMrG110iNpt5cikTMB8GA1UdIwQYMBaAFCDfEeq5Hsm8jMrG110i\nNpt5cikTMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAK3iizM4\nCx69YD+4CWOUswULrCJA38C+nDYONLbNkact8JKXqCn/MaZTII+dZoV9RjjX4AzA\nPTQkZT+RoVeCZyt+qWHMdjq6koabXwQmXNozUtaxEZTrnoUDEWtNIbjV/gNtRcSG\nsU7i9L2YnwDzTw0cR/pu1Hykq8fwqNqjQGYnmXtJspMkKAtVe1CrtnPLiC6JBr0g\n5GZF58sHx5+gO0RkqdzJgRAGnImdfAahqfHmKRFmxoxWLyylRyqDgQ+KqcaDvZI+\ni36M+NQHVrDX4jo4CFoXhFlSOepvtDOpmzoWhugwDNMPuU1IEY7//CJBXQnjp+uf\nLO6PsNmMKDGi9Dk=\n-----END CERTIFICATE-----\n",
                                    "subject": "C=HU/ST=Budapest/L=None/O=Internet Widgits Pty Ltd/OU=None/CN=None/emailAddress=None"
                                }
                            ],
                            "crl_urls": [
                                "http://crl.it/sec"
                            ],
                            "revocation_check": "full",
                            "trust_store_type": "custom"
                        }
                    }
                ]
            }

Elements of the response message body include:

Elements of items

 

 Type

Description

 Notes
items

 

 object array

List of JSON objects available from the current endpoint.

  
 

key

string

The ID of the trust store.

Each trust store has a unique key.

The built-in trust store's ID is "-7001".

 

meta

string (uri)

The href field contains the URL of the trust store.

  
 

body

     
Elements of body

 

 Type

Description

 Notes
body

 

 object Top level element.  
 

name

string The name of the trust store.

The name field is set by the user and it must be unique.

For example:

"name": "My_Custom_Trust_Store".

The built-in trust store's name is "Built-in".

 

authorities

 

      
 

crl_urls

string array The crl_urls field contains the list of CRL web addresses (HTTP or HTTPs URLs) used for revocation check.

If a trust store that uses certificate revocation lists (CRLs) does not work properly, it might be due to invalid or inaccessible CRL URLs. Troubleshooting can involve checking whether all URLs of the CA CRL URL list are valid, and can be accessed from the SPS via the Basic Settings / Troubleshooting / Connect to TCP port function in the Web UI.

 

revocation_check

enum

The type of the revocation check.

Possible values: "full", "leaf", "none".

"full" - The crl_urls field must contain CRL URLs for all of the CAs that are part of the chain of a given certificate which is being verified.

"leaf" - The crl_urls field must contain at least the CRL URL of the CA which signed the certificate which is being validated.

"none" - The crl_urls field must be empty.

 

trust_store_type

enum

The type of the trust store.

Possible values: "built-in", "custom".

The built-in trust store comes with the operation system. This type of trust store is read-only. There is no CRL check involved, and it cannot be removed.

Elements of authorities

 

 Type

Description

 Notes
authorities

 

 array List of Certificate Authorities.  
 

fingerprint

     
 

issuer

 

 string The name of the entity that signed the certificate.  
 

pem

string The certificate in PEM format.  

 

subject

string

The subject of the certificate.

 

Elements of fingerprint

 

 Type

Description

 Notes
fingerprint

 

   A two-piece byte sequence consisting of a hash algorithm and a message digest.  
 

digest

string The string of digits produced by the hash algorithm.  
 

hash_algorithm

 

 string The name of the hash algorithm.  
Code Description Notes
400 SyntacticError

A value to be set is not accepted syntactically. The details section contains the path that was found to be invalid.

Possible syntactic error messages related to trust store:

  • The user is not allowed to create a built-in trust store or edit or delete the existing one.
  • When revocation_check is set to "none", the crl_urls field must be empty. The user cannot add any element to crl_urls.
  • When revocation_check is set to "full" or "leaf", the crl_urls cannot be empty.

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.

Possible semantic error messages related to trust store:

  • The name of the trust stores must be unique.
  • The authorities of a trust store must be unique.
  • The CRL URLs of a trust store must be unique.

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

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating