One Identity Safeguard for Privileged Sessions 7.2.1

The time policy determines the timeframe when the users are permitted to access a particular channel. To list the available Time policies, use the following command.

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

The following sections detail the properties of Time policy objects.

URL

GET https:<IP-address-of-SPS>/api/configuration/policies/time_policies/<object-id>

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 properties of a specific Time policy object.

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

Response

The following is a sample response received, showing the properties of Content policy objects.

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

{
  "body": {
    "Fri": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "Mon": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "Sat": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "Sun": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "Thu": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "Tue": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "Wed": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "name": "7x24"
}

Element	Type	Description
name	string	Top level element, the name of the object. This name is also displayed on the SPS web interface. It cannot contain whitespace.
Fri	list	A list of intervals for the day when the users are allowed to access the connection. Use the hh:mm format. If the users are not allowed to access the connection for this day, use an empty list. For example: "Sat": [], To allow access for the whole day, use 0:00 for the starting time, and 23:59for the end. For example: "Wed": [ [ "0:00", "23:59" ] You can list multiple intervals for a day, for example: "Wed": [ [ "8:00", "18:00" ], [ "19:00", "22:00" ]
Sat	list
Sun	list
Tue	list
Wed	list
Thu	list

Trusted Certificate Authorities

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.

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

The following command retrieves the properties of a specific CA.

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

Response

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

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

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

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

{
  "body": {
    "authorities": [
      {
        "certificate": "<cert>",
        "crl": "<url-of-revocation-list>"
      }
    ],
    "dn_check": {
      "altEmailAddress": "<altEmail>",
      "c": "<country>",
      "cn": "<commonName>",
      "emailAddress": "<email>",
      "l": "<localityName>",
      "o": "<orgName>",
      "ou": "<orgUnitName>",
      "st": "<stateOrProvince>"
    },
    "dns_lookup": false,
    "name": "<ca-name>",
    "strict_hostcheck": true
  },
  "key": "12269547065727ad6e79d9e",
  "meta": {
    "first": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e",
    "href": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e",
    "last": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e",
    "next": null,
    "parent": "/api/configuration/policies/trusted_ca_lists",
    "previous": null,
    "transaction": "/api/transaction"
  }
}

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	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 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 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 https://<IP-address-of-SPS>/api/configuration/policies/userlists

The following command retrieves the properties of a specific list.

curl --cookie cookies 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.

製品を選択してください:

サービス向上のために、「Purpose of your Chat（チャットの目的）」を記入してください。

お客様の不具合に推奨されるソリューション

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

Time policy

URL

Cookies

Sample request

Response

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