Chat now with support
Chat mit Support

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

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.

Checking the transaction status

Before changing anything in the configuration of SPS, you must POST a request to open a transaction.

URL
GET https:<IP-address-of-SPS>/api/transaction/
Sample request

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

curl --cookie cookies --request GET https://<IP-address-of-SPS>/api/transaction
Response

The following is a sample response received if opening the transaction is successful.

{
              "body": {
                  "commit_message": "optional",
                  "status": "closed"
              },
              "key": "transaction",
              "meta": {
                  "href": "/api/transaction",
                  "parent": "/api"
              }
          }
Element

Type

 Description

Notes
body.commit_message

enum

Commit messages can be used to add an explanation to every configuration change.

Possible values:

  • required - the value of the commit_message parameter is required, if the require_commitlog parameter in /api/configuration/management/accounting is set to true.

  • optional - the value of the commit_message parameter is optional, if the require_commitlog parameter in /api/configuration/management/accounting is set to false.

body.status

enum

The status of the current transaction. By default, or after a successful commit it is closed. After successfully opening a transaction, it is open.

 

key

string

Top level element, contains the details of the current transaction.

 

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

Open a transaction

The REST API of SPS manages the changes of the configuration in transaction. You can open a transaction with a POST request, but the first change of the configuration will open the transaction automatically. For details about the transaction model of SPS see How to configure SPS using REST.

URL
POST https:<IP-address-of-SPS>/api/transaction
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).
POST body

Note that you must:

  • either send an empty body in the POST request,

  • or include a Content-Length: 0 header.

Otherwise the SPS REST server returns a 411 - Length Required error.

Sample request

The following command opens a new transaction on SPS, using the session ID received during the authentication.

curl -X POST --data "" --cookie cookies https://<IP-address-of-SPS>/api/transaction
Response

The following is a sample response received if opening the transaction is successful.

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

{
  "meta": {
    "href": "/api/transaction",
    "parent": "/api"
  }
}

After opening a transaction successfully, the transaction status changes to open.

{
    "body": {
        "commit_message": "optional|required"
        "status": "open"
    },
    "key": "transaction",
    "meta": {
        "changes": "/api/transaction/changes",
        "href": "/api/transaction",
        "parent": "/api"
    }
}
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 Transaction opened 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.
405 MethodNotAllowed You tried using an unsupported HTTP method. Use the POST method to open a transaction.
409 WebGuiOrConsoleConfigInProgress The configuration of SPS is locked. Committing a new transaction is not allowed while another user is modifying configuration through interfaces other than the REST API. For example, web GUI, console, and so on.
411 UnsupportedMethod You must send a body (which can be empty) in this POST request, otherwise the SPS REST server returns a 411 - Length Required error.

Commit a transaction

To submit your changes to SPS, you have to commit the transaction by using a PUT request with a JSON object. For details about the transaction model of SPS, see How to configure SPS using REST.

Note that committing a transaction locks the configuration of SPS similarly to accessing SPS from the web interface. For more information, see "Multiple users and locking" in the Administration Guide.

URL
PUT https:<IP-address-of-SPS>/api/transaction
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).
PUT body

The PUT request must include the following JSON object in its body.

{
  "status": "commit"
}

If the Basic Settings > Management > Accounting settings > Require commit log option is selected in the SPS web interface, you must include a commit message (a message object) in the request. This message will be visible on the Users & Access Control > Configuration History page of the SPS web interface. Note that on the Users & Access Control > Configuration History page, changes performed using the REST API are listed as changes to the REST server/REST configuration page.

{
  "status": "commit",
  "message": "My commit message"
}
Sample request

The following command commits a transaction to SPS, using the session ID received during the authentication.

curl -d '{"status": "commit","message": "My commit message"}' --cookie cookies -X PUT https://<IP-address-of-SPS>/api/transaction
Response

The following is a sample response received if committing the transaction is successful.

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

After a successful commit, the transaction status changes to closed. To make other changes, you have to open a new transaction.

{
  "meta": {
    "href": "/api/transaction",
    "parent": "/api"
  },
  "key": "transaction",
  "transaction": {
    "status": "closed"
  }
}
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 Transaction committed 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.
405 MethodNotAllowed You tried using an unsupported HTTP method. Use the PUT method to commit a transaction.
Verwandte Dokumente

The document was helpful.

Bewertung auswählen

I easily found the information I needed.

Bewertung auswählen