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

Local services: enabling SSH access to the SPS host

Exclusively for troubleshooting purposes, you can access the SPS host using SSH. Completing the Welcome Wizard automatically disables SSH access to SPS. Re-enabling it allows you to connect remotely to the SPS host and login using the root user. The password of the root user is the one you provided in the Welcome Wizard.

The following encryption algorithms are configured on the local SSH service of SPS:

• Key exchange (KEX) algorithms:

  diffie-hellman-group-exchange-sha256

• Ciphers:

  aes256-ctr,aes128-ctr

• Message authentication codes:

  hmac-sha2-512,hmac-sha2-256

URL

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

Cookies

Sample request

The following command lists the configuration options.

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

Response

The following is a sample response received when listing the configuration options.

For details of the meta object, see Message format.

{
    "body": {
        "access_restriction": {
            "allowed_from": [
                "10.40.0.48/24"
            ],
            "enabled": true
        },
        "allow_password_auth": true,
        "bruteforce_protection": true,
        "enabled": true,
        "listen": [
            {
                "address": {
                    "key": "nic1.interfaces.ff7574025754b3df1647001.addresses.1",
                    "meta": {
                        "href": "/api/configuration/network/nics/nic1#interfaces/ff7574025754b3df1647001/addresses/1"
                    }
                },
                "port": 23
            }
        ],
        "public_keys": [
            {
                "comment": "key-comment anothercomment",
                "selection": "rsa",
                "value": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDTnisLCjZ3vONMXqFBIdvpZ0BY73+GdHpgoaL8YsydxJBsYg9dYTDzVVtYFVvdCVzBdcwCjyOuPwtZoYU3pLEFQ7OVoDUDPmVnl6idS/6tB2m89I5zdc02xUeCWTBpTGoOhNtc+YDmxPGZ1FQIpXCw0MT91jviWm3JydDd5YKINwvdTh8zsRT/702ZD9uZslwkQA/b2B9/hidCAkQkvs5H1B3o4laTd0JE9k90N+qbaQjVvoInr+jdXaWvrScwFVxZhb7Q1LvUL6oxW889bOWFMSa+/mnENarw6rpwfk9Ayi5uQQ2imY/tSnfgbS2RvIa1sKwUsJasDqN2lo/DuhON"
            }
        ]
    },
    "key": "ssh",
    "meta": {
        "first": "/api/configuration/local_services/admin_web",
        "href": "/api/configuration/local_services/ssh",
        "last": "/api/configuration/local_services/user_web",
        "next": "/api/configuration/local_services/user_web",
        "parent": "/api/configuration/local_services",
        "previous": "/api/configuration/local_services/snmp_agent",
        "transaction": "/api/transaction"
    }

{
    "body": {
        "interfaces": {
            "@order": [
                "ff7574025754b3df1647001"
            ],
            "ff7574025754b3df1647001": {
                "addresses": {
                    "1": "10.40.255.171/24",
                    "@order": [
                        "1"
                    ]
                },
                "name": "default",
                "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,
        "transaction": "/api/transaction"
    }
    }

nic1.interfaces.ff7574025754b3df1647001.addresses.1

"address": "nic1.interfaces.ff7574025754b3df1647001.addresses.1"

"address": {
    "key": "nic1.interfaces.ff7574025754b3df1647001.addresses.1",
    "meta": {
        "href": "/api/configuration/network/nics/nic1#interfaces/ff7574025754b3df1647001/addresses/1"
    }
    },

"public_keys": [
        {
            "comment": "user@example.com anothercomment",
            "key": {
                "selection": "rsa",
                "value": "AADDB3NzaC1yc2EABBADAQA......./DuhON"
            }
        },
        {
            "comment": "username@example.com",
            "key": {
                "selection": "rsa",
                "value": "ASFDFAB3NzaC1yc2EAAAABIwAAASdfASF/EuQh9zc2umxX...dU="
            }
        }
    ]

"key": {
    "selection": "rsa",
    "value": "ASFDFAB3NzaC1yc2EAAAABIwAAASdfASF/EuQh9zc2umxX...dU="
}

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.

RPC API

The SPS RPC API allows you to access, query, and manage SPS from remote applications. You can access the API using the Simple Object Access Protocol (SOAP) protocol over HTTPS, meaning that you can use any programming language that has access to a SOAP client to integrate SPS to your environment.

URL

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

Cookies

Sample request

The following command lists the RPC API settings.

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

Response

The following is a sample response received when listing the RPC API settings.

For details of the meta object, see Message format.

{
  "body": {
    "enabled": true
  },
  "key": "soap",
  "meta": {
    "first": "/api/configuration/management/certificates",
    "href": "/api/configuration/management/soap",
    "last": "/api/configuration/management/webinterface",
    "next": "/api/configuration/management/syslog",
    "parent": "/api/configuration/management",
    "previous": "/api/configuration/management/snmp",
    "transaction": "/api/transaction"
  }
}

Modify RPC API settings

To modify the RPC API settings, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Modify the JSON object of the endpoint.

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

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

Manage the SPS license

You can display information about the currently used SPS license from the https://<IP-address-of-SPS>/api/configuration/management/license endpoint.

The following encryption algorithms are configured on the local SSH service of SPS:

• Key exchange (KEX) algorithms:

  diffie-hellman-group-exchange-sha256

• Ciphers:

  aes256-ctr,aes128-ctr

• Message authentication codes:

  hmac-sha2-512,hmac-sha2-256

URL

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

Cookies

Sample request

The following command lists the configuration options.

curl --cookie cookies -H "Content-Type: application/json" https://10.30.255.28/api/configuration/management/license

Response

The following is a sample response received.

For details of the meta object, see Message format.

{
    "body": {
        "customer": "Example",
        "limit": 5000,
        "limit_type": "host",
        "serial": "b937d212-db7d-0f2f-4c87-295e3c57024a",
        "valid_not_after": "2018-11-07",
        "valid_not_before": "2017-11-06"
    },
    "key": "license",
    "meta": {
        "first": "/api/configuration/management/certificates",
        "href": "/api/configuration/management/license",
        "last": "/api/configuration/management/webinterface",
        "next": "/api/configuration/management/root_password",
        "parent": "/api/configuration/management",
        "previous": "/api/configuration/management/health_monitoring",
        "remaining_seconds": 600,
        "transaction": "/api/transaction",
        "upload": "/api/upload/license"
    }
}

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.

Upload a new license

To upload a new license file, complete the following steps.

1. Download your license file from support portal.

2. Open a transaction.

   For details, see Open a transaction.

3. Upload the license file.

   Upload the file to the https://<IP-address-of-SPS>/api/upload/license endpoint. For example:

   curl --cookie cookies -F 'data=@/path/license.txt' -H "Expect:" --insecure https://<IP-address-of-SPS>/api/upload/license

4. Restart the traffic on SPS.

   SPS will not use the new license to ongoing sessions. For the new license to take full effect, you must restart all traffic on the Basic Settings > System > Traffic control page of the SPS web interface.

   curl --cookie cookies -F 'data=@/path/license.txt' -H "Expect:" --insecure https://<IP-address-of-SPS>/api/upload/license

5. Commit your changes.

   For details, see Commit a transaction.

Change contact information

The About page on the SPS web interface and the /api/info endpoint contains various contact information. You can change this to a custom email address or URL.

URL

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

Cookies

Sample request

The following command lists the RPC API settings.

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

Response

The following is a sample response received when querying the endpoint.

For details of the meta object, see Message format.

{
    "body": {
        "uri": null
    },
    "key": "support_info",
    "meta": {
        "first": "/api/configuration/management/certificates",
        "href": "/api/configuration/management/support_info",
        "last": "/api/configuration/management/webinterface",
        "next": "/api/configuration/management/syslog",
        "parent": "/api/configuration/management",
        "previous": "/api/configuration/management/splunk_forwarder",
        "remaining_seconds": 600,
        "transaction": "/api/transaction"
    }

Change the support link

To change the support link, complete the following steps.

1. Open a transaction.

   For details, see Open a transaction.

2. PUT a JSON object containing the new support link.

   PUT a JSON object containing the new support link to the https://<IP-address-of-SPS>/api/configuration/management/support_info endpoint. For example:

   curl -X PUT -d '{"uri": { "selection": "mailto", "value": "mailto:support@example.com" } }' -H "Content-Type: application/json" --cookie cookies "https://<IP-address-of-SPS>/api/configuration/management/support_info"

   To use an HTTP or HTTPS link as contact info, use the following JSON object:

   {
     "uri": {
       "selection": "url",
       "value": "http://example.com"
      }
   }

   To use a email address as contact info, use the following JSON object:

   {
     "uri": {
       "selection": "mailto",
       "value": "mailto:support@example.com"
      }
   }

3. Commit your changes.

   For details, see Commit a transaction.