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

Managing Safeguard for Privileged Sessions

Troubleshooting options

Configures debug logging and the retention time of core dump files.

• Debug logging increases the log level of the non-network-related events, adding the commands executed by the Safeguard for Privileged Sessions web interface to the log.

• Safeguard for Privileged Sessions automatically generates core dump files if an important software component of the system crashes. These core dump files can be of great help to the One Identity Support Team to identify problems. To download the generated core dump files, navigate to Basic Settings > Troubleshooting > Core files on the web interface of Safeguard for Privileged Sessions.

URL

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

Headers

Sample request

The following command queries the troubleshooting settings.

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

Response

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

{
  "body": {
    "core_files": {
      "retention_days": 14
    },
    "debug_logging": {
      "enabled": true
    }
  },
  "key": "troubleshooting",
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/troubleshooting",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/vnc",
    "parent": "/api/configuration",
    "previous": "/api/configuration/telnet",
    "transaction": "/api/transaction"
  }
}

Modify troubleshooting settings

To modify troubleshooting settings, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Modify the JSON object of the troubleshooting options.

   PUT the modified JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/troubleshooting endpoint. You can find a detailed description of the available parameters listed in Troubleshooting options.

3. Commit your changes.

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

Internal certificates

This endpoint references the certificates of Safeguard for Privileged Sessions's internal Certificate Authority, Timestamping Authority, and the SSL certificate of the web and REST interface.

URL

GET https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/management/certificates

Headers

Sample request

The following command lists the internal certificates of Safeguard for Privileged Sessions.

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

Response

The following is a sample response received when listing the internal certificates of Safeguard for Privileged Sessions. For details of the meta object, see Introduction.

{
  "body": {
    "ca": {
      "selection": "identity",
      "x509_identity": {
        "key": "fbd684e1-e1ac-4f34-ad25-86c560c51e24",
        "meta": {
          "href": "/api/configuration/x509/fbd684e1-e1ac-4f34-ad25-86c560c51e24"
        }
      }
    },
    "server": {
      "key": "fd1c73e8-bcb8-4d13-991f-722f492dc074",
      "meta": {
        "href": "/api/configuration/x509/fd1c73e8-bcb8-4d13-991f-722f492dc074"
      }
    },
    "tsa": {
      "key": "20e72ede-78ef-460a-b843-68a35d994142",
      "meta": {
        "href": "/api/configuration/x509/20e72ede-78ef-460a-b843-68a35d994142"
      }
    }
  },
  "key": "certificates",
  "meta": {
    "first": "/api/configuration/management/certificates",
    "href": "/api/configuration/management/certificates",
    "last": "/api/configuration/management/webinterface",
    "next": "/api/configuration/management/disk_fillup_prevention",
    "parent": "/api/configuration/management",
    "previous": null,
    "transaction": "/api/transaction"
  }
}

Modify a certificate

To modify a certificate, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Create a CA

   Have the value of the key element of a valid X.509 CA certificate stored on Safeguard for Privileged Sessions.

3. Modify the JSON object of the endpoint.

   Use the X.509 certificate's key as the value of the ca element. You can find a detailed description of the available parameters listed in Internal certificates. PUT the modified JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/management/certificates endpoint.

4. Commit your changes.

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

Headers

To create a new password, you have to POST the password or its hash as a JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/passwords endpoint. For details, see Using the Safeguard for Privileged Sessions REST API. The body of the POST request must contain a JSON object with the parameters listed in Passwords stored on Safeguard for Privileged Sessions. The response to a successful POST message is a JSON object that includes the reference ID of the created password in its key attribute. You can reference this ID in other parts of the configuration, for example, to set the password of a user account. Note that you can use a password object for only one purpose, that is, you cannot reference a password object twice.

URL

POST https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/passwords

• Note that the GET method is not permitted on this endpoint, you cannot list the existing passwords. However, if you know the reference ID of a password, you can display its properties:

  GET https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/passwords/<reference-ID-of-the-password;>

• You cannot directly delete or modify a password, the DELETE and PUT methods are not permitted on password objects. To update a password, create a new one, then update the object that uses the old password to reference the new password.

Sample request

The following command creates a new password object.

curl -X POST -H "Content-Type: application/json" --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/passwords --data '{"plain": "newpassword"}'

If you do not want to include the actual password in the request, the SHA-256 hash of the password is enough:

curl -X POST -H "Content-Type: application/json" --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/passwords --data '{"hash": "$6$rounds=5000$If20/EFyQ4dW3dg/$xrECLfXgZlC2Xr1s257E2aZen42fM7R.sOGG9pkPy1x5ORTx6j03oPWexVlB3f5wnaZOQCBF.NjlDgyg2WEe./"}'

Response

The response to a successful POST message is a JSON object that includes the reference ID of the created password in its key attribute. For details of the meta object, see Introduction.

{
    "key": "faa96916-c85e-46ff-8697-f4cc5e596e7f",
    "meta": {
        "href": "/api/configuration/passwords/faa96916-c85e-46ff-8697-f4cc5e596e7f",
        "parent": "/api/configuration/passwords",
        "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.

Modify or delete password

You cannot directly delete or modify a password, the DELETE and PUT methods are not permitted on password objects. To update a password, create a new one, then update the object that uses the old password to reference the new password. After you commit the transaction, Safeguard for Privileged Sessions will automatically delete the old password. For details, see Passwords stored on Safeguard for Privileged Sessions.

Change the admin password

To change the password of the admin user, complete the following steps.

1. Open a transaction.

   For details, see Open a transaction.

2. Create a new password object

   POST a JSON object containing the password or the hash of the password to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/passwords endpoint. For details, see Passwords stored on Safeguard for Privileged Sessions. For example:

   curl -X POST -H "Content-Type: application/json" --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/passwords --data '{"plain": "mypassword"}'

   If the operation is successful, the response includes a reference key to the new password object.

3. Reference the key of the password in the user configuration.

   Modify the JSON object of the user to reference the key of the new password object, and PUT the modified JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/aaa/local_database/users/<key-of-the-user> endpoint. For example:

   curl -X PUT -H "Content-Type: application/json" --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/aaa/local_database/users/14322374245a7de542bbb04 --data '{"name": "admin", "password": "<key-of-the-new-password>"}'

4. Commit your changes.

   For details, see Commit a transaction.

Change the root password

To change the password of the root user, complete the following steps.

1. Open a transaction.

   For details, see Open a transaction.

2. Create a new password object

   POST a JSON object containing the password or the hash of the password to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/passwords endpoint. For details, see Passwords stored on Safeguard for Privileged Sessions. For example:

   curl -X POST -H "Content-Type: application/json" --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/passwords --data '{"plain": "mypassword"}'

   If the operation is successful, the response includes a reference key to the new password object.

3. Configure Safeguard for Privileged Sessions to use this password for the root user configuration.

   PUT the reference key of the new password object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/management/root_password endpoint. For example:

   curl -X PUT -H "Content-Type: application/json" --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/management/root_password --data '"<key-of-the-new-password>"'

   Note that you must PUT the reference key as a JSON string, enclosed in double-quotes.

4. Commit your changes.

   For details, see Commit a transaction.