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

User lists are local white- or blacklists of usernames that allow fine-control over who can access a connection or a channel.

You can use user lists when configuring gateway_groups or remote_groups in the allowed_for element of channel policies. For more information on configuring channel policies, see Channel policy.

To use this option, you must also configure web gateway authentication in the connection policy, or client-side gateway authentication back-end in the authentication policy.

URL

GET https://<IP-address-of-SPS>/api/configuration/policies/userlists

Cookies

Sample request

The following command lists the user lists created on SPS.

curl --cookie cookies.txt https://<IP-address-of-SPS>/api/configuration/policies/userlists

The following command retrieves the properties of a specific list.

curl --cookie cookies.txt https://<IP-address-of-SPS>/api/configuration/policies/userlists/<key-id>

Response

The following is a sample response received when retrieveing the user lists.

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

The keys with negative ID values are the default user lists of SPS.

{
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/userlists",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/usermapping_policies",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/user_databases",
    "transaction": "/api/transaction"
  },
  "items": [
    {
      "key": "-1",
      "meta": {
        "href": "/api/configuration/policies/userlists/-1"
      }
    },
    {
      "key": "-2",
      "meta": {
        "href": "/api/configuration/policies/userlists/-2"
      }
    },
    {
      "key": "-3",
      "meta": {
        "href": "/api/configuration/policies/userlists/-3"
      }
    },
    {
      "key": "-4",
      "meta": {
        "href": "/api/configuration/policies/userlists/-4"
      }
    },
    {
      "key": "20088200245706af301b1ba",
      "meta": {
        "href": "/api/configuration/policies/userlists/20088200245706af301b1ba"
      }
    }
  ]
}

When retrieving the endpoint of a specific user list, the response is the following.

{
  "body": {
        "allow": "no_user",
        "except": [
            "root"
        ],
        "name": "root_only"
    },
    "key": "-4",
    "meta": {
        "href": "/api/configuration/policies/userlists/-4"
    }
},
  "key": "-4",
  "meta": {
    "first": "/api/configuration/policies/userlists/-1",
    "href": "/api/configuration/policies/userlists/-4",
    "last": "/api/configuration/policies/userlists/20088200245706af301b1ba",
    "next": "/api/configuration/policies/userlists/20088200245706af301b1ba",
    "parent": "/api/configuration/policies/userlists",
    "previous": "/api/configuration/policies/userlists/-3",
    "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.

{
    "allow": "all_users",
    "except": [
        "root"
    ],
    "name": "no_root"
}

{
    "allow": "no_user",
    "except": [
        "permitted_user1",
        "permitted_user2"
    ],
    "name": "no_root"
}

Add a user list

To add a user list, you have to:

1. Open a transaction

   For more information, see Open a transaction.

2. Create the JSON object for the new user list.

   POST the JSON object to the https://<IP-address-of-SPS>/api/configuration/policies/userlists endpoint. You can find a detailed description of the available parameters listed in Element .

   If the POST request is successful, the response includes the key of the new user list. For example:

   {
     "key": "321314dc-eca0-4e97-b445-0612fedc0165",
     "meta": {
       "href": "/api/configuration/policies/userlists/321314dc-eca0-4e97-b445-0612fedc0165",
       "parent": "/api/configuration/policies/userlists",
       "transaction": "/api/transaction"
     }
   }

3. Commit your changes

   For more information, see Commit a transaction.

Modify a user list

To modify a user list, you have to:

1. Open a transaction

   For more information, see Open a transaction.

2. Modify the JSON object of the user list.

   PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/policies/userlists/<key-of-the-object> endpoint. You can find a detailed description of the available parameters listed in Element .

3. Commit your changes

   For more information, see Commit a transaction.