Configure the Advanced Server Access gateway

This topic explains how to configure an Advanced Server 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 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 Manage the Advanced Server 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 an Advanced Server Access gateway setup token.

Option Default value Description
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).

SetupTokenFile Linux: /var/lib/sft-gatewayd/setup.token

FreeBSD: /var/db/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 Advanced Server 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 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.

LDAP options

These options control how the gateway establishes secure connections with Lightweight Directory Access Protocol (LDAP) servers. These options must be configured for the gateway to work with AD-Joined. See Configure an Advanced Server Access gateway for AD-Joined.

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:

LDAP:
  StartTLS: ...

Option Default value Description
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.

Teams should ensure that valid certificates for each connected domain are stored on the gateway before they enable this option. If no valid certificates are found, the gateway rejects all connections.

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

You can use any path, but Okta recommends using /etc/sft/trusted-ldap-certs/.

For information on certificates, see Add a certificate to an Advanced Server Access gateway.

RDP options

These options control how the gateway manages Remote Desktop Protocol (RDP) sessions. Teams must configure these options to route RDP sessions through the gateway to servers enrolled with the server agent or discovered in an AD domain. These options must be configured for the gateway to work with AD-Joined. See Configure an Advanced Server Access gateway for AD-Joined.

You must explicitly allow RDP connections with the Enabled option and either the TrustedCAsDir or DangerouslyIgnoreServerCertificates option.

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 Active Directory server discovery.

You must indent these options within an RDP YAML dictionary using two spaces:

RDP:
  Enabled: ...

Option Default value Description
Enabled False

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 /etc/sft/trusted-rdp-certs/.

For information on certificates, see Add a certificate to an Advanced Server Access gateway.

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.

Session capture 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 generally /tmp, unless the $TMPDIR environment variable is specified.

The directories for the temporary and finalized session logs must be located 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 Advanced Server 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 is optional
    Region: US-EAST-1
    # You may specify Profile for shared credentials...
    Profile: AWS-PROFILE-NAME
    # ... or AccessKeyId, SecretKey, and SessionToken for static credentials...
    AccessKeyId: SECRET
    SecretKey: SECRET
    SessionToken: SECRET
    # ... or no credentials to use the default credentials chain

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"
    }

Related topics