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

Health and maintenance

Topics:

Monitor appliance health status

To monitor the health status of an appliance, complete the following steps.

1. Query the /api/health-status endpoint.

   curl --cookie cookies https://<IP-address-of-SPS>/api/health-status

   The following is a sample response received.

   For details of the meta object, see Message format.

   For details of the other objects, see tables Cluster status details and "issues" object details.

   {
       "health_status": {
           "memory": 62.5,
           "disk": 1.9,
           "swap": 0,
           "load1": 0.53,
           "load5": 0.68,
           "load15": 0.37,
           "sessions": {
               "ssh": 3,
               "rdp": 4
           },
           "total_sessions": 7
       }
   }

   Elements		Type	Description
   health_status		null or object	The health status of a node. If the node is down, the value is null. Otherwise, the health-related data is listed.
   	memory	floating point integer (percent)	Memory use
   	disk	floating point integer (percent)	Hard disk use
   	swap	floating point integer (percent)	Swap use
   	load1	floating point integer	The average system load during the last one minute. The values mean the following: < 1: low system load 1-5: high system load > 5: extremely high system load
   	load5	floating point integer	The average system load during the last five-minute period. The values mean the following: < 1: low system load 1-5: high system load > 5: extremely high system load
   	load15	floating point integer	The average system load during the last fifteen-minute period. The values mean the following: < 1: low system load 1-5: high system load > 5: extremely high system load
   	sessions	string	The protocol type and the number of ongoing sessions. For example: "sessions": { "ssh": 3, "rdp": 4 },
   	total_sessions	integer (number of)	The total number of ongoing sessions.

Advanced authentication and authorization

Topics:

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