Configure the Okta Privileged Access server agent

This topic explains how to configure the Okta Privileged Access server agent.

Command-line options

  • --conf: Provides an alternative configuration file path.
  • --debug-device-info: Prints detected device information to stderr and then exits.
  • -h, --help: Displays help.
  • -v, --version: Displays version.
  • --syslog: Forces syslog logging.

Configuration file

You can control the Okta Privileged Access server agent by manually creating a configuration file. The location of the configuration file depends on the operating system running the server agent.

  • Linux: /etc/sft/sftd.yaml

  • Windows: C:\Windows\System32\config\systemprofile\AppData\Local\scaleft\sftd.yaml

If a configuration file hasn't been created or is unavailable, the server agent uses the following default values.

Restart the server agent before changes to the configuration file take effect.

Enrollment Options

Option Default value Description
AutoEnroll True Forces the server agent to attempt to automatically enroll during the initial startup.
EnrollmentTokenFile Linux: /var/lib/sftd/enrollment.token

Windows: C:\Windows\System32\config\systemprofile\AppData\Local\scaleft\enrollment.token

 Specifies the path to a separate file containing an enrollment token. The default value depends on the operating system running the server agent. After the server is enrolled, the server agent deletes this token file.

If using this option, you must manually create the token file and add an enrollment token created on the Okta Privileged Access platform. See Server Enrollment.
InitialURL unset When AutoEnroll is set to True, this option specifies a URL used to automatically enroll the server. If the EnrollmentTokenFile option is also configured, this option is ignored.

Note: This option is only used by legacy installations not hosted by Okta Privileged Access instances.

Log Options

The location of the log file depends on the operating system running the server agent.

  • Linux: sftd uses the system logger when available
  • Windows: C:\Windows\System32\config\systemprofile\AppData\Local\scaleft\Logs

Log files are rotated after 5 MB and only the 10 most recent log files are kept.

Option Default value Description
LogLevel INFO Controls the verbosity of the logs.

Valid values include:

  • warn
  • info
  • debug

Connection Options

Option Default value Description
AccessAddress unset

Specifies the network address (IPv4 or IPv6) used by clients to access servers with multiple interfaces or behind DNATs.

If you set a sftd AccessAddress to DNS FQDN, a message appears on the console warning you that the host key for the IP address has been added to the list of known hosts permanently. See the KB article for additional information.
AccessInterface unset Specifies the interface used by clients to negotiate connections to the host. Only needed by hosts with a specific public IP address associated with a known interface.

Example:

AccessInterface: eth0
AltNames unset Specifies a list of alternative server hostnames. These names can be used as targets for sft ssh.

Example:

AltNames: ["web01", "web01.example.com"]
Bastion unset Specifies a bastion host used automatically by clients when connecting to this server.
BufferFile /var/lib/sftd/buffer.db Specifies the path prefix to the files used for the server agent local buffer store. Individual buffer file names consist of the path prefix, followed by a period and an incremental number (for example, buffer.db.1). Buffer files are automatically removed after being synchronized.
CanonicalName unset Specifies the name that clients should use when connecting to this host. This option overrides the name returned by the hostname command.
ForwardProxy unset Specifies the URL of an HTTP CONNECT proxy that the server agent uses for outbound network connectivity to the Okta Privileged Access platform. Alternatively, the HTTPS_PROXY environment variable can be used to configure this proxy.

Example:

ForwardProxy: https://myproxydomain.com:8080
ServerFile /var/lib/sftd/device.server Specifies the path to a file used to store the server URL of the server that it connects to.
SSHDConfigFile /etc/ssh/sshd_config Specifies the path to the sshd configuration file.

Note: The server agent modifies this file.

SSHDPort

unset

 Specifies a port to use when negotiating SSH connections. This option is only needed if the default port (22) isn't being used. This option tells the sft client (ScaleFT Client-Tools) how to connect to the sftd Agent (ScaleFT Server-Tools). You must also modify the sshd_config file on the server agent server to listen on the specified port.
TokenFile /var/lib/sftd/device.token Specifies the path to a file used to store the secret authentication token for Okta Privileged Access.

TrustedUserCAKeysFile

 /var/lib/sftd/ssh_ca.pub Specifies the path to a file used by the server agent to store a list of trusted SSH Certificate Authorities.

Access Broker Options

The Okta Privileged Access server agent automatically runs an access broker process. The access broker authenticates clients using certificates issued by the Okta Privileged Access platform.

On Windows servers, the access broker is also responsible for proxying RDP connections. See Windows Internals.

Option

Default value

Description
BrokerAccessPort 4421 Specifies a port used by clients to reach the access broker.
BrokerListenHost unset Specifies the network address (IPv4 or IPv6) used by the access broker to listen for connections. By default, the access broker listens for connections on every available interface.
BrokerListenPort 4421 Specifies a port used by the access broker to listen for connections.
DisableBroker unset Controls the operation status of the access broker. Set to True to restrict the access broker from running on the server.

Note: Disabling the access broker process isn't recommended on Windows. See Windows Internals.

Custom labels

Custom labels may impact server accessibility. A user with access to the config files of the server can change files. This causes the server to become accessible or inaccessible based on the labels that they choose. Okta recommends exercising caution when using custom labels.

Labels allow teams to define key:value pairs used to control server access to specific groups. Labels are formatted as key:value pairs to allow teams to define a schema that best fits their needs. Add labels in the server configuration file to configure and categorize the servers. These labels are used in the Okta Privileged Access console to select specific servers for access. See Security policy.

You must indent any key pairs within a Label YAML dictionary using two spaces:

Labels: label_1: value_1 label_2: value_2

System generated labels

When you add a server to Okta Privileged Access, several system-generated labels are created based on characteristics such as hostname, server type, operating system, AWS, Azure, or Google Cloud Platform (GCP) account ID.

The following are the list of system-generated labels.

Label

Description
system.hostname The hostname of the server
system.canonical_name The server alias used by clients to connect to the server. See Connection Options.
system.os The OS version of the server, such as CentOS 6 or Debian 9.13
system.os_type

The OS family of the server. Valid values are linux and windows.

system.cloud_provider

The cloud provider for the server. Valid values are aws for AWS, gce for GCP, azure for Azure.

system.aws_account_id

The account ID of the AWS server

system.aws_availability_zone

The specific availability zone (AZ) of the AWS server

system.gcp_project_id

The project ID of the GCP server

system.azure_location

The specific region of the Azure server

Environment variables

On startup, the server agent reads the following variables:

SFT_DEBUG: Prints more debugging to stderr when set.

Related topics

Server Enrollment

Requirements and limitations