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

Using the Safeguard for Privileged Sessions REST API

The following sections give you a general overview of how the Safeguard for Privileged Sessions REST API works.

Authenticate to the Safeguard for Privileged Sessions REST API

Prerequisites:

• The REST server must permit password authentication to the Safeguard for Privileged Sessions web interface. If only certificate-based authentication is permitted, see Authenticate to the Safeguard for Privileged Sessions REST API using X.509 certificate.

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

  • If the types field of the response includes the x509 object, certificate-based authentication is permitted.

  • If it includes only the basic object, password authentication is permitted.

  • If it includes both fields, then certificate-based authentication is permitted for the users, but the admin user can authenticate with password as well. Note that in this case, Safeguard for Privileged Sessions assumes that the admin user will authenticate with a password, and expects password-authentication on the /api/authentication endpoint. To authenticate with a certificate, use the /api/authentication?type=x509 endpoint.

• You can access the REST server on the same IP address and port that you use to access the Safeguard for Privileged Sessions 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.

• The user accessing the Safeguard for Privileged Sessions REST API must have the REST server privilege. For details, see "Modifying group privileges" in the Administration Guide. Note that the built-in api usergroup does not have this privilege by default, it is used to access the SOAP RPC API of Safeguard for Privileged Sessions.

• Note that the system time of Safeguard for Privileged Sessions and the client must be synchronized. The authentication cookie is valid for twenty minutes, and both Safeguard for Privileged Sessions and most REST clients validate this. As a result, if the system time of Safeguard for Privileged Sessions and the client is significantly different from each other, the authentication seems to be successful, but you will not be able to actually access Safeguard for Privileged Sessions. (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 Safeguard for Privileged Sessions 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

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

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

URL

GET https://<IP-address-of-Safeguard for Privileged Sessions>/api/authentication

Headers

Sample request

curl --basic --user <username>:<password> --cookie-jar cookies --insecure https://<Safeguard for Privileged Sessions-IP-address>/api/authentication

localhost  FALSE  /  FALSE  1395325830  session_id  600dc0ffeec0ffeec0ffeec0ffeec0ffeec0ffee

curl --cookie cookies --insecure https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration

Response

The following is a sample response received if the authentication is successful. For details of the meta object, see Introduction.

{
  "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 Using the Safeguard for Privileged Sessions REST API.

Authenticate to the Safeguard for Privileged Sessions REST API using X.509 certificate

Prerequisites:

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

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

  • If the types field of the response includes the x509 object, certificate-based authentication is permitted.

  • If it includes only the basic object, password authentication is permitted.

  • If it includes both fields, then certificate-based authentication is permitted for the users, but the admin user can authenticate with password as well. Note that in this case, Safeguard for Privileged Sessions assumes that the admin user will authenticate with a password, and expects password-authentication on the /api/authentication endpoint. To authenticate with a certificate, use the /api/authentication?type=x509 endpoint.

• You can access the REST server on the same IP address and port that you use to access the Safeguard for Privileged Sessions 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.

• The user accessing the Safeguard for Privileged Sessions REST API must have the REST server privilege. For details, see "Modifying group privileges" in the Administration Guide. Note that the built-in api usergroup does not have this privilege by default, it is used to access the SOAP RPC API of Safeguard for Privileged Sessions.

• Note that the system time of Safeguard for Privileged Sessions and the client must be synchronized. The authentication cookie is valid for twenty minutes, and both Safeguard for Privileged Sessions and most REST clients validate this. As a result, if the system time of Safeguard for Privileged Sessions and the client is significantly different from each other, the authentication seems to be successful, but you will not be able to actually access Safeguard for Privileged Sessions. (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 Safeguard for Privileged Sessions 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 AAA > Settings > X.509 > AUTHENTICATION CA field of the Safeguard for Privileged Sessions 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 Safeguard for Privileged Sessions and the client must be synchronized. The authentication cookie is valid for twenty minutes, and both Safeguard for Privileged Sessions and most REST clients validate this. As a result, if the system time of Safeguard for Privileged Sessions and the client is significantly different from each other, the authentication seems to be successful, but you will not be able to actually access Safeguard for Privileged Sessions. (If the session_id is missing from the cookies file, check the system clocks.)

URL

GET https:<IP-address-of-Safeguard for Privileged Sessions>/api/authentication

Headers

Sample request

curl --basic --user <username>:<password> --cookie-jar cookies --insecure https://<Safeguard for Privileged Sessions-IP-address>/api/authentication

localhost  FALSE  /  FALSE  1395325830  session_id  600dc0ffeec0ffeec0ffeec0ffeec0ffeec0ffee

curl --cookie cookies --insecure https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration

Response

The following is a sample response received if the authentication is successful. For details of the meta object, see Introduction.

{
  "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 Using the Safeguard for Privileged Sessions REST API.

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-Safeguard for Privileged Sessions>/api/user_info

Headers

Sample request

The following command retrieves user information from Safeguard for Privileged Sessions about the logged in user, using the session ID received during the authentication.

curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/user_info

Response

The following is a sample response received if the request to retrieve user information is successful. For details of the meta object, see Introduction.

{
  "user": {  
    "name": "admin",
  }
  "endpoints": [
    {
      "methods": [
        "DELETE",
        "GET",
        "POST",
        "PUT" 
      ],
      "url": "/api"
    },
    {
      "...": "..."
    }
  ],
  "meta": {
    "href": "/api/user_info",
    "...": "..."
  }
}

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 Using the Safeguard for Privileged Sessions REST API.