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

Global SSH options

List of options that affect all SSH connections.

URL

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

Cookies

Sample request

The following command lists global SSH options.

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

Response

The following is a sample response received when listing global SSH options.

For details of the meta object, see Message format.

{
  "body": {
    "audit": {
      "cleanup": {
        "channel_database_cleanup_days": 600,
        "enabled": true
      },
      "timestamping": {
        "selection": "local",
        "signing_interval": 30
      }
    },
    "gssapi": {
      "enabled": false
    },
    "service": {
      "enabled": true,
      "log_level": 4
    }
  },
  "key": "options",
  "meta": {
    "first": "/api/configuration/ssh/authentication_policies",
    "href": "/api/configuration/ssh/options",
    "last": "/api/configuration/ssh/settings_policies",
    "next": "/api/configuration/ssh/settings_policies",
    "parent": "/api/configuration/ssh",
    "previous": "/api/configuration/ssh/connections",
    "transaction": "/api/transaction"
  }
}

Examples:

Set SPS as the timestamping server:

{
  "audit": {
    "cleanup": {
      "enabled": false
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "gssapi": {
    "enabled": false
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Enable cleanup, and set it to occur every 10 days:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "gssapi": {
    "enabled": false
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, without specifying a timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": false
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "gssapi": {
    "enabled": false
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, and specify the 1.2.3 timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": true,
          "policy_oid": "1.2.3"
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "gssapi": {
    "enabled": false
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

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.

Modify global SSH settings

To modify global SSH settings, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Modify the JSON object of the global SSH settings endpoint.

   PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/ssh/options endpoint. You can find a detailed description of the available parameters listed in Element . The elements of the audit item are described in Elements of audit.

3. Commit your changes.

   For details, see Commit a transaction.

SSH settings policies

SSH settings policies define protocol-level settings (algorithms, greetings and banners, timeout). You can create multiple policies, and choose the appropriate one for each SSH connection.

URL

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

Cookies

Sample request

The following command lists SSH settings policies.

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

The following command retrieves the properties of a specific policy.

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

Response

The following is a sample response received when listing SSH settings policies.

For details of the meta object, see Message format.

{
  "items": [
    {
      "key": "-300",
      "meta": {
        "href": "/api/configuration/ssh/settings_policies/-300"
      }
    },
    {
      "key": "236283841571912b948b88",
      "meta": {
        "href": "/api/configuration/ssh/settings_policies/236283841571912b948b88"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/ssh/authentication_policies",
    "href": "/api/configuration/ssh/settings_policies",
    "last": "/api/configuration/ssh/settings_policies",
    "next": null,
    "parent": "/api/configuration/ssh",
    "previous": "/api/configuration/ssh/options",
    "transaction": "/api/transaction"
  }
}

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

{
  "body": {
    "client_side_algorithms": {
      "cipher": [
        "aes128-ctr",
        "aes192-ctr",
        "aes256-ctr"
      ],
      "compression": [
        "none"
      ],
      "kex": [
        "diffie-hellman-group14-sha1"
      ],
      "mac": [
        "hmac-sha2-256",
        "hmac-sha2-512"
      ]
    },
    "greeting": "Welcome!",
    "name": "API_SSH_Setting",
    "preconnect_channel_check": true,
    "server_side_algorithms": {
      "cipher": [
        "aes128-ctr",
        "aes192-ctr",
        "aes256-ctr"
      ],
      "compression": [
        "none"
      ],
      "kex": [
        "diffie-hellman-group14-sha1"
      ],
      "mac": [
        "hmac-sha2-256",
        "hmac-sha2-512"
      ]
    },
    "software_version": "SSH",
    "strict_mode": true,
    "timeout": 600,
    "userauth_banner": "This is a monitored connection."
  },
  "key": "236283841571912b948b88",
  "meta": {
    "first": "/api/configuration/ssh/settings_policies/-300",
    "href": "/api/configuration/ssh/settings_policies/236283841571912b948b88",
    "last": "/api/configuration/ssh/settings_policies/236283841571912b948b88",
    "next": null,
    "parent": "/api/configuration/ssh/settings_policies",
    "previous": "/api/configuration/ssh/settings_policies/-300",
    "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.

Add SSH settings policies

To add a settings policy, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Create the JSON object for the new policy.

   POST the JSON object to the https://<IP-address-of-SPS>/api/configuration/ssh/settings_policies/ 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 policy. For example:

   {
     "key": "59790911-415c-4ed3-a0d2-1164637472ca",
     "meta": {
       "href": "/api/configuration/ssh/settings_policies/59790911-415c-4ed3-a0d2-1164637472ca",
       "parent": "/api/configuration/ssh/settings_policies",
       "transaction": "/api/transaction"
     }
   }

3. Commit your changes.

   For details, see Commit a transaction.

Modify SSH settings policies

To modify a settings policy, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Modify the JSON object of the policy.

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

3. Commit your changes.

   For details, see Commit a transaction.

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: