Chat now with support
Chat with Support

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

Introduction Using the Safeguard for Privileged Sessions REST API Basic settings User management and access control Managing Safeguard for Privileged Sessions General connection settings HTTP connections Citrix ICA connections RDP connections SSH connections Telnet connections VNC connections Search, download, and index sessions Reporting Advanced authentication and authorization Completing the Welcome Wizard using REST Enable and configure analytics using REST About us Third-party contributions

Privileges of usergroups

This endpoint lists the usergroups configured on Safeguard for Privileged Sessions, and the privileges (ACLs) of each group.

Note that currently you cannot edit the privileges (ACLs) of the groups using the REST API. If you change the privileges of a usergroup on the Safeguard for Privileged Sessions web interface, the changes will apply to the users when they authenticate again on Safeguard for Privileged Sessions, the privileges of active sessions are not affected.

URL
GET https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/aaa/acls
Headers
Header 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 details on authentication, see Authenticate to the Safeguard for Privileged Sessions REST API.

Note that this session ID refers to the connection between the REST client and the Safeguard for Privileged Sessions REST API. It is not related to the sessions that Safeguard for Privileged Sessions records (and which also have a session ID, but in a different format).
Sample request

The following command lists the local users.

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

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

{
    "body": [
        {
            "group": "basic-view",
            "objects": [
                "/special/basic"
            ],
            "permission": "read"
        },
        {
            "group": "basic-write",
            "objects": [
                "/special/basic"
            ],
            "permission": "write"
        },
        {
            "group": "auth-view",
            "objects": [
                "/special/auth"
            ],
            "permission": "read"
        },
        {
            "group": "auth-write",
            "objects": [
                "/special/auth"
            ],
            "permission": "write"
        },
        {
            "group": "search",
            "objects": [
                "/special/searchmenu"
            ],
            "permission": "read"
        },
        {
            "group": "changelog",
            "objects": [
                "/special/changelog"
            ],
            "permission": "read"
        },
        {
            "group": "policies-view",
            "objects": [
                "/special/pol"
            ],
            "permission": "read"
        },
        {
            "group": "policies-write",
            "objects": [
                "/special/pol"
            ],
            "permission": "write"
        },
        {
            "group": "ssh-view",
            "objects": [
                "/special/ssh"
            ],
            "permission": "read"
        },
        {
            "group": "ssh-write",
            "objects": [
                "/special/ssh"
            ],
            "permission": "write"
        },
        {
            "group": "rdp-view",
            "objects": [
                "/special/rdp"
            ],
            "permission": "read"
        },
        {
            "group": "rdp-write",
            "objects": [
                "/special/rdp"
            ],
            "permission": "write"
        },
        {
            "group": "telnet-view",
            "objects": [
                "/special/telnet"
            ],
            "permission": "read"
        },
        {
            "group": "telnet-write",
            "objects": [
                "/special/telnet"
            ],
            "permission": "write"
        },
        {
            "group": "vnc-view",
            "objects": [
                "/special/vnc"
            ],
            "permission": "read"
        },
        {
            "group": "vnc-write",
            "objects": [
                "/special/vnc"
            ],
            "permission": "write"
        },
        {
            "group": "indexing",
            "objects": [
                "/special/search/search",
                "/special/bap"
            ],
            "permission": "write"
        },
        {
            "group": "ica-view",
            "objects": [
                "/special/ica"
            ],
            "permission": "read"
        },
        {
            "group": "ica-write",
            "objects": [
                "/special/ica"
            ],
            "permission": "write"
        },
        {
            "group": "api",
            "objects": [
                "/special/rpcapi"
            ],
            "permission": "write"
        },
        {
            "group": "http-view",
            "objects": [
                "/special/http"
            ],
            "permission": "read"
        },
        {
            "group": "http-write",
            "objects": [
                "/special/http"
            ],
            "permission": "write"
        },
        {
            "group": "indexer-view",
            "objects": [
                "/special/indexer"
            ],
            "permission": "read"
        },
        {
            "group": "indexer-write",
            "objects": [
                "/special/indexer"
            ],
            "permission": "write"
        }
    ],
    "key": "acls",
    "meta": {
        "first": "/api/configuration/aaa/acls",
        "href": "/api/configuration/aaa/acls",
        "last": "/api/configuration/aaa/settings",
        "next": "/api/configuration/aaa/local_database",
        "parent": "/api/configuration/aaa",
        "previous": null,
        "transaction": "/api/transaction"
    }
}
Element Type Description
body Top level element (JSON object) Contains the properties of the user.
group string The name of the usergroup.
objects list The list of privileges that the group has access to.
permission read | write The type of the permission. The group needs write access to configure an object, or to perform certain actions.
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.

Code Description Notes
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.
401 AuthenticationFailure Authenticating the user with the given credentials has failed.
404 NotFound The requested object does not exist.

Manage users and usergroups locally on Safeguard for Privileged Sessions

Contains the endpoints for managing users and usergroups locally on Safeguard for Privileged Sessions.

URL
GET https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/aaa/local_database
Headers
Header 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 details on authentication, see Authenticate to the Safeguard for Privileged Sessions REST API.

Note that this session ID refers to the connection between the REST client and the Safeguard for Privileged Sessions REST API. It is not related to the sessions that Safeguard for Privileged Sessions records (and which also have a session ID, but in a different format).
Sample request

The following command lists the endpoints of the local database.

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

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

{
    "items": [
        {
            "key": "groups",
            "meta": {
                "href": "/api/configuration/aaa/local_database/groups"
            }
        },
        {
            "key": "users",
            "meta": {
                "href": "/api/configuration/aaa/local_database/users"
            }
        }
    ],
    "meta": {
        "first": "/api/configuration/aaa/acls",
        "href": "/api/configuration/aaa/local_database",
        "last": "/api/configuration/aaa/settings",
        "next": "/api/configuration/aaa/settings",
        "parent": "/api/configuration/aaa",
        "previous": "/api/configuration/aaa/acls",
        "transaction": "/api/transaction"
    }
}
Element Description
groups Endpoint that contains local usergroups.
users Endpoint that contains local usernames.
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.

Code Description Notes
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.
401 AuthenticationFailure Authenticating the user with the given credentials has failed.
404 NotFound The requested object does not exist.

Manage usergroups locally on Safeguard for Privileged Sessions

Contains the local usergroups of Safeguard for Privileged Sessions. You can use local groups to control the privileges of Safeguard for Privileged Sessions local and LDAP users — who can view and configure what. You can edit the group memberships here as well.

Note that currently you cannot edit the privileges (ACLs) of the groups using the REST API. If you change the privileges of a usergroup on the Safeguard for Privileged Sessions web interface, the changes will apply to the users when they authenticate again on Safeguard for Privileged Sessions, the privileges of active sessions are not affected.

URL
GET https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/aaa/local_database/groups
Headers
Header 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 details on authentication, see Authenticate to the Safeguard for Privileged Sessions REST API.

Note that this session ID refers to the connection between the REST client and the Safeguard for Privileged Sessions REST API. It is not related to the sessions that Safeguard for Privileged Sessions records (and which also have a session ID, but in a different format).
Sample request

The following command lists the local usergroups.

curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/aaa/local_database/groups
Response

The following is a sample response received when querying a particular usergroup endpoint. For details of the meta object, see Introduction.

{
    "body": {
        "members": [],
        "name": "http-write"
    },
    "key": "ca2dc85730ca082ee6b5c8",
    "meta": {
        "first": "/api/configuration/aaa/local_database/groups/224696054489c27f6c5710",
        "href": "/api/configuration/aaa/local_database/groups/ca2dc85730ca082ee6b5c8",
        "last": "/api/configuration/aaa/local_database/groups/ca2dc85730ca082ee6b5f8",
        "next": "/api/configuration/aaa/local_database/groups/b080b1ba546232548bb1f9",
        "parent": "/api/configuration/aaa/local_database/groups",
        "previous": "/api/configuration/aaa/local_database/groups/b080b1ba546232548bb1a9",
        "transaction": "/api/transaction"
    }
}
Element Type Description
body Top level element (JSON object) Contains the properties of the usergroup.
members list Lists the names of the users belonging to the group.
name string The name of the group.
key string Top level element, contains the ID of the endpoint.
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.

Code Description Notes
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.
401 AuthenticationFailure Authenticating the user with the given credentials has failed.
404 NotFound The requested object does not exist.
409 NoTransaction No open Transaction is available. You must open a transaction first (for details, see Using the Safeguard for Privileged Sessions REST API).
Add new local usergroup

To create a new local usergroup, you have to POST the name and members of the group as a JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/aaa/local_database/groups endpoint. For details, see Using the Safeguard for Privileged Sessions REST API.

  1. Open a transaction.

    For details, see Using the Safeguard for Privileged Sessions REST API.

  2. Create a new usergroup.

    POST the name of the group and the list of member accounts as a JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/aaa/local_database/groups endpoint. The body of the POST request should be the following. Note that you must refer to existing user accounts, and use their reference IDs, not their usernames.

    {
    "name": "new-userggroup",
    "members": ["46785097158061f46c63d0", "1362061674580df4e00620d"]
}

    For example:

    curl -X POST -H "Content-Type: application/json" --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/aaa/local_database/groups --data '{"name": "new-usergroup", "members": ["46785097158061f46c63d0", "1362061674580df4e00620d"]}'

    If the POST request is successful, the response includes a reference ID for the usergroup object.

  3. Commit your changes.

    For details, see Using the Safeguard for Privileged Sessions REST API.

Delete usergroup

To delete a usergroup, you have to:

  1. Open a transaction (for details, see Using the Safeguard for Privileged Sessions REST API).

  2. DELETE the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/aaa/local_database/groups/<ID-of-the-group> endpoint. For details, see Using the Safeguard for Privileged Sessions REST API. If the DELETE request is successful, the response includes only the meta object, for example:

    {
    "meta": {
        "href": "/api/configuration/aaa/local_database/groups/b080b1ba546232548bb1a9",
        "parent": "/api/configuration/aaa/local_database/groups"
    }
}

  3. Commit your changes to actually delete the object from Safeguard for Privileged Sessions (for details, see Using the Safeguard for Privileged Sessions REST API).

Delete user from usergroup

To delete a user from a usergroup, you have to:

  1. Open a transaction (for details, see Using the Safeguard for Privileged Sessions REST API).

  2. Create an updated version of the usergroup object that does not include the user you want to delete.

  3. PUT the updated usergroup object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/aaa/local_database/groups/<ID-of-the-group> endpoint. For details, see Using the Safeguard for Privileged Sessions REST API.

  4. Commit your changes to actually delete the object from Safeguard for Privileged Sessions (for details, see Using the Safeguard for Privileged Sessions REST API).

Manage users locally on Safeguard for Privileged Sessions

Contains the local users of Safeguard for Privileged Sessions. You can use local users and groups to control the privileges of Safeguard for Privileged Sessions local and LDAP users — who can view and configure what.

 NOTE:

The admin user is available by default and has all possible privileges. It is not possible to delete this user.

Local users cannot be managed when LDAP authentication is used. When LDAP authentication is enabled, the accounts of local users is disabled, but they are not deleted,

When using RADIUS authentication together with local users, the users are authenticated to the RADIUS server, only their group memberships must be managed locally on Safeguard for Privileged Sessions.

For details, see Authentication and user database settings.

URL
GET https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/aaa/local_database/users
Headers
Header 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 details on authentication, see Authenticate to the Safeguard for Privileged Sessions REST API.

Note that this session ID refers to the connection between the REST client and the Safeguard for Privileged Sessions REST API. It is not related to the sessions that Safeguard for Privileged Sessions records (and which also have a session ID, but in a different format).
Sample request

The following command lists the local users.

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

The following command displays the parameters of a specific user.

curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/aaa/local_database/users/<ID-of-the-user>
Response

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

{
    "items": [
        {
            "key": "103640099357f3b14f0529a",
            "meta": {
                "href": "/api/configuration/aaa/local_database/users/103640099357f3b14f0529a"
            }
        },
        {
            "key": "46785097158061f46c63d0",
            "meta": {
                "href": "/api/configuration/aaa/local_database/users/46785097158061f46c63d0"
            }
        }
    ],
    "meta": {
        "first": "/api/configuration/aaa/local_database/groups",
        "href": "/api/configuration/aaa/local_database/users",
        "last": "/api/configuration/aaa/local_database/users",
        "next": null,
        "parent": "/api/configuration/aaa/local_database",
        "previous": "/api/configuration/aaa/local_database/groups",
        "transaction": "/api/transaction"
    }
}

The following is a sample response received when querying a specific user.

{
    "body": {
        "name": "testuser",
        "password": {
            "key": "8f84d7d1-9de1-429a-a7a7-c33a61cc7419",
            "meta": {
                "href": "/api/configuration/passwords/8f84d7d1-9de1-429a-a7a7-c33a61cc7419"
            }
        },
        "password_created": 1476796261
    },
    "key": "46785097158061f46c63d0",
    "meta": {
        "first": "/api/configuration/aaa/local_database/users/103640099357f3b14f0529a",
        "href": "/api/configuration/aaa/local_database/users/46785097158061f46c63d0",
        "last": "/api/configuration/aaa/local_database/users/46785097158061f46c63d0",
        "next": null,
        "parent": "/api/configuration/aaa/local_database/users",
        "previous": "/api/configuration/aaa/local_database/users/103640099357f3b14f0529a",
        "transaction": "/api/transaction"
    }
Element Type Description
body Top level element (JSON object) Contains the properties of the user.
name string The username of the user account.
password reference A reference to a password object. To create or update passwords, see Passwords stored on Safeguard for Privileged Sessions.
password_created integer The date when the password of the account was changed in UNIX timestamp format (for example, 1476796261).
key string Top level element, contains the ID of the user.
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.

Code Description Notes
400 SemanticError You tried to reuse a password object. You can use a password object for only one purpose, that is, you cannot reference a password object twice.
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.
401 AuthenticationFailure Authenticating the user with the given credentials has failed.
404 NotFound The requested object does not exist.
409 NoTransaction No open Transaction is available. You must open a transaction first (for details, see Using the Safeguard for Privileged Sessions REST API).
Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating