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

SSH host keys and certificates

SPS stores the host keys and X.509 certificates of the trusted servers. When a client tries to connect to a server, SPS verifies the host key or the certificate of the server, and allows connections only to the servers that have their keys available on SPS (unless the SSH Connection Policy is configured differently).

URL

GET https://<IP-address-of-SPS>/api/ssh-host-keys

Cookies

Sample request

The following command lists the SSH host keys and certificates of the servers that the users can connect to using SSH.

curl --cookie cookies https://<IP-address-of-SPS>/api/ssh-host-keys/

The following command retrieves the properties of a specific key.

curl --cookie cookies https://<IP-address-of-SPS>/api/ssh-host-keys/<object-id>

Response

The following is a sample response received when listing SSH host keys and certificates from the https:<IP-address-of-SPS>/api/ssh-host-keys/ endpoint.

For details of the meta object, see Message format.

The key of these objects is in the following format: <type-of-the-key>-<host-address>:<host-port>.

{
  "meta": {
    "href": "/api/ssh-host-keys",
    "parent": "/api"
  },
  "items": [
    {
      "key": "ssh-dss-10.110.0.1:22",
      "meta": {"href": "/api/ssh-host-keys/ssh-dss-10.110.0.1:22"}
    },
    {
      "key": "ssh-dss-10.110.0.2:2222",
      "meta": {"href": "/api/ssh-host-keys/ssh-dss-10.110.0.2:2222"}
    },
    {
      "key": "ssh-rsa-10.110.0.1:22",
      "meta": {"href": "/api/ssh-host-keys/ssh-rsa-10.110.0.1:22"}
    },
    {
      "key": "x509v3-sign-rsa-d00::2222:dead:2222",
      "meta": {"href": "/api/ssh-host-keys/x509v3-sign-rsa-d00::2222:dead:2222"}
    }
  ]
}

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

{
  "key": "ssh-rsa-10.10.100.1:22",
  "meta": {
    "href": "/api/ssh-host-keys/ssh-rsa-10.10.100.1:22",
    "parent": "/api/ssh-host-keys"
  },
  "ssh-rsa-10.10.100.1:22": {
    "address": "10.10.100.1",
    "port": 22,
    "type": {
      "selection": "ssh-rsa",
      "value": "AAAAB3NzaC1yc2EAAAABIwAAAQEAxrtNxBZieXhBI2gJoAdsjKNq...=="
    }
  }
}

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.

Search and filter host keys

To list only specific host keys, you can use the following filters.

• List every host key and certificate:

  GET https://<IP-address-of-SPS>/api/ssh-host-keys

• List host keys of a specific type:

  GET https://<IP-address-of-SPS>/api/ssh-host-keys?type=<type-to-list>

  Possible values: ssh-rsa, ssh-dss, x509v3-sign-rsa, x509v3-sign-dss. For example:

  GET https://<IP-address-of-SPS>/api/ssh-host-keys?type=ssh-rsa

• List host keys for a specific port number:

  GET https://<IP-address-of-SPS>/api/ssh-host-keys?port=<port-number-to-list>

• List host keys for a specific host address (IPv4 or IPv6):

  GET https://<IP-address-of-SPS>/api/ssh-host-keys?address=<host-address>

• For a complex filter, separate the parameters with an ampersand (&) character, for example:

  GET https://<IP-address-of-SPS>/api/ssh-host-keys?port=<port-number-to-list>&type=<type-to-list>

The response to such requests is a JSON object, where the items list includes the IDs of the selected host keys (or an empty list). For example, filtering for ssh-dss keys could return a similar list:

{
  "meta": {
    "href": "/api/ssh-host-keys",
    "parent": "/api"
  },
  "items": [
    {
      "key": "ssh-dss-10.110.0.1:22",
      "meta": {"href": "/api/ssh-host-keys/ssh-dss-10.110.0.1:22"}
    },
    {
      "key": "ssh-dss-10.110.0.2:2222",
      "meta": {"href": "/api/ssh-host-keys/ssh-dss-10.110.0.2:2222"}
    }
  ]
}

Add new host key

To upload a new host key or certificate, you have to POST the host key and other data as a JSON object to the https://<IP-address-of-SPS>/api/ssh-host-keys endpoint. For details, see Create a new object. The body of the POST request must contain a JSON object with the parameters listed in Element . If the POST request is successful, the response includes an ID for the host key in the following format: <type-of-the-key>-<host-address>:<host-port>. For example:

{
  "address": "10.110.0.1",
  "port": 22,
  "type": {
    "selection": "ssh-rsa",
    "value": "AAAAB3NzaC1yc2EAAAAD...zvMwgc=="
  }
}

Note that for IPv6 addresses, SPS will automatically convert the address to its canonical format.

Delete host key

To delete a host key or certificate, you have to DELETE https://<IP-address-of-SPS>/api/ssh-host-keys/<ID-of-the-host-key> endpoint. For details, see Delete an object. If the DELETE request is successful, the response includes only the meta object, for example:

{
    "meta": {
        "href": "/api/ssh-host-keys/ssh-rsa-10.10.20.35:22",
        "parent": "/api/ssh-host-keys"
    }
}

You must commit your changes to actually delete the object from SPS.

Telnet connections

Topics:

Telnet connections

List of endpoints for configuring the policies, options and connection rules of Telnet connections.

URL

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

Cookies

Sample request

The following command lists the available settings for configuring for Telnet connections.

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

Response

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

For details of the meta object, see Message format.

{
  "items": [
    {
      "key": "channel_policies",
      "meta": {
        "href": "/api/configuration/telnet/channel_policies"
      }
    },
    {
      "key": "options",
      "meta": {
        "href": "/api/configuration/telnet/options"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/telnet",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/troubleshooting",
    "parent": "/api/configuration",
    "previous": "/api/configuration/ssh",
    "transaction": "/api/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.

Telnet connection policies

Connection policies determine if a server can be accessed from a particular client. Connection policies reference other resources (policies, usergroups, keys) that must be configured and available before creating a connection policy.

URL

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

Cookies

Sample request

The following command lists Telnet connection policies.

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

The following command retrieves the properties of a specific policy.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/telnet/connections/<connection-key>