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

Usermapping policy

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-Safeguard for Privileged Sessions>/api/configuration/policies/usermapping_policies

Headers

Sample request

The following command lists the existing usermapping policies.

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

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

curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/usermapping_policies<object-id>

Response

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

{
  "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 Using the Safeguard for Privileged Sessions REST API.

Add a usermapping policy

To add a usermapping policy, you have to:

1. Open a transaction.

   For details, see Open a transaction.

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

   POST the JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/usermapping endpoint. You can find a detailed description of the available parameters listed in Usermapping policy.

   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 details, see Commit a transaction.

Modify a usermapping policy

To modify a usermapping policy, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Modify the JSON object of the usermapping policy.

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

3. Commit your changes.

   For details, see Commit a transaction.

Upload a plugin

Contains the endpoints for configuring plugins.

URL

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

Headers

Sample request

The following command lists endpoints for configuring plugins.

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

Response

The following is a sample response received when listing endpoints for configuring plugins. For details of the meta object, see Introduction.

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

To upload or update a plugin, complete the following steps. Note that currently you cannot delete a plugin, only update it by uploading a new version.

1. Open a transaction.

   For details, see Open a transaction.

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

   curl -X POST -H "Content-Type: application/zip" --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/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 details, see Commit a transaction.

Authentication and authorization plugins

The authentication and authorization (AAA) plugins used on Safeguard for Privileged Sessions. To upload or update a plugin, see To upload or update a plugin, complete the following steps. Note that currently you cannot delete a plugin, only update it by uploading a new version..

URL

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

Headers

Sample request

The following command queries the list of AAA plugins used on Safeguard for Privileged Sessions.

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

The following command retrieves the properties of a specific plugin.

curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/plugins/aa/<plugin-id>

Response

The following is a sample response received when querying the list of AAA plugins used on Safeguard for Privileged Sessions. For details of the meta object, see Introduction.

{
  "items": [
    {
      "key": "2080160955734bb2a1ddf9",
      "meta": {
        "href": "/api/configuration/plugins/aa/2080160955734bb2a1ddf9"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/plugins/aa",
    "href": "/api/configuration/plugins/aa",
    "last": "/api/configuration/plugins/ticketing",
    "next": "/api/configuration/plugins/credentialstore",
    "parent": "/api/configuration/plugins",
    "previous": null,
    "transaction": "/api/transaction"
  }
}

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

{
  "body": {
    "api": "1.0",
    "description": "test1",
    "name": "AAPluginExample",
    "path": "/opt/scb/var/plugins/aa/AAPluginExample",
    "version": "1.0"
  },
  "key": "2080160955734bb2a1ddf9",
  "meta": {
    "first": "/api/configuration/plugins/aa/2080160955734bb2a1ddf9",
    "href": "/api/configuration/plugins/aa/2080160955734bb2a1ddf9",
    "last": "/api/configuration/plugins/aa/2080160955734bb2a1ddf9",
    "next": null,
    "parent": "/api/configuration/plugins/aa",
    "previous": null,
    "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.

Credential store plugins

The credential store plugins used on Safeguard for Privileged Sessions. To upload or update a plugin, see To upload or update a plugin, complete the following steps. Note that currently you cannot delete a plugin, only update it by uploading a new version..

URL

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

Headers

Sample request

The following command lists the credential store plugins stored on Safeguard for Privileged Sessions.

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

The following command retrieves the properties of a specific plugin.

curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/plugins/credentialstore/<plugin-id>

Response

The following is a sample response received when listing the credential store plugins used on Safeguard for Privileged Sessions. For details of the meta object, see Introduction.

{
  "items": [
    {
      "key": "2534221015734bb18aaf32",
      "meta": {
        "href": "/api/configuration/plugins/credentialstore/2534221015734bb18aaf32"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/plugins/aa",
    "href": "/api/configuration/plugins/credentialstore",
    "last": "/api/configuration/plugins/ticketing",
    "next": "/api/configuration/plugins/ticketing",
    "parent": "/api/configuration/plugins",
    "previous": "/api/configuration/plugins/aa",
    "transaction": "/api/transaction"
  }
}

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

{
  "body": {
    "api": "1.0",
    "description": "Demo credentialstore plugin for demonstration purposes",
    "name": "DemoCredentialStorePlugin",
    "path": "/opt/scb/var/plugins/credentialstore/DemoCredentialStorePlugin",
    "version": "0.0"
  },
  "key": "2534221015734bb18aaf32",
  "meta": {
    "first": "/api/configuration/plugins/credentialstore/2534221015734bb18aaf32",
    "href": "/api/configuration/plugins/credentialstore/2534221015734bb18aaf32",
    "last": "/api/configuration/plugins/credentialstore/2534221015734bb18aaf32",
    "next": null,
    "parent": "/api/configuration/plugins/credentialstore",
    "previous": null,
    "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.