Configure the Okta Privileged Access gateway

This topic explains how to configure a Okta Privileged Access gateway.

Command-line options

  • service: Runs the sft-gatewayd service
  • support: Collects local system information for Okta support
  • -h, --help: Displays help
  • -v, --version: Displays version
  • --syslog: Forces syslog logging

Configuration file

You can control Okta Privileged Access gateways by using a configuration file at /etc/sft/sft-gatewayd.yaml. After installing the gateway, an example configuration file is available at /etc/sft/sft-gatewayd.sample.yaml. If a configuration file hasn't been created or is unavailable, the gateway uses the following default values.

Restart the gateway before changes to the configuration file take effect. For details, see Manage the Okta Privileged Access gateway.

Setup Token options

These options control how you add a setup token to your gateway. You must enable one of the following options. For details on obtaining a setup token, see Create tokens and labels.

Option Default value Description
SetupToken unset Specifies a setup token created on the Okta Privileged Access platform.

Note: If you use this option, the setup token remains available in plain text. Okta recommends restricting read permissions to the configuration file (for example, 0600 on Linux).
SetupTokenFile Linux: /var/lib/sft-gatewayd/setup.token Specifies the path to a separate file containing the setup token. The default value is based on the operating system running the gateway.

This option is the recommended method.

If using this option, you must manually create the setup token file and add the setup token created on the Okta Privileged Access platform.

After the gateway is enrolled with a team, the gateway deletes the token file.

Note: If the SetupToken option is also configured, the gateway uses the token specified there.

Log options

Option Default value Description
LogLevel info Controls the verbosity of the logs. Okta recommends leaving this as info.

Valid values include:

  • error
  • warn
  • info
  • debug

Connection options

Option Default value Description
AccessAddress 1.1.1.1 Specifies the network address (IPv4, IPv6, or FQDN) that's used by clients to access the gateway. If no address is specified, the gateway uses the address indicated by the network interface or cloud provider metadata.
AccessPort 7234 Specifies the port clients can use to access the gateway.
ListenAddress 0.0.0.0 Specifies the network address (IPv4, IPv6, or FQDN) that's used by the gateway to listen for connections. By default, the gateway listens for connections on every available interface.
ListenPort 7234 Specifies a port used by the gateway to listen for connections.
TLSUseBundledCAs True Forces the gateway to use the bundled certificate store (instead of the OS certificate store) to secure HTTP requests with TLS. This also includes requests to the Okta Privileged Access cloud service.

Note: To use the OS certificate store, set this option to False.
RefuseConnections False Controls whether the gateway accepts SSH and RDP proxy traffic. If enabled, SSH and RDP connection requests aren't routed and the gateway won't listen for proxy traffic requests.
ForwardProxy unset Specifies the URL of an HTTP CONNECT proxy used for outbound network connectivity to Okta Privileged Access. Alternatively, you can set the proxy using the HTTPS_PROXY environment variable.

RDP options

These options control how the gateway manages RDP sessions.

You must explicitly allow RDP connections with Enabled: true and DangerouslyIgnoreServerCertificates options. Make sure to add two spaces for these options under RDP as it's a YAML dictionary.

Ubuntu 20.04, 22.04, RHEL 8, or RHEL 9 is required for RDP connections routed through a gateway.

Option Default value Description
Enabled False

Controls RDP functionality for the gateway. This option is disabled by default as RDP requires other configuration and must be set to True before any RDP connections are allowed.
DangerouslyIgnoreServerCertificates False Restricts the gateway from validating server certificates when connecting to an RDP host. This flag is dangerous in non-test environments, but may be required if the RDP host has any self-signed certificates.
MaximumActiveSessions 20 Controls the number of concurrent RDP sessions allowed by the gateway. After reaching this number of sessions, other users will receive an error and be unable to connect to the gateway. This is done exclusively for resource and performance reasons.
VerboseLogging True Controls the log level of RDP-internal logs. These messages are useful when diagnosing issues but might clutter logs.

Note: Set to False to label all internal RDP log messages as debug.

Session recording options

Option Default value Description
SessionLogFlushInterval 10s Specifies a size threshold for session capture logs. After reaching this threshold, logs for an active session are signed and flushed to disk. This option must include a time unit (ms, s, m, h).
SessionLogMaxBufferSize 262144 Specifies a size threshold for session capture logs. After reaching this threshold, logs for an active session are signed and flushed. This option is measured in bytes.
SessionLogTempStorageDirectory /tmp Specifies a temp directory to store SSH session logs before upload to the specified log destination.

The default depends on the operating system. On Linux, the default is /tmp, unless the $TMPDIR environment variable is specified.

The directories for the temporary and finalized session logs must be on the same device.
LogDestinations unset Specifies where to store finalized session logs. Teams can store logs locally or on AWS or GCS buckets. You can store session logs in multiple locations. If doing so, the logs are sent to the destination in the order specified in the configuration file. Session logs are never sent to Okta Privileged Access.

See the following default values and examples.

Example - Linux/BSD

LogDestinations:
- Type: file
LogDir: /var/log/sft/sessions

Gateways can't write to the /home, /root, or /run/user directories.

Example - AWS

LogDestinations:
- Type: s3
Bucket: BUCKET-NAME
Region: US-EAST-1
# Use of ec2 instance IAM Role credentials for s3 bucket access is recommended
# To use ec2 instance IAM Role credentials leave Profile, AccesKeyId, SecretKey, and SessionToken BLANK
# Specify Profile for shared credentials
Profile: AWS-PROFILE-NAME
# Specify AccessKeyId, SecretKey, and SessionToken for static credentials
AccessKeyId: SECRET
SecretKey: SECRET
SessionToken: SECRET

Example - Google Cloud

LogDestinations:
- Type: gcs
Bucket: BUCKET-NAME
# Supply one of CredentialsFile or CredentialsJSON (or none to use instance credentials)
CredentialsFile: /path/to/cred/file
CredentialsJSON: |
{
"SOME": "value",
"IN": "json"
}

LogFileNameFormats

SSHRecording: {{StartTime}}-{{.TeamName}}-{{Username}}

RDPRecording: {{StartTime}}-{{Protocol}}-{{.TeamName}}-{{ProjectName}}-{[.ServerName}}-{{.Username}}

System administrators can customize and configure the logFileNameFormats option to better understand and manage the session recording logs.

  • StartTime - The time when the session recording starts. Time conversion is done using the ISO 8601 standard format.

  • TeamName - The Okta Privileged Access team name of the user who trigger the connection session.

  • UserName - The name of the user who triggers the SSH or RDP session.

  • Protocol - The connection protocol; either SSH or RDP.

  • ProjectName - The name of the project, which the target SSH or RDP server belongs to.

  • ServerName - The hostname of the target server client connected to in the SSH or RDP session.

Related topics

Install the Okta Privileged Access gateway

Create tokens and labels

Requirements and limitations