Configure an Advanced Server Access gateway
This topic explains how to configure an Advanced Server Access gateway.
- Command line options
- Configuration file
- Related topics
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
You can control Advanced Server Access gateways through the use of a configuration file located 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.
You must restart the gateway before changes to the configuration file take effect. For details, see Restart an Advanced Server Access gateway
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 an Advanced Server Access gateway setup token.
|SetupToken||unset||Specifies a setup token created on the Advanced Server 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).
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 Advanced Server Access platform.
After the gateway is enrolled with a team, the gateway deletes the token file.
Note: If the
|LogLevel||info||Controls the verbosity of the logs. Okta recommends leaving this as
Valid values include:
|AccessAddress||18.104.22.168||Specifies the network address (IPv4 or IPv6) 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 or IPv6) 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 Advanced Server 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 Advanced Server Access. Alternatively, you can set the proxy using the HTTPS_PROXY environment variable.|
These options control how the gateway establishes secure connections with LDAP servers (usually Active Directory). By default, the gateway starts TLS, but doesn’t perform any certificate validation. The gateway only supports StartTLS for LDAP communication; gateways do not support LDAPS.
You must indent these options within an LDAP YAML dictionary using two spaces:
|StartTLS||True||Upgrades Active Directory/LDAP server communications to TLS. If disabled, communication with the server is not encrypted.|
|ValidateCertificates||False||Performs validation on certificates received from the AD/LDAP server. If disabled, LDAP server communications may be vulnerable to MITM attacks.
If enabled, the gateway looks for certificates at the path specified by
|TrustedCAsDir||unset||Specifies the path to a directory containing public certificates of a
Certificate Authority (usually managed within Active Directory and distributed
via Group Policy). The directory and certificates must be readable by the
sft-gatewayd user and the certificates must be PEM encoded. Subdirectories are
You can use any path, but Okta recommends using
These options control how the gateway manages RDP sessions. Teams can use these options to route RDP sessions through a gateway to servers enrolled with the server agent or discovered in an AD domain. You must explicitly allow RDP connections with the
Enabled option and either the
If a team is using the AD-Joined feature, the gateway can still discover Active Directory servers even if RDP support isn't enabled. See Server discovery.
You must indent these options within an RDP YAML dictionary using two spaces:
Controls RDP functionality for the gateway. This option is disabled by default as RDP requires additional configuration. Must be set to True before any RDP conections are allowed.
Teams can only route RDP connections through gateways running Ubuntu 20.04.
|TrustedCAsDir||unset||Specifies the path to a directory containing public certificates signed by a Certificate Authority (usually managed within Active Directory and distributed via Group Policy) The directory and certificates must be readable by the sft-gatewayd user and the certificates must be PEM encoded. Subdirectories are not checked.
You can use any path, but Okta recommends using
|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, additional 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.
|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 generally /tmp, unless the $TMPDIR environment variable is specified.
|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 Advanced Server Access.
See the following default values and examples.
Example - Linux/BSD
Gateways can't write to the
Example - AWS
Example - Google Cloud