One Identity Safeguard for Privileged Sessions 8.0 LTS

SPS can check the validity of certificates using the certificates and certificate-revocation lists of trusted certificate authorities (CAs) that issued the certificates.

URL

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

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 trusted CAs:

Querying trusted CA lists request

The following command retrieves the properties of a specific CA:

Querying a trusted CA list request

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

Response

The following is a sample response received when listing trusted CAs:

Querying trusted CA lists response

When retrieving the endpoint of a specific CA, the response is the following:

Querying a trusted CA list response

Element			Type	Description
key			string	Top level element, contains the ID of the CA.
body			Top level element (string)	Contains the properties of the CA.
	authorities		Top level list	Contains the certificates and the Certificate Revocation Lists (CLR) of the trusted CAs. You can add multiple certificate and CRL pairs.
		certificate.pem	string	The certificate of the trusted CA.
		crl	string	The URL of the Certificate Revocation List of the CA.
	dn_check		Top level item	Certificates are only accepted if their content matches the configured values.
		altEmailAddress	string	The certificate is only accepted if its alternative e-mail address matches the value of the altEmailAddress element.
		c	string	The certificate is only accepted if its country matches the value of the c element.
		cn	string	The certificate is only accepted if its common name matches the value of the cn element.
		emailAddress	string	The certificate is only accepted if its e-mail address matches the value of the emailAddress element.
		l	string	The certificate is only accepted if its locality matches the value of the l element.
		o	string	The certificate is only accepted if its organization name matches value of the o element.
		ou	string	The certificate is only accepted if its organization unit name matches value of the ou element.
		st	string	The certificate is only accepted if its state or province matches value of the st element.
	dns_lookup		boolean	Set to true to use the domain name server set on the /api/configuration/network/naming endpoint to resolve the hostnames and IP addresses for certificate validation. If you have enabled strict_hostcheck, you probably want to enable this option as well.
	name		string	The name of the trusted CA. This name is also displayed on the SPS web interface. It cannot contain whitespace.
	strict_hostcheck		boolean	Set to true to configure only accepting certificates where the Common Name of the certificate contains the hostname or the IP address of the host showing the certificate.

Uploading CA certificates

SPS uses only the key part of the CA certificate.

To use a certificate with the SPS API, remove all data, 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"

Add a trusted CA

To add a trusted CA, you have to:

Open a transaction.

For more information, see Open a transaction.
Create the JSON object for the new trusted CA.

POST the JSON object to the https://<IP-address-of-SPS>/api/configuration/policies/trusted_ca_lists 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 trusted CA. For example:
```
{
  "key": "becc17b1-e876-4443-b22e-a3baf7825e55",
  "meta": {
    "href": "/api/configuration/policies/trusted_ca_lists/becc17b1-e876-4443-b22e-a3baf7825e55",
    "parent": "/api/configuration/policies/trusted_ca_lists",
    "transaction": "/api/transaction"
  }
}
```
Commit your changes.

For more information, see Commit a transaction.

Modify a trusted CA

To modify a trusted CA, you have to:

Open a transaction.

For more information, see Open a transaction.
Modify the JSON object of the trusted CA.

PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/policies/trusted_ca_lists/<key-of-the-object> 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.
400	InvalidQuery	The requested filter or its value is invalid.
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.

Local user databases

Local User Databases are available for RDP, SSH and Telnet protocols, and can be used to authenticate the clients to credentials that are locally available on SPS. Such credentials include passwords and public keys. Local User Databases are most commonly used in inband gateway authentication scenarios.

URL

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

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 local user databases.

curl --cookie cookies.txt https://<IP-address-of-SPS>/api/configuration/policies/user_databases

The following command retrieves the properties of a specific local user database.

curl --cookie cookies.txt https://<IP-address-of-SPS>/api/configuration/policies/user_databases/<object-id>

Response

The following is a sample response received when listing local user databases.

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

{
  "items": [
    {
      "key": "8235074425707e306abf39",
      "meta": {
        "href": "/api/configuration/policies/user_databases/8235074425707e306abf39"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/user_databases",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/userlists",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/trusted_ca_lists",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific local user database, the response is the following.

{
  "body": {
    "name": "<name-of-the-user-database>",
    "users": [
      {
        "passwords": [
          {
            "key": "ad55822d-fa28-45aa-bca4-220074f770e1",
            "meta": {
              "href": "/api/configuration/passwords/ad55822d-fa28-45aa-bca4-220074f770e1"
            }
          }
        ],
        "public_keys": [
          {
            "selection": "rsa",
            "value": "<public-key>"
          }
        ],
        "username": "<username>"
      }
    ]
  },
  "key": "8235074425707e306abf39",
  "meta": {
    "first": "/api/configuration/policies/user_databases/8235074425707e306abf39",
    "href": "/api/configuration/policies/user_databases/8235074425707e306abf39",
    "last": "/api/configuration/policies/user_databases/8235074425707e306abf39",
    "next": null,
    "parent": "/api/configuration/policies/user_databases",
    "previous": null,
    "transaction": "/api/transaction"
  }
}

Element			Type	Description
key			string	Top level element, contains the ID of the local user database.
body			Top level element (string)	Contains the properties of the local user database.
	name		string	The name of the local user database. This name is also displayed on the SPS web interface. It cannot contain whitespace.
	users		Top level list	Contains the credentials (password, key) of each configured user.
		passwords	Top level item	References the password of the user. You can configure passwords at the /api/configuration/passwords/ endpoint. To modify or add a password, use the value of the returned key as the value of the password element, and remove any child elements (including the key).
		public_keys	Top level list	Contains the pubic keys of the user.
		username	Top level list, string	Name of the user.

Elements of public_keys	Type	Description
selection	string	Possible values are: rsa The value element contains an RSA key. dss The value element contains a DSS key.
value	string	The public key.

Elements of public_keys

Type

Description

selection

string

Possible values are:

rsa

The value element contains an RSA key.
dss

The value element contains a DSS key.

value

string

The public key.

Examples:

Configure password authentication only for test_user. (New passwords can only be provided using the web interface of SPS.)

{
  "name": "<name-of-the-user-database>",
  "users": [
    {
      "certificates": [],
      "passwords": [
        "ad55822d-fa28-45aa-bca4-220074f770e1"
      ],
      "public_keys": [],
      "username": "test_user"
    }
  ]
}

Configure two possible X.509 certificates for test_user, and no other authentication options.

{
  "name": "<name-of-the-user-database>",
  "users": [
    {
      "certificates": [
        "<cert1>",
        "<cert2>"
      ],
      "passwords": [],
      "public_keys": [],
      "username": "test_user"
    }
  ]
}

Add a local user database

To add a local user database, you have to:

Open a transaction.

For more information, see Open a transaction.
Create the JSON object for the new local user database.

POST the JSON object to the https://<IP-address-of-SPS>/api/configuration/policies/user_databases 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 local user database. For example:
```
{
  "key": "c4e60325-971a-44bc-ac01-e353dc6320d6",
  "meta": {
    "href": "/api/configuration/policies/user_databases/c4e60325-971a-44bc-ac01-e353dc6320d6",
    "parent": "/api/configuration/policies/user_databases",
    "transaction": "/api/transaction"
  }
}
```
Commit your changes.

For more information, see Commit a transaction.

Modify a local user database

To modify a local usre database, you have to:

Open a transaction.

For more information, see Open a transaction.
Modify the JSON object of the local user database.

PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/policies/user_databases/<key-of-the-object> 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.
400	InvalidQuery	The requested filter or its value is invalid.
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.

User lists

User lists are local white- or blacklists of usernames that allow fine-control over who can access a connection or a channel.

NOTE: User lists on SPS cannot prevent a user from accessing the server from a local terminal.

You can use user lists when configuring gateway_groups or remote_groups in the allowed_for element of channel policies. For more information on configuring channel policies, see Channel policy.

To use this option, you must also configure web gateway authentication in the connection policy, or client-side gateway authentication back-end in the authentication policy.

URL

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

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 user lists created on SPS.

curl --cookie cookies.txt https://<IP-address-of-SPS>/api/configuration/policies/userlists

The following command retrieves the properties of a specific list.

curl --cookie cookies.txt https://<IP-address-of-SPS>/api/configuration/policies/userlists/<key-id>

Response

The following is a sample response received when retrieveing the user lists.

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

The keys with negative ID values are the default user lists of SPS.

{
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/userlists",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/usermapping_policies",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/user_databases",
    "transaction": "/api/transaction"
  },
  "items": [
    {
      "key": "-1",
      "meta": {
        "href": "/api/configuration/policies/userlists/-1"
      }
    },
    {
      "key": "-2",
      "meta": {
        "href": "/api/configuration/policies/userlists/-2"
      }
    },
    {
      "key": "-3",
      "meta": {
        "href": "/api/configuration/policies/userlists/-3"
      }
    },
    {
      "key": "-4",
      "meta": {
        "href": "/api/configuration/policies/userlists/-4"
      }
    },
    {
      "key": "20088200245706af301b1ba",
      "meta": {
        "href": "/api/configuration/policies/userlists/20088200245706af301b1ba"
      }
    }
  ]
}

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

{
  "body": {
        "allow": "no_user",
        "except": [
            "root"
        ],
        "name": "root_only"
    },
    "key": "-4",
    "meta": {
        "href": "/api/configuration/policies/userlists/-4"
    }
},
  "key": "-4",
  "meta": {
    "first": "/api/configuration/policies/userlists/-1",
    "href": "/api/configuration/policies/userlists/-4",
    "last": "/api/configuration/policies/userlists/20088200245706af301b1ba",
    "next": "/api/configuration/policies/userlists/20088200245706af301b1ba",
    "parent": "/api/configuration/policies/userlists",
    "previous": "/api/configuration/policies/userlists/-3",
    "transaction": "/api/transaction"
  }
}

Element		Type	Description
key		string	Top level element, contains the ID of the user list
body		Top level element (string)	The elements of the user policy.
	allow	string	The default policy of the user list. Possible values are: all_users creates a blacklist, where every user is permitted, except the ones listed in the except field. no_user creates a whitelist, where only the users listed in the except field are allowed access.
	name	string	The name of the user list.
	except	list	The usernames added to the list.

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.
400	InvalidQuery	The requested filter or its value is invalid.
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.

Examples

The following defines a blacklist called no_root that permits every username except root.

{
    "allow": "all_users",
    "except": [
        "root"
    ],
    "name": "no_root"
}

The following defines a whitelist called my_list that permits only the permitted_user1 and permitted_user2 usernames.

{
    "allow": "no_user",
    "except": [
        "permitted_user1",
        "permitted_user2"
    ],
    "name": "no_root"
}

Add a user list

To add a user list, you have to:

Open a transaction.

For more information, see Open a transaction.
Create the JSON object for the new user list.

POST the JSON object to the https://<IP-address-of-SPS>/api/configuration/policies/userlists 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 user list. For example:
```
{
  "key": "321314dc-eca0-4e97-b445-0612fedc0165",
  "meta": {
    "href": "/api/configuration/policies/userlists/321314dc-eca0-4e97-b445-0612fedc0165",
    "parent": "/api/configuration/policies/userlists",
    "transaction": "/api/transaction"
  }
}
```
Commit your changes.

For more information, see Commit a transaction.

Modify a user list

To modify a user list, you have to:

Open a transaction.

For more information, see Open a transaction.
Modify the JSON object of the user list.

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

For more information, see Commit a transaction.

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

Trusted Certificate Authorities

URL

Cookies

Sample request

Response

Uploading CA certificates

Add a trusted CA

Open a transaction.

Create the JSON object for the new trusted CA.

Commit your changes.

Modify a trusted CA

Open a transaction.

Modify the JSON object of the trusted CA.

Commit your changes.

Status and error codes

Local user databases

URL

Cookies

Sample request

Response

Examples:

Add a local user database

Open a transaction.

Create the JSON object for the new local user database.

Commit your changes.

Modify a local user database

Open a transaction.

Modify the JSON object of the local user database.

Commit your changes.

Status and error codes

User lists

URL

Cookies

Sample request

Response

Status and error codes

Examples

Add a user list

Open a transaction.

Create the JSON object for the new user list.

Commit your changes.

Modify a user list

Open a transaction.

Modify the JSON object of the user list.

Commit your changes.

HTTP connections

Detailed information about this topic