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

RDP connection policies

Connection policies determine if a server can be accessed from a particular client. Connection policies reference other resources (policies, usergroups, keys) that must be configured and available before creating a connection policy.

URL

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

Cookies

Sample request

The following command lists RDP connection policies.

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

The following command retrieves the properties of a specific policy.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/rdp/connections/<connection-key>

Response

The following is a sample response received when listing RDP connection policies.

For details of the meta object, see Message format.

{
    "items": [
        {
            "key": "12932832285a830b4d2f5d7",
            "meta": {
                "href": "/api/configuration/rdp/connections/12932832285a830b4d2f5d7"
            }
        }
    ],
    "meta": {
        "first": "/api/configuration/rdp/channel_policies",
        "href": "/api/configuration/rdp/connections",
        "last": "/api/configuration/rdp/settings_policies",
        "next": "/api/configuration/rdp/domain_membership",
        "parent": "/api/configuration/rdp",
        "previous": "/api/configuration/rdp/channel_policies",
        "remaining_seconds": 600,
        "transaction": "/api/transaction"
    }
}

When retrieving the endpoint of a specific RDP connection policy, the response is the following.

{
    "body": {
        "access_control": [
          {
            "authorizer": "reporting",
            "permission": "audit_and_authorize",
            "require_different_ip": true,
            "require_different_username": true,
            "subject": {
              "selection": "everybody"
            }
          }
        ],
        "active": true,
        "channel_database_cleanup": {
          "days": 550,
          "enabled": true
        },
        "indexing": {
            "enabled": true,
            "policy": {
                "key": "-50000",
                "meta": {
                    "href": "/api/configuration/policies/indexing/-50000"
                }
            },
            "priority": 3
        },
        "log_audit_trail_downloads": true,
        "name": "rdp_demo",
        "network": {
            "clients": [
                "0.0.0.0/0"
            ],
            "ports": [
                3389
            ],
            "targets": [
                "10.30.255.28/24"
            ]
        },
        "policies": {
            "aa_plugin": null,
            "analytics_policy": null,
            "archive_cleanup_policy": {
              "key": "1854671967571b9063c4c82",
              "meta": {
                "href": "/api/configuration/policies/archive_cleanup_policies/1854671967571b9063c4c82"
              }
            },
            "audit_policy": {
                "key": "78101850949e47437dd91d",
                "meta": {
                    "href": "/api/configuration/policies/audit_policies/78101850949e47437dd91d"
                }
            },
            "backup_policy": {
                "key": "512524636571b903540804",
                "meta": {
                    "href": "/api/configuration/policies/backup_policies/512524636571b903540804"
                }
            },
            "channel_policy": {
                "key": "-20200",
                "meta": {
                    "href": "/api/configuration/rdp/channel_policies/-20200"
                }
            },
            "credential_store": {
                "key": "505008562571b936560254",
                "meta": {
                  "href": "/api/configuration/policies/credentialstores/505008562571b936560254"
                }
            },
            "ldap_server": {
                "key": "250588254571b931066482",
                "meta": {
                  "href": "/api/configuration/policies/ldap_servers/250588254571b931066482"
                }
            },
            "settings": {
                "key": "-301",
                "meta": {
                    "href": "/api/configuration/rdp/settings_policies/-301"
                }
            },
            "usermapping_policy": null
        },
        "rate_limit": {
            "enabled": false
        },
        "remote_desktop_gateway": {
            "enabled": false
        },
        "server_address": {
            "address": "10.30.255.70",
            "port": 3389,
            "selection": "fix"
        },
        "server_certificate_check": {
            "enabled": false
        },
        "source_address": {
            "selection": "box_address"
        },
        "transport_security": {
            "certificate": {
                "selection": "self_signed"
            },
            "legacy_fallback": false,
            "selection": "tls"
        },
        "web_gateway_authentication": {
            "enabled": false
        }
    },
    "key": "12932832285a830b4d2f5d7",
    "meta": {
        "first": "/api/configuration/rdp/connections/12932832285a830b4d2f5d7",
        "href": "/api/configuration/rdp/connections/12932832285a830b4d2f5d7",
        "last": "/api/configuration/rdp/connections/12932832285a830b4d2f5d7",
        "next": null,
        "parent": "/api/configuration/rdp/connections",
        "previous": null,
        "remaining_seconds": 600,
        "transaction": "/api/transaction"
    }
}

"remote_desktop_gateway": {
    "enabled": false
},

"server_certificate_check": {
    "enabled": false
},

"server_certificate_check": {
    "enabled": true,
    "trusted_ca": "9106862955a844051d7bf6"
},

"common_name": "examplecn"

"signing_ca": "1904188625a843f11d30a5"

Examples

For practical purposes, the following examples show only the relevant parts of a connection policy JSON object. To modify or add a connection policy, always submit the full JSON object.

Access control list: configuring the "security" usergroup to only audit connections made by the "root_only" usergroup.

"access_control": [
      {
    "authorizer": "security",
    "permission": "audit",
    "require_different_ip": true,
    "require_different_username": true,
    "subject": {
      "group": "root_only",
      "selection": "only"
    }
  }

Access control list: configuring the "security" usergroup to only audit connections made by the "root_only" usergroup.

"access_control": [
      {
    "authorizer": "security",
    "permission": "audit",
    "require_different_ip": true,
    "require_different_username": true,
    "subject": {
      "group": "root_only",
      "selection": "only"
    }
  }

Target server: use the address specified by the client.

"server_address": {
  "selection": "original"
}

Target server: use a fix address.

"server_address": {
  "address": "<fix-IP>",
  "port": 22,
  "selection": "fix"
}

Target server: configure inband destination selection, where the client can specify the target address in the username. The target can be either an IP range, or a domain.

"server_address": {
  "dns_server": "<ip-of-dns-server>",
  "dns_suffixes": null,
  "domains": [
    {
      "domain": {
        "selection": "address",
        "value": "<IP-range>"
      },
      "port": 22
    },
    {
      "domain": {
        "selection": "domain",
        "value": "*.example"
      },
      "port": 22
    }
  ],
  "selection": "inband"
}

Source address: use the same fix IP when connecting to the remote server.

"source_address": {
  "address": "<ip-address>",
  "selection": "fix"
}

Web gateway authentication: require the admin usergroup to perform an additional gateway authentication on the SPS web interface. They must authenticate from the same host which initiated the connection.

"web_gateway_authentication": {
  "enabled": true,
  "groups": [
    "admin"
  ],
  "require_same_ip": true
}

Policies: configure only the required policies.

"policies": {
  "aa_plugin": null,
  "analytics_policy": null,
  "archive_cleanup_policy": null,
  "audit_policy": "<key-of-audit-policy>",
  "backup_policy": null,
  "channel_policy": "<key-of-channel-policy>",
  "credential_store": null,
  "ldap_server": null,
  "settings": "<key-of-settings-policy>",
  "usermapping_policy": null
}

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 connection policy

To add an RDP connection policy, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Create the JSON object for the new RDP connection policy.

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

   {
     "key": "a99be49b-b0a2-4cf9-b70d-fea1f9ea188f",
     "meta": {
       "href": "/api/configuration/rdp/connections/a99be49b-b0a2-4cf9-b70d-fea1f9ea188f",
       "parent": "/api/configuration/rdp/connections",
       "transaction": "/api/transaction"
     }
   }

3. Commit your changes.

   For details, see Commit a transaction.

Modify an RDP connection policy

To modify an RDP connection policy, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Modify the JSON object of the connection policy.

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

RDP channels

The available RDP channel types and their functionalities are described below.

"actions": {
  "audit": true,
  "content_policy": {
    "key": "433849548566ab327522e6"
  },
  "four_eyes": false,
  "ids": false
}

"devices": [
  "C:"
                        
Channel-specific actions:
log_transfer_to_db (true|false): Make the list of file operations available in the Search > File operations column of the SPS web interface
log_transfer_to_syslog (true|false): Send the file operations into the system log
Channel-specific access control rules:
devices (list): To permit only specific redirections, list the unique name of the redirection in this field. Leave it empty to permit access to every redirection available.

Configuring domain membership

To use Credential Security Service Provider (CredSSP, also called Network Level Authentication or NLA) when One Identity Safeguard for Privileged Sessions (SPS) is member of the domain. If you cannot or do not want to join SPS to the domain, see "Network Level Authentication without domain membership" in the Administration Guide.

The SPS configuration API allows you to view, disable, or modify the domain membership configuration. To join the configured domain, you have to use the web interface of SPS.

URL

GET https://<IP-address-of-SPS>/api/rdp/domain_membership

Cookies

Sample request

The following command lists the configuration options for domain membership.

curl --cookie cookies https://<IP-address-of-SPS>/api/rdp/domain_membership

Response

The following is a sample response received when querying the domain membership configuration.

For details of the meta object, see Message format.

{
  "body": {
    "domain": "testdomain",
    "enabled": true,
    "realm": "testdomain.api.test"
  },
  "key": "domain_membership",
  "meta": {
    "first": "/api/configuration/rdp/channel_policies",
    "href": "/api/configuration/rdp/domain_membership",
    "last": "/api/configuration/rdp/settings_policies",
    "next": "/api/configuration/rdp/options",
    "parent": "/api/configuration/rdp",
    "previous": "/api/configuration/rdp/channel_policies",
    "transaction": "/api/transaction"
  }
}

Examples:

Configure domain membership for the "test" domain on the "config.api" realm:

{
  "domain": "test",
  "enabled": true,
  "realm": "test.config.api"
}

Disable domain membership.

{
  "enabled": false
}

Modify domain membership settings

To modify domain membership settings, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Modify the JSON object of the domain membership configuration.

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

3. Commit your changes.

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

Global RDP options

List of options that affect all RDP connections.

URL

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

Cookies

Sample request

The following command lists global RDP options.

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

Response

The following is a sample response received when listing global RDP options.

For details of the meta object, see Message format.

{
  "body": {
    "audit": {
      "cleanup": {
        "enabled": false
      },
      "timestamping": {
        "selection": "local",
        "signing_interval": 30
      }
    },
    "service": {
      "enabled": true,
      "log_level": 4
    }
  },
  "key": "options",
  "meta": {
    "first": "/api/configuration/rdp/channel_policies",
    "href": "/api/configuration/rdp/options",
    "last": "/api/configuration/rdp/settings_policies",
    "next": "/api/configuration/rdp/settings_policies",
    "parent": "/api/configuration/rdp",
    "previous": "/api/configuration/rdp/domain_membership",
    "transaction": "/api/transaction"
  }
}

Examples:

Set SPS as the timestamping server:

{
  "audit": {
    "cleanup": {
      "enabled": false
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Enable cleanup, and set it to occur every 10 days:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, without specifying a timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": false
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, and specify the 1.2.3 timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": true,
          "policy_oid": "1.2.3"
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Modify global RDP settings

To modify global RDP settings, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Modify the JSON object of the global RDP settings endpoint.

   PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/rdp/options endpoint. You can find a detailed description of the available parameters listed in Element . The elements of the audit item are described in Elements of audit.

3. Commit your changes.

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