Chat now with support
Chat with Support

One Identity Safeguard for Privileged Sessions 8.0 LTS - 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

Managing API keys as a user

The /api/user/api_keys endpoint enables an authenticated user to manage (create, list or remove) their own API keys.

URL
https://<IP-address-of-SPS>/api/user/api_keys
HTTP operations

HTTP operations on the /api/user/api_keys endpoint include:

HTTP method

Description

Notes

GET

 List API keys of the current user

The API key value is not displayed.

POST

Create an API key for the current user

The generated API key is displayed. The key becomes effective after the user commits the transaction (Commit a transaction).

DELETE

Remove an API key of the current user

The key is removed after the user commits the transaction (Commit a transaction).

Sample request for creating an API key
{ 
 
                "name": "my_api_key" 
 
            } 

Elements of the message body include:

Element

Type

 Description
name

string

Name of the API key. The name cannot contain white-spaces or extra characters.

Sample Response

The following is a sample response received when creating the API key was successful.

{ 
 
                "body": { 
 
                "login_method": "f46acbd3-69c4-4562-8ed6-3212cc8750a8", 
 
                "name": "my_api_key", 
 
                "token": "sriUN7XteezWI7rJshnppe3tc7RPIBNhI4HYpvYQlR6DpEMr8ksO5ZHi3b83qcU5", 
 
                "username": "exampleuser" 
 
                }, 
 
                "key": "2dde93c0-4292-445d-9fb3-e13b9e22c460" 
 
            } 
Element

Type

 Description
login_method

string

The identifier of the login method of the current user.

name

string

A descriptive name for an API key.

token

string

The cleartext value of the generated token. Note that the value can never be retrieved later.

username

string

The identifier of the current user.

key

string

The identifier of the API key.

After creating a new API key, commit your changes (Commit a transaction.

Authenticate to the SPS REST API using X.509 certificate

Prerequisites

  • The REST server must permit certificate authentication to the SPS web interface. If only password-based authentication is permitted, see Authenticate to the SPS REST API.

    To check the permitted authentication method, query the /api/authentication/login_methods endpoint.

    For more information, see Listing SPS login methods.

  • You can access the REST server on the same IP address and port that you use to access the SPS web interface. Note that management (administrator) access must be enabled on the interface. For details on configuring management access, see Configuring user and administrator login addresses in the Administration Guide.

  • For the user to have full access over the SPS REST API, they must have the REST server privilege. The user privileges on the web UI and REST API are synchronized. For example, if the user has the ICA Control / Connections privilege then they can access this page on the web UI and also the /api/configuration/ica/connections endpoint on the REST API.For details, see Modifying group privileges in the Administration Guide.

  • Note that the system time of SPS and the client must be synchronized. The authentication cookie is valid for twenty minutes, and both SPS and most REST clients validate this. As a result, if the system time of SPS and the client is significantly different from each other, the authentication seems to be successful, but you will not be able to actually access SPS. (If the session_id is missing from the cookies file, check the system clocks.)

  • Make sure that user credentials are encoded in UTF-8.

The authentication procedure:

  1. To authenticate on the SPS REST server, send an HTTPS GET request, including your certificate to the /api/authentication?type=x509 resource. The certificate must be signed by the Trusted CA certificate that is configured on the Users & Access Control > Settings > X.509 > AUTHENTICATION CA field of the SPS web interface, or the /api/configuration/aaa/settings resource.

  2. If the authentication is successful, the server responds with an HTTP 302 redirect to the /api/ resource, and also , sets an HTTP cookie named session_id. This cookie is used to identify the client in every subsequent HTTP request. The response body also includes a meta object.

  3. For every subsequent request, include the session_id header with the value of the received session ID. For example:

    session_id 087658d7e30cdc2552b015dd761b6f7ccb25bbd5

  4. The authenticated session times out after 20 minutes of inactivity.

    Note that the system time of SPS and the client must be synchronized. The authentication cookie is valid for twenty minutes, and both SPS and most REST clients validate this. As a result, if the system time of SPS and the client is significantly different from each other, the authentication seems to be successful, but you will not be able to actually access SPS. (If the session_id is missing from the cookies file, check the system clocks.)

URL
GET https:<IP-address-of-SPS>/api/authentication
Headers
Header name Description Required Values
Authorization Contains the username and password of the user Required The string Basic followed by the username:password encoded using the RFC2045-MIME. For example, Basic YWRtaW46YQ==
Sample request
Example: Authenticate to the SPS REST server using curl

The following command authenticates on SPS using the curl HTTP client. The --insecure option used in the example is used to bypass verifying the certificate of SPS. (Alternatively, you can use the --cacert option or the CURL_CA_BUNDLE environment variable to specify the Certificate Authority to verify the certificate of SPS. For more information, see the curl man page).

When using the REST API in production environments, make sure to download the CA certificate of SPS from Basic Settings > Management > SSL certificate > CA X.509 certificate. Validate the certificate of SPS using this CA certificate, or with the CA certificate you used to sign the Server X.509 certificate of SPS.

curl --basic --user <username>:<password> --cookie-jar cookies.txt --insecure https://<SPS-IP-address>/api/authentication

The cookie containing the session ID is also received (you can display it for example with the tail -l cookies command).

localhost  FALSE  /  FALSE  1395325830  session_id  600dc0ffeec0ffeec0ffeec0ffeec0ffeec0ffee

The following command retrieves the configuration of SPS, using the session ID received during the authentication.

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

The following is a sample response received if the authentication is successful.

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

{
  "meta": {
     "href": "/api",
     "next": "/api",
     "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.

Code Description Notes
302 OK Successful authentication. If the authentication is successful, the server returns the 302 status code, and a meta object in the response body. Also, the HTTP headers of the response include an HTTP cookie named session_id. This cookie is used to identify the client in every subsequent HTTP request. The Location header in the response is /api/.
400 InvalidAuthenticationRequest Unable to authenticate: no valid credentials found. SPS returns this message if password fallback is enabled for the admin user, but the admin tries to authenticate with a certificate on the /api/authentication endpoint. To authenticate with a certificate, use the /api/authentication?type=x509 endpoint.
401 AuthenticationFailure Authenticating the user with the given credentials has failed.
405 MethodNotAllowed You tried using an unsupported HTTP method. Use the GET method for authentication.

Listing SPS login methods

List login methods (local, LDAP, RADIUS, or X.509) to determine which login methods are available to you to authenticate to SPS. For more information on authentication, see Authenticate to the SPS REST API.

URL
GET https://<IP-address-of-SPS>/api/authentication/login_methods
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 available login methods in SPS.

curl -X GET https://<IP-address-of-SPS>/api/authentication/login_methods
Response

The following is a sample response received if the request is successful.

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

 {
                "login_methods": [
                    {
                        "name": "local",
                        "title": "Local login",
                        "authentication": "local",
                        "credential": "password"
                    },
                    {
                        "name": "x509_name",
                        "title": "X509 login",
                        "authentication": "x509",
                        "credential": "x509"
                    },
                    {
                        "name": "x509_with_ldap_groups_name",
                        "title": "X509 login ldap groups",
                        "authentication": "x509",
                        "credential": "x509"
                    },
                    {
                        "name": "radius_with_local_groups_name",
                        "title": "Radius login with local groups",
                        "authentication": "radius",
                        "credential": "password"
                    },
                    {
                        "name": "radius_with_ldap_groups_name",
                        "title": "Radius login with ldap groups",
                        "authentication": "radius",
                        "credential": "password"
                    },
 
                ],
                "meta": {
                    "href": "/api/authentication/login_methods",
                    "next": "/api/authentication"
                }
            }
 

Elements of the response message body include:

Element

Type

Description

Notes

login_methods

object array

A list of available SPS login methods.

 

login_methods.name

string

A unique identifier for the login method.

 

login_methods.title

string

The title that appears above the login method button on the SPS web interface. This can be customized.

In the case of X.509 login method, there is only one button.

login_methods.authentication

enum

The login method used for authentication.

 

credential

enum

The type of credential used for authentication.

Possible values are:

  • password

    Send the username and password in a Basic Authorization header.

  • x509

    Use a X.509 certificate for authentication.

HTTP response codes

For more information and a list of standard HTTP response codes, see Application level error codes.

Retrieve user information

You can check the endpoints and methods that a particular user is authorized to access.

Prerequisites

  • The user must be logged in.

URL
GET https:<IP-address-of-SPS>/api/user_info
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 retrieves user information from SPS about the logged in user, using the session ID received during the authentication.

Querying user info request

This information is also available on the /api/user/info and /api/user_info endpoints.

Response

If the user information is retrieved successfully, the response is the following.

Querying user info response

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

Element Type Description

login_method

 

string

The user's login method during authentication.

 

login_method.authentication

string

This field defines the type of the authentication. The possible values are: local, ldap, x509, radius, saml2.

 

login_method.credential

string

This field defines the credential type. The possible values are: password, x509, local, cluster, federated.

 

login_method.name

string

The name of the login method.

user Top-level element, contains the details of the user whose access rights information has been retrieved.
user.name string The user name of the logged-in user whose information has been retrieved.
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
200 OK User information has been retrieved successfully.
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.
Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating