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

Topics:

For SSH, RDP, Telnet, and Citrix ICA connections, usermapping policies can be defined. A usermapping policy describes who can use a specific username to access the remote server: only members of the specified local or LDAP usergroups (for example, administrators) can use the specified username (for example, root) on the server.

URL

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

Cookies

Sample request

The following command lists the existing usermapping policies.

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

The following command retrieves the properties of a specific usermapping policy.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/policies/usermapping_policies<object-id>

Response

The following is a sample response received when listing usermapping policies.

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

{
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/usermapping_policies",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": null,
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/userlists",
    "transaction": "/api/transaction"
  },
  "items": [
    {
      "key": "11581153055704544883f77",
      "meta": {
        "href": "/api/configuration/policies/usermapping_policies/11581153055704544883f77"
      }
    },
    {
      "key": "9328731525704545f5e3de",
      "meta": {
        "href": "/api/configuration/policies/usermapping_policies/9328731525704545f5e3de"
      }
    }
  ]
}

When retrieving the endpoint of a specific host key, the response is the following.

{
  "body": {
    "allow_other_remote_users_without_mapping": false,
    "mappings": [
      {
        "allowed_groups": [],
        "remote_user": "test"
      },
      {
        "allowed_groups": [
          "admins"
        ],
        "remote_user": "root"
      }
    ],
    "name": "Test"
  },
  "key": "9328731525704545f5e3de",
  "meta": {
    "first": "/api/configuration/policies/usermapping_policies/277736452570454272e157",
    "href": "/api/configuration/policies/usermapping_policies/9328731525704545f5e3de",
    "last": "/api/configuration/policies/usermapping_policies/9328731525704545f5e3de",
    "next": null,
    "parent": "/api/configuration/policies/usermapping_policies",
    "previous": "/api/configuration/policies/usermapping_policies/11581153055704544883f77",
    "transaction": "/api/transaction"
  }
}

Example mappings:

Anyone can log in to the remote server as the test user:

"mappings": [
  {
    "allowed_groups": [],
    "remote_user": "test"
  }
Only the members of the admin group can log in to the remote server as the root user:
"mappings": [
  {
    "allowed_groups": [
      "admins"
    ],
    "remote_user": "root"
  }
    

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.

Add a usermapping policy

To add a usermapping policy, you have to:

1. Open a transaction.

   For more information, see Open a transaction.

2. Create the JSON object for the new usermapping policy.

   POST the JSON object to the https://<IP-address-of-SPS>/api/configuration/policies/usermapping 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 usermapping policy. For example:

   {
     "key": "2e8692fa-7fda-4753-8363-37e8244f6b80",
     "meta": {
       "href": "/api/configuration/policies/usermapping_policies/2e8692fa-7fda-4753-8363-37e8244f6b80",
       "parent": "/api/configuration/policies/usermapping_policies",
       "transaction": "/api/transaction"
     }
   }

3. Commit your changes.

   For more information, see Commit a transaction.

Modify a usermapping policy

To modify a usermapping policy, you have to:

1. Open a transaction.

   For more information, see Open a transaction.

2. Modify the JSON object of the usermapping policy.

   PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/policies/usermapping/<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.

Contains the endpoints for configuring plugins.

URL

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

Cookies

Sample request

The following command lists endpoints for configuring plugins.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/plugins

Response

The following is a sample response received when listing endpoints for configuring plugins.

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

{
    "items": [
        {
            "key": "aa",
            "meta": {
                "href": "/api/configuration/plugins/aa"
            }
        },
        {
            "key": "configuration_sync",
            "meta": {
                "href": "/api/configuration/plugins/configuration_sync"
            }
        },
        {
            "key": "credentialstore",
            "meta": {
                "href": "/api/configuration/plugins/credentialstore"
            }
        },
        {
            "key": "signingca",
            "meta": {
                "href": "/api/configuration/plugins/signingca"
            }
        }
    ],
    "meta": {
        "first": "/api/configuration/aaa",
        "href": "/api/configuration/plugins",
        "last": "/api/configuration/x509",
        "next": "/api/configuration/policies",
        "parent": "/api/configuration",
        "previous": "/api/configuration/passwords",
        "remaining_seconds": 600,
        "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.

To upload or update a plugin, complete the following steps. To update a plugin, upload a new version. Starting with version 6.4, you can also delete plugins using the REST API. For details, see Delete a plugin.

1. Open a transaction.

   For more information, see Open a transaction.

2. POST the plugin as a zip file (application/zip) to the https://<IP-address-of-SPS>/api/upload/plugins endpoint, for example:

   curl -X POST -H "Content-Type: application/zip" --cookie cookies https://<IP-address-of-SPS>/api/upload/plugins --data-binary @<path-to-plugin.zip>

   If the POST request is successful, the response includes the key of the new plugin, as well as information about the uploaded plugin. For example:

   {
       "meta": {
           "href": "/api/configuration/plugins/aa/aa423b72-0d0f-4275-be30-494e9a99ffad",
           "parent": "/api/configuration/plugins/aa"
       },
       "key": "aa423b72-0d0f-4275-be30-494e9a99ffad",
       "body": {
           "name": "Sample-Authentication-Plugin",
           "description": "My custom authentication plugin",
           "version": "1.12",
           "path": "/opt/scb/var/plugins/aa/Sample-Authentication-Plugin",
           "api": "1.0"
       }
   }

3. Commit your changes.

   For more information, see Commit a transaction.

Note the following points.

• Re-uploading an already existing plugin overwrites the existing plugin.

• Uploading a newer version of an already existing plugin overwrites the existing plugin.

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.