One Identity Safeguard for Privileged Sessions 7.0.4 LTS - REST API Reference Guide

Collection of access policies. Access policies define who can authorize and audit a connection.

Retention time, in days. Must not exceed the retention time of the archive_cleanup_policy, and the retention time configured in the global settings of the protocol.

The global settings of the SSH protocol are available at the api/configuration/ssh/options endpoint.

References the identifier of the indexing policy. You can configure indexing policies at the /api/configuration/policies/indexing/ endpoint.

To modify or add an indexing policy, use the value of the returned key as the value of the policy element, and remove any child elements (including the key).

Specifies the indexing priority for the connection. Possible values are:

• 5

  Very low priority.

• 4

  Low priority.

• 3

  Normal (default) priority.

• 2

  High priority.

• 1

  Very high priority.

• 0

  Near real-time priority.

Set to true to log audit trail downloads.

Specifies the verbosity level of sessions handled by this connection policy. The log level of other connection policies is not affected. If disabled, the log level set at the /api/configuration/<protocol>/options endpoint is used.

• To use the default log level, disable this option:

  "override_log_level": {
      "enabled": false
  },

• To use a custom log level for the connection policy, enable this option and set the log level to use:

  "override_log_level": {
      "enabled": true,
      "log_level": 5
  },

References the identifier of the AA plug-in. You can configure AA plug-ins at the /api/configuration/plugins/aa/ endpoint.

To modify or add an AA plug-in, use the value of the returned key as the value of the aa_plugin element, and remove any child elements (including the key).

References the identifier of the analytics policy. You can configure analytics policies at the /api/configuration/analytics/ endpoint.

To add or modify an analytics policy, use the value of the returned key as the value of the analytics element, and remove any child elements (including the key).

References the identifier of the archive/cleanup policy. You can configure archive and cleanup policies at the /api/configuration/policies/archive_cleanup_policies/ endpoint.

To modify or add an archive/cleanup policy, use the value of the returned key as the value of the archive_cleanup_policy element, and remove any child elements (including the key).

Cannot be null.

References the identifier of the audit policy. You can configure audit policies at the /api/configuration/policies/audit_policies/ endpoint.

To modify or add an audit policy, use the value of the returned key as the value of the audit_policy element, and remove any child elements (including the key).

References the identifier of the backup policy. You can configure backup policies at the /api/configuration/policies/backup_policies/ endpoint.

To modify or add a backup policy, use the value of the returned key as the value of the backup_policy element, and remove any child elements (including the key).

References the identifier of the channel policy. The value of this option cannot be null.

To modify or add a channel policy, use the value of the returned key as the value of the channel_policy element, and remove any child elements (including the key).

You can configure RDP channel policies at the /api/configuration/rdp/channel_policies/ endpoint.

References the identifier of the credential store.

You can configure credential stores at the /api/configuration/policies/credentialstores/ endpoint.

To modify or add a credential store, use the value of the returned key as the value of the credential_store element, and remove any child elements (including the key).

References the identifier of the LDAP server. You can configure LDAP servers at the /api/configuration/policies/ldap_servers/ endpoint.

To modify or add an LDAP server, use the value of the returned key as the value of the ldap_server element, and remove any child elements (including the key).

References the identifier of the settings policy. The value of this option cannot be null.

To modify or add a settings policy for this protocol, use the value of the returned key as the value of the settings element, and remove any child elements (including the key).

You can configure RDP settings policies at the /api/configuration/ssh/settings_policies/ endpoint.

References the identifier of a Usermapping Policy. You can configure Usermapping Policies at the /api/configuration/policies/usermapping_policies/ endpoint.

To modify or add a Usermapping Policy, use the value of the returned key as the value of the usermapping_policies element, and remove any child elements (including the key).

Configure SPS to act as a Remote Desktop Gateway. Otherwise, simply disable this option:

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

Configures Source Network Address Translation. Possible values are:

• box_address

  Default. Uses the network address of the logical interface of SPS.

• original

  Uses the IP address of the client, as seen by SPS.

• fix

  Uses a fixed address when connecting to the remote server.

  Must be used with the address element.

Must be used if the value of the selection element is set to fix.

The IP address to use as the source address in server-side connections.

Configures the encryption used in the sessions.

Selects the certificate to show to the peers. You have the following options:

• Use a self-signed certificate:

  Select this option if you want to enable TLS-encryption, but you do not have a certificate that is generated by an external CA, or a signing CA.

  "certificate": {
          "selection": "self_signed"
      }

• Use the same certificate for each client:

  Select this option if you want to use the same certificate for every peer. Note that you must reference a certificate that includes its private key that you have already uploaded to SPS. For details, see Certificates stored on SPS.

  "certificate": {
      "selection": "fix",
      "x509_identity": "893b7eb7-8c6f-403a-ba3a-1d09dc4b4c7a"
  }

• Generate a certificate for each client:

  Select this option if you want to generate a certificate for each client. Note that you must reference a Signing CA that you have already configured on SPS. For details, see Signing CA policies.

  "certificate": {
      "selection": "generate",
      "signing_ca": "1904188625a843f11d30a5"
  },

By default, SPS accepts any certificate shown by the server.

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

To verify the certificate of the destination server, configure and reference a Trusted CA list.

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

Set to true to permit the clients to disable TLS encryption and use only the Legacy RDP Security Layer (also known as: Standard RDP Security). You might want to do this if you are experiencing compatibility issues. For example, when you attempt to connect to a very old Windows machine (for example, Windows Server 2003 or older).

Configures the encryption used in the sessions.

• legacy: Disables TLS encryption for RDP connections completely, and uses only the Legacy RDP Security Layer (also known as: Standard RDP Security). You might want to do this if you are experiencing compatibility issues. For example, when you attempt to connect to a very old Windows machine (for example, Windows Server 2003 or older).

  Caution: Security Hazard! Selecting this option can significantly reduce the strength of the encryption used!

  "transport_security": {
      "selection": "legacy"
  },

• tls: Enables TLS-encryption. Note that you must also set the certificate, server_certificate_check, and legacy_fallback options.

  "transport_security": {
      "certificate": {
          "selection": "self_signed"
      },
      "server_certificate_check": {
          "enabled": false
      },
      "legacy_fallback": false,
      "selection": "tls"
  }

By default, any user can perform gateway authentication for the connections. You can restrict authentication to members of specific usergroups. Define the usergroups at the /api/configuration/aaa/local_database/groups/ endpoint, and list the name of each group here.

Set to true and configure the other options as needed for your environment to use SPS as a Remote Desktop Gateway. For details and prerequisites, see "Using One Identity Safeguard for Privileged Sessions (SPS) as a Remote Desktop Gateway" in the Administration Guide.

To act as a Remote Desktop Gateway, SPS needs to display a certificate to the clients.

• To automatically create new certificates on SPS for every client, set "selection": "generate", and reference the Certificate Authority (CA) to sign the generated certificates. For example:

  "certificate": {
      "selection": "generate",
      "value": {
          "signing_ca": "53449998258a4ceba80fdc"
          },
          "common_name": "examplecn"
      }

  For details on uploading certificates, see Certificates stored on SPS.

• To always display the same certificate, set "selection": "fix", and reference an X.509 certificate and the matching private key. For example:

  "certificate": {
          "selection": "fix",
          "value": "1904188625a843f11d30a5"
      },

  For details on creating a signing CA, see Signing CA policies.

Determines if SPS displays the same certificate to every client (fix), or generates a separate certificate (generate) for every client.

Contains the options and parameters related to the option set in selection.

• If selection is set to generate, this is a JSON object.

• If selection is set to fix, this is a string containing the reference ID of the certificate that SPS displays to the clients.

Available only if selection is set to generate. You can specify the Common Name of the generated certificates in this parameter. For example:

"common_name": "examplecn"

If set to null, the Common Name of the certificates will be SPS-hostname.domainname

Available only if selection is set to generate. Contains the reference key of the signing CA used to sign the certificates that SPS shows to the clients. For example:

"signing_ca": "1904188625a843f11d30a5"

If set to null, the Common Name of the certificates will be SPS-hostname.domainname

Determines how SPS authenticates the clients: either using Active Directory (SPS must be member of a domain), or using a Local User Database.

Determines how SPS authenticates the clients:

• using Active Directory (SPS must be member of a domain)

  "local_authentication": {
      "selection": "local_user_database",
      "value": {
          "domain": "example",
          "local_user_database": "15646962145a843f758501d"
          }
      }

• using a Local User Database.

  "local_authentication": {
      "selection": "active_directory",
      "value": null
  }

Set to null if selection is set to active_directory.

If selection is set to local_user_database, value contains a JSON object with the domain and local_user_database keys.

Available only if selection is set to local_user_database.

Configures a DNS server that is used to reverse-resolve the hostname if the Channel Policy contains the address of the target as a hostname instead of an IP address. By default, this is disabled and SPS uses the DNS server set in the /api/configuration/network/dns endpoint.

• To use the default DNS, disable this option:

  "server_address": {
      "custom_dns": {
          "enabled": false
      },
      ...
  },

• To use a custom DNS, enable this option and set the IP address of the domain name server to use:

  "server_address": {
      "custom_dns": {
          "enabled": true,
          "server": "192.168.1.1"
      },
      ...
  },

Configures the address where the clients connect to. Possible values are:

• original

  Connect to the same address specified by the client.

• nat

  Perform a network address translation on the target address.

  Must be used with the network element.

• fix

  Must be used with the address and port elements.

• inband

  Extract the address of the server from the username.

  Must be used with the domains element.

  Optional elements: exception_domains, dns_server, and dns_suffixes.

Must be used if selection is set to nat.

The target address in IP/prefix format. Example: "10.20.30.40/24".

Must be used if selection is set to fix.

The IP address of the target server.

Must be used if selection is set to fix.

The port of the target server.

Must be used if selection is set to inband.

Specifies if the target address range is provided as a domain or as an IP range. Possible values are:

• address

  The value of the target address is an IP range.

• domain

  The value of the target address is a domain.

The address range of the target server(s).

Use the selection element to specify if the address is an IP range, or a domain.

Can only be used if selection is set to inband.

Lists the address ranges that are excluded from the connection policy.

Specifies if the excluded address(es) are provided as a domain or as an IP range. Possible values are:

• address

  The value of the excluded address is an IP range.

• domain

  The value of the excluded address is a domain.

The excluded address(es).

Use the selection element to specify if the address is an IP range, or a domain.

Can only be used if selection is set to inband.

IP address or the hostname of the domain name server used to resolve the address of the target server.

Drawing: Enables access to the server's graphical desktop (screen). This channel must be enabled for RDP to work.

Channel-specific actions:

• content_policy reference: The ID of the Content policy to apply to the connection.

For example:

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

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:

• 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.

Sound: Enable access to the sound device of the server.

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:

• customs (list): To permit only specific custom channels, list the unique name of the channels in this field. Leave it empty to permit access to every custom channel available.

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:

• drdynvcs (list): To restrict which dynamic channels are permitted, list the unique names of the channels in this field. Leave it empty to permit access to every dynamic channel available.

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:

• 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.

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:

• 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.

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:

• 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.

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 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.