One Identity Safeguard for Privileged Sessions 8.0 LTS - REST API Reference Guide

The following sections give you a general overview of how the SPS REST API works.

The authentication procedure:

1. To authenticate on the SPS REST server, send a GET request over HTTPS using the basic HTTP authentication method, including your username and password to the /api/authentication resource.

2. If the authentication is successful, the server returns the 200 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.

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

   session_id 087658d7e30cdc2552b015dd761b6f7ccb25bbd5

   NOTE: On Microsoft Windows platforms, to include the session ID, use the SessionVariable option in PowerShell. For example:

   $cred = Get-Credential 
   Invoke-WebRequest -skipcertificatecheck -Uri 
   "<SPS IP or hostname>/api/authentication?login_method=us"
   -Credential $cred -SessionVariable sessionid
   					
   Invoke-WebRequest -skipcertificatecheck -Uri "https://<example.com>/api/endpoints" -websession $sessionid

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

Sample request

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

localhost  FALSE  /  FALSE  1395325830  session_id  600dc0ffeec0ffeec0ffeec0ffeec0ffeec0ffee

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"
  }
}

https://<IP-address-of-SPS>/api/authentication?login_method=<name-of-the-login-method>&type=<password|x509>

curl --user <username>:<password> https://<IP-address-of-SPS>/api/authentication?login_method=example_login_method&type=password

curl --key <private-key.pem> --cert <x509-certificate.pem> https://<IP-address-of-SPS>/api/authentication?login_method=example_login_method&type=x509

{

"meta": {

    "href": "/api/authentication",

    "next": "/api",

    "remaining_seconds": 600,

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

In addition to the cookie-based authentication methods (Authenticate to the SPS REST API or Authenticate to the SPS REST API using X.509 certificate), you can use API keys to authenticate to the SPS REST API. This appliance access method is most suitable for scripts, so that saving passwords to text files can be avoided.

API keys are associated with a user entry. When an HTTP request is made to the REST API, which has the Authorization: apikey <token_value> header, the request will run with the same privileges, as it had been made by the authenticated user using HTTP cookies. The user’s privileges are determined by the groups to which the user belongs at the time of the request.

API tokens are random base64-encoded data, and SPS only displays the cleartext value once, right after its creation. The tokens are kept in the configuration in a cryptographically secure way and are subject to system backup and cluster replication.

API keys replace the authentication step entirely, therefore the API key access of a user remains available after the user password is changed or when their login credentials are revoked.

Authenticated users can create their own API key. Administrators who have read privilege to Users & Access control can list the API keys of all users. (The token value is not displayed.) Administrators with write privilege to Users & Access Control can remove API keys of any user.

Limitations:

• Currently it is not possible to open or commit transactions when using API keys, therefore API keys cannot be used for changing SPS configuration or any other operation, which requires a transaction commit.

• Currently it is not possible to view and manage API keys from the UI.

• API keys can only be used with login methods, where api_key_access is set to enabled (Configuring SPS login methods).

• The local admin user is not allowed to have an API key.

• Groups obtained directly from a SAML2 Identity Provider are not available for API key access.

• API keys do not have an expiry time; the user or the administrator must remove the token in order to prevent the future use of the token. Removing an API key cannot be undone.

To enable API key access for a login method, see Configuring SPS login methods.

curl -H "Authorization: apikey <token_value>" https://<IP-address-of- 

SPS>/api/health_status 

Privileged administrators have write access to Users & Access Control and can remove API keys of users.

Users are identified by the combination of the following two pieces of information:

• The identifier of the login method (Configuring SPS login methods)

• The username string

URL

https://<IP-address-of-SPS>/api/configuration/aaa/local_database/api_keys

HTTP operations

HTTP operations on the /api/configuration/aaa/local_database/api_keys endpoint include:

Sample request for listing API keys

GET /api/aaa/local_database/api_keys

Sample Response

The following is a sample response received when listing all API keys.

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

{ 

                "items": [ 

                { 

                "body": { 

                "login_method": "f46acbd3-69c4-4562-8ed6-3212cc8750a8", 

                "name": "my_api_key", 

                "username": "exampleuser" 

                }, 

                "key": "575bbc51-c2a8-414b-8b7a-173da8d3cc9b", 

                "meta": { 

                "href": "/api/configuration/aaa/local_database/api_keys/575bbc51-c2a8-414b-8b7a-173da8d3cc9b" 

                } 

                }, 

                { 

                "body": { 

                "login_method": "f46acbd3-69c4-4562-8ed6-3212cc8750a8", 

                "name": "my_other_api_key", 

                "username": "exampleuser" 

                }, 

                "key": "f61f378e-bf15-4761-b507-5fe81cbf55de", 

                "meta": { 

                "href": "/api/configuration/aaa/local_database/api_keys/f61f378e-bf15-4761-b507-5fe81cbf55de" 

                } 

                } 

                ] 

            } 

Sample request for removing an API key

DELETE /api/aaa/local_database/api_keys/<key-of-API-key>

After removing an API key, commit your changes (Commit a transaction).