The available RDP channel types and their functionalities are described below.
Channel | Special options | Description |
---|---|---|
#drawing | Yes |
Drawing: Enables access to the server's graphical desktop (screen). This channel must be enabled for RDP to work. Channel-specific actions:
For example: "actions": { "audit": true, "content_policy": { "key": "433849548566ab327522e6" }, "four_eyes": false, "ids": false } |
cliprdr | None | Clipboard: Enable access to the server's clipboard: the clipboard of the remote desktop can be pasted into local applications (and vice-versa). Note that Safeguard for Privileged Sessions can audit the clipboard channel, but cannot search or display its contents. |
rdpdr | Yes |
Redirects: Enables access to every device redirections available in RDP, like file-sharing, printer sharing, device (for example CD-ROM) sharing, and so on. To enable only a specific type of redirection, use the specific channels instead (for example, rdpdr-serial for serial device redirection). Channel-specific actions:
Channel-specific access control rules:
|
rdpsnd | None |
Sound: Enable access to the sound device of the server. |
customs | Yes |
Custom: Applications can open custom channels to the clients connecting remotely to the server. Enabling the Custom channel allows the clients to access all of these custom channels. To permit only specific channels, list the unique names of the channels into the customs field. For example, to monitor RemoteApp connections, you need to configure custom channels. For more information, see "Configuring RemoteApps" in the Administration Guide. Channel-specific access control rules:
|
seamrdp | None | Seamless: Enable seamless channels that run a single application on the RDP server, instead of accessing the entire desktop. |
drdynvc | Yes |
Dynamic virtual channel: Enable the server to open channels back to the client dynamically. Enabling this channel allows access to all of such dynamic channels. To restrict which dynamic channels are permitted, list the unique names of the channels into the drdynvcs field. Channel-specific access control rules:
|
rdpdr-serial | Yes |
Serial redirect: Enables access to serial-port redirections. To restrict access to specific redirections, list the unique names of the channels in the devices field. Channel-specific access control rules:
|
rdpdr-parallel | Yes |
Parallel redirect: Enables access to parallel-port redirections. To restrict access to specific redirections, list the unique names of the channels in the devices field. Channel-specific access control rules:
|
rdpdr-printer | Yes |
Printer redirect: Enables access to printer-port redirections. To restrict access to specific redirections, list the unique names of the channels in the devices field. Channel-specific access control rules:
|
rdpdr-disk | Yes |
Disk redirect: Enables access to shared disk drives. To restrict access to specific redirections, list the unique names of the channels in the devices field, for example: "devices": [ "C:"
Channel-specific access control rules:
|
rdpdr-scard | Yes |
SCard redirect:Enables access to shared SCard devices. To restrict access to specific redirections, list the unique names of the channels in the devices field, for example: Channel-specific access control rules:
|
To use Credential Security Service Provider (CredSSP, also called Network Level Authentication or NLA) when Safeguard for Privileged Sessions is member of the domain. If you cannot or do not want to join Safeguard for Privileged Sessions to the domain, see "Network Level Authentication without domain membership" in the Administration Guide.
The target servers and Safeguard for Privileged Sessions must be in the same domain, or you must establish trust between the domains that contain the target servers and Safeguard for Privileged Sessions. For details on the type of trust required, see "Using Safeguard for Privileged Sessions across multiple domains" in the Administration Guide.
The Safeguard for Privileged Sessions 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 Safeguard for Privileged Sessions.
GET https://<IP-address-of-Safeguard for Privileged Sessions>/api/rdp/domain_membership
Header name | Description | Required | Values |
---|---|---|---|
session_id | Contains the authentication token of the user | Required |
The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Authenticate to the Safeguard for Privileged Sessions REST API. Note that this session ID refers to the connection between the REST client and the Safeguard for Privileged Sessions REST API. It is not related to the sessions that Safeguard for Privileged Sessions records (and which also have a session ID, but in a different format). |
The following command lists the configuration options for domain membership.
curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/rdp/domain_membership
The following is a sample response received when querying the domain membership configuration. For details of the meta object, see Introduction.
{ "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" } }
Element | Type | Description | |
---|---|---|---|
key | string | Top level element, contains the ID of the endpoint. | |
body | Top level element (string) | Contains the domain membership configuration. | |
domain | string |
The name of the domain. Must be used if enabled is set to true. | |
enabled | boolean | Set to true to configure domain membership. | |
realm | string |
Name of the realm. Must be used if enabled is set to true. |
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 }
To modify domain membership settings, you have to:
For details, see Open a transaction.
PUT the modified JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/rdp/domain_embership/ endpoint. You can find a detailed description of the available parameters listed in Configuring domain membership.
For details, see Commit a transaction.
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.
Code | Description | Notes |
---|---|---|
201 | Created | The new resource was successfully created. |
401 | Unauthenticated | The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
401 | AuthenticationFailure | Authenticating the user with the given credentials has failed. |
404 | NotFound | The requested object does not exist. |
List of options that affect all RDP connections.
GET https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/rdp/options
Header name | Description | Required | Values |
---|---|---|---|
session_id | Contains the authentication token of the user | Required |
The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Authenticate to the Safeguard for Privileged Sessions REST API. Note that this session ID refers to the connection between the REST client and the Safeguard for Privileged Sessions REST API. It is not related to the sessions that Safeguard for Privileged Sessions records (and which also have a session ID, but in a different format). |
The following command lists global RDP options.
curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/rdp/options
The following is a sample response received when listing global RDP options. For details of the meta object, see Introduction.
{ "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" } }
Element | Type | Description | ||
---|---|---|---|---|
key | Top level item | Contains the ID of the endpoint. | ||
body | Top level item | Contains the elements of the global RDP options. | ||
audit | Top level item | Contains settings for timestamping and cleanup. | ||
service | Top level item | Global setting to enable RDP connections, and specify the logging detail. | ||
enabled | boolean | Set to true to enable RDP connections. | ||
log_level | int | Defines the logging detail of RDP connections. |
Elements of audit | Type | Description | ||
---|---|---|---|---|
cleanup | Top level item | Global retention settings for RDP connection metadata. To configure retention time for a specific connection policy, use the archive_cleanup_policy element at the endpoint of the policy instead. | ||
channel_database_cleanup_days | int | Global retention time for the metadata of RDP connections, in days. Must exceed the retention time of the archiving policy (or policies) used for RDP connections, and the connection-specific database cleanup times (if configured). | ||
enabled | boolean | To enable the global cleanup of RDP connection metadata, set this element to true. | ||
timestamping | Top level item | Global timestamping settings for RDP connections. | ||
selection | string |
Configures local or remote timestamping.
| ||
server_url | string |
Required for remote timestamping. The URL of the timestamping server. Note that HTTPS and password-protected connections are not supported. | ||
oid | Top level item | The Object Identifier of the policy used for timestamping. | ||
enabled | boolean |
Required for remote timestamping. Set to true to configure the Object Identifier of the timestamping policy on the timestamping remote server. | ||
policy_oid | string |
Required if the oid is enabled. The Object Identifier of the timestamping policy on the remote timestamping server. | ||
signing_interval | int | Time interval for timestamping open connections, in seconds. |
Set Safeguard for Privileged Sessions 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 } }
To modify global RDP settings, you have to:
For details, see Open a transaction.
PUT the modified JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/rdp/options endpoint. You can find a detailed description of the available parameters listed in Global RDP options. The elements of the audit item are described in Global RDP options.
For details, see Commit a transaction.
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.
Code | Description | Notes |
---|---|---|
201 | Created | The new resource was successfully created. |
401 | Unauthenticated | The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
401 | AuthenticationFailure | Authenticating the user with the given credentials has failed. |
404 | NotFound | The requested object does not exist. |
RDP settings policies define protocol-level settings (timeout, display, protocol version, and authentication). You can create multiple policies, and choose the appropriate one for each RDP connection.
GET https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/rdp/settings_policies
Header name | Description | Required | Values |
---|---|---|---|
session_id | Contains the authentication token of the user | Required |
The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Authenticate to the Safeguard for Privileged Sessions REST API. Note that this session ID refers to the connection between the REST client and the Safeguard for Privileged Sessions REST API. It is not related to the sessions that Safeguard for Privileged Sessions records (and which also have a session ID, but in a different format). |
The following command lists RDP settings policies.
curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/rdp/settings_policies
The following command retrieves the properties of a specific policy.
curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/rdp/settings_policies/<policy-id>
The following is a sample response received when listing RDP settings policies. For details of the meta object, see Message format.
{ "items": [ { "key": "-301", "meta": { "href": "/api/configuration/rdp/settings_policies/-301" } }, { "key": "-303", "meta": { "href": "/api/configuration/rdp/settings_policies/-303" } }, { "key": "13298899495727c51f725cf", "meta": { "href": "/api/configuration/rdp/settings_policies/13298899495727c51f725cf" } } ], "meta": { "first": "/api/configuration/rdp/channel_policies", "href": "/api/configuration/rdp/settings_policies", "last": "/api/configuration/rdp/settings_policies", "next": null, "parent": "/api/configuration/rdp", "previous": "/api/configuration/rdp/options", "transaction": "/api/transaction" } }
When retrieving the endpoint of a specific policy, the response is the following.
{ "body": { "autologon_domain_suffix": "-AUTO", "name": "API_test", "permit_unreliable_usernames": true, "preconnect_channel_check": true, "protocol_features": { "nla": { "enabled": true, "require_domain_membership": true }, "rdp4_auth_enabled": true, "rdp4_enabled": true, "rdp5_enabled": true }, "screen": { "maximum_bpp": 32, "maximum_height": 2000, "maximum_width": 2000 }, "timeout": 600, "userauth_banner": "Click 'OK' to log in." }, "key": "13298899495727c51f725cf", "meta": { "first": "/api/configuration/rdp/settings_policies/-301", "href": "/api/configuration/rdp/settings_policies/13298899495727c51f725cf", "last": "/api/configuration/rdp/settings_policies/13298899495727c51f725cf", "next": null, "parent": "/api/configuration/rdp/settings_policies", "previous": "/api/configuration/rdp/settings_policies/-303", "transaction": "/api/transaction" } }
Element | Type | Description | |
---|---|---|---|
key | string | Top level element, contains the ID of the policy. | |
body | Top level element (string) | The elements of the RDP settings policy. | |
autologon_domain_suffix | string | Enter the suffix that the client will append to the domain when using autologon in conjunction with Network Level Authentication (CredSSP). | |
name | string | Name of the RDP settings policy. Cannot contain whitespace. | |
permit_unreliable_usernames | boolean | Set to true to automatically terminate RDP connections if Safeguard for Privileged Sessions cannot reliably extract the username. | |
preconnect_channel_check | boolean |
Before establishing the server-side connection, Safeguard for Privileged Sessions can evaluate the connection and channel policies to determine if the connection might be permitted at all. The server-side connection is established only if the evaluated policies permit the client to access the server. To enable this function, set the parameter to true. | |
protocol_features | Top level item | Settings for RDP protocol versions, and Network Layer Authentication. | |
screen | Top level item | Display size and depth settings. | |
timeout | int | Connection timeout, in seconds. Note that the Safeguard for Privileged Sessions web UI displays the same value in milliseconds. | |
|
userauth_banner |
string |
You can display a banner message to the clients before authentication. |
Elements of protocol | Type | Description | |
---|---|---|---|
nla | Top level item | Settings for Network Level Authentication. | |
enabled | boolean |
Set to true to enable Network Level Authentication. If set to true, the require_domain_membership element is required in the JSON. | |
require_domain_membership | boolean |
Set to true to require domain membership. Must be in the JSON if NLA is enabled. | |
rdp4_auth_enabled | boolean | Set to true to enable RDP4 authentication within the RDP5 protocol. This might be needed for compatibility reasons with certain client applications. | |
rdp4_enabled | boolean | Set to true to enable the version 4 of the Remote Desktop Protocol. | |
rdp5_enabled | boolean |
Set to true to enable the version 5 of the Remote Desktop Protocol. To also configure SSL-encryption for RDP5, enable the nla element, or configure a Signing CA in your connection policies. |
Elements of screen | Type | Description |
---|---|---|
maximum_bpp | int | The maximum allowed color depth of the remote desktop, in bits. The following values are valid: 8, 15, 16, 24. |
maximum_height | int | The maximum allowed height of the remote desktop, in pixels. |
maximum_width | int | The maximum allowed width of the remote desktop, in pixels. |
Turn off NLA.
{ "autologon_domain_suffix": "-AUTO", "name": "API_test", "permit_unreliable_usernames": true, "preconnect_channel_check": true, "protocol_features": { "nla": { "enabled": false }, "rdp4_auth_enabled": true, "rdp4_enabled": true, "rdp5_enabled": true }, "screen": { "maximum_bpp": 24, "maximum_height": 2000, "maximum_width": 2000 }, "timeout": 600 }
Configure NLA.
{ "autologon_domain_suffix": "-AUTO", "name": "API_test", "permit_unreliable_usernames": true, "preconnect_channel_check": true, "protocol_features": { "nla": { "enabled": true, "require_domain_membership": false }, "rdp4_auth_enabled": true, "rdp4_enabled": true, "rdp5_enabled": true }, "screen": { "maximum_bpp": 24, "maximum_height": 2000, "maximum_width": 2000 }, "timeout": 600 }
To add a settings policy, you have to:
For details, see Open a transaction.
POST the JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/rdp/settings_policies/ endpoint. You can find a detailed description of the available parameters listed in the table of RDP settings policy parameters.
If the POST request is successful, the response includes the key of the new policy. For example:
{ "key": "9c3a0419-53e6-43a4-902c-2b3b0ce7a7a7", "meta": { "href": "/api/configuration/rdp/settings_policies/9c3a0419-53e6-43a4-902c-2b3b0ce7a7a7", "parent": "/api/configuration/rdp/settings_policies", "transaction": "/api/transaction" } }
For details, see Commit a transaction.
To modify a settings policy, you have to:
For details, see Open a transaction.
PUT the modified JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/rdp/settings_policies/<key-of-the-object> endpoint. You can find a detailed description of the available parameters listed in the table of RDP settings policy parameters.
For details, see Commit a transaction.
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.
Code | Description | Notes |
---|---|---|
201 | Created | The new resource was successfully created. |
400 |
Bad Request "message": "RDP Settings Policy 'API_test': Safeguard for Privileged Sessions must be a domain member to allow enabling Network Level Authentication." |
You have set require_domain_membership to true, but Safeguard for Privileged Sessions is not the member of a domain. |
401 | Unauthenticated | The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
401 | AuthenticationFailure | Authenticating the user with the given credentials has failed. |
404 | NotFound | The requested object does not exist. |
© 2023 One Identity LLC. ALL RIGHTS RESERVED. Feedback Terms of Use Privacy