Chat now with support
Chat mit Support

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

Introduction Using the SPS REST API Basic settings User management and access control Managing SPS General connection settings HTTP connections Citrix ICA connections MSSQL connections RDP connections SSH connections Telnet connections VNC connections Search, retrieve, download, and index sessions Reporting Health and maintenance Advanced authentication and authorization Completing the Welcome Wizard using REST Enable and configure analytics using REST REST API examples

Signing CA policies

SPS can generate the server-side certificates on the fly. This technique is used for example in SSL-encrypted RDP sessions, RDP sessions that use Network Level Authentication (CredSSP), or SSH connections that use X.509-based authentication.

URL
GET https://<IP-address-of-SPS>/api/configuration/policies/signing_cas
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 configured signing Certificate Authorities (CAs).

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

The following command retrieves the properties of a specific policy.

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

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

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

{
  "items": [
    {
      "key": "991699365727ac4eb4606",
      "meta": {
        "href": "/api/configuration/policies/signing_cas/991699365727ac4eb4606"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/signing_cas",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/ticketing_policies",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/ldap_servers",
    "transaction": "/api/transaction"
  }
}

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

{
  "body": {
    "ca": {
      "key": "55b2419c-f94f-4836-9c0b-bc3796b6f556",
      "meta": {
        "href": "/api/configuration/x509/55b2419c-f94f-4836-9c0b-bc3796b6f556"
      }
    },
    "name": "API_CA"
  },
  "key": "991699365727ac4eb4606",
  "meta": {
    "first": "/api/configuration/policies/signing_cas/991699365727ac4eb4606",
    "href": "/api/configuration/policies/signing_cas/991699365727ac4eb4606",
    "last": "/api/configuration/policies/signing_cas/991699365727ac4eb4606",
    "next": null,
    "parent": "/api/configuration/policies/signing_cas",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key string Top level element, contains the ID of the signing CA.
body Top level element (string) Contains the properties of the signing CA.
ca string

References the identifier of the signing CA's X.509 certificate. You can configure certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

name string The name of the signing CA. This name is also displayed on the SPS web interface. It cannot contain whitespace.
Add a signing CA

To add a signing CA, you have to:

  1. Open a transaction

    For more information, see Open a transaction.

  2. Create a signing CA

    Have the value of the key element of a valid X.509 CA certificate stored on SPS.

  3. Create the JSON object for the new signing CA.

    Use the X.509 certificate's key as the value of the ca element for the signing CA. You can find a detailed description of the available parameters listed in Element .

    POST the JSON object to the https://<IP-address-of-SPS>/api/configuration/policies/signing_cas endpoint. If the POST request is successful, the response includes the key of the new signing CA. For example:

    {
      "key": "325768b5-5b85-467d-8e30-e2b57d0869c8",
      "meta": {
        "href": "/api/configuration/policies/signing_cas/325768b5-5b85-467d-8e30-e2b57d0869c8",
        "parent": "/api/configuration/policies/signing_cas",
        "transaction": "/api/transaction"
      }
    }
  4. Commit your changes

    For more information, see Commit a transaction.

Modify a signing CA

To modify a signing CA, you have to:

  1. Open a transaction

    For more information, see Open a transaction.

  2. Modify the JSON object of the signing CA.

    Use the X.509 certificate's key as the value of the ca element for the signing CA. You can find a detailed description of the available parameters listed in Element .

    PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/policies/signing_cas/<key-of-the-object> endpoint.

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

HTTP response code Status/Error Description
201 Created The new resource was successfully created.
400 InvalidQuery The requested filter or its value is invalid.
400

Bad Request

The referenced certificate is not a valid CA certificate.

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.

Time policy

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.txt 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.txt -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:

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:

-----BEGIN CERTIFICATE-----
MIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC
Q0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT
B0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi
aXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2
MDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP
bnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD
VQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN
AQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS
59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw
0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc
3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs
X5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX
hJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA
R5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP
AB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy
0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB
uNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc
N5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt
qYyyD1ld89OUEYZ+aJQd/A==
-----END CERTIFICATE-----

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:

  1. Open a transaction

    For more information, see Open a transaction.

  2. 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"
      }
    }
  3. Commit your changes

    For more information, see Commit a transaction.

Modify a trusted CA

To modify a trusted CA, you have to:

  1. Open a transaction

    For more information, see Open a transaction.

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

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

  1. Open a transaction

    For more information, see Open a transaction.

  2. 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"
      }
    }
  3. Commit your changes

    For more information, see Commit a transaction.

Modify a local user database

To modify a local usre database, you have to:

  1. Open a transaction

    For more information, see Open a transaction.

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

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

The document was helpful.

Bewertung auswählen

I easily found the information I needed.

Bewertung auswählen