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

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

LDAP:
StartTLS: ...

Warning: If StartTLS and UseLDAPS are set to False, then LDAP communications with Active Directory won't be encrypted. Okta recommends that you set StartTLS to True.

Option Default value Description
StartTLS True

Upgrades Active Directory/LDAP server communications to TLS. If disabled, communication with the server is not encrypted.

StartTLS is an extension to the LDAP protocol that uses the TLS protocol to encrypt communication. This option can't be enabled simultaneously with the UseLDAPS option.

UseLDAPS

False

Enables the use of the LDAPS protocol to encrypt communication. This option can't be enabled simultaneously with the StartTLS option.

LDAPSPort

636

If the UseLDAPS option is set to True, then this port value is used to make the LDAPS connection.
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.

Ubuntu 20.04, 22.04, RHEL 8, or RHEL 9 is required for AD-joined and RDP connections that are 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 additional configuration. Must be set to True before any RDP conections are allowed.
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 in AWS or GCS buckets. If you store session logs in multiple locations, the logs are sent to the destination in the order specified in the configuration file. Session logs are never sent to Advanced Server Access.

To ensure proper session logging with S3 storage, configure the gateway with the necessary permissions to write objects to the S3 buckets. There's no need for any other permissions.

See the following default values and examples.

Example - Linux/BSD
Copy 
LogDestinations:
- Type: file
  LogDir: /var/log/sft/sessions

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

Example - AWS
Copy 
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
Copy 
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 logFileNameFormats option to better understand and manage the session recording logs.

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

  • TeamName - The Advanced Server Access team name of the user who trigger the connection session.

  • UserName - The name of user who trigger 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