Use the Advanced Server Access client
Every Advanced Server Access client command uses the syntax:
sft [global options] command [command options] [arguments...]
Global options
You can use the following options with any client command:
- -h, --help displays help
- -v, --version displays the version
Client commands
| Command | Description | Options |
|---|---|---|
| sft config | Gets and sets client configuration options. See Configure the client. |
|
| sft dash | Opens your team's dashboard in your browser. |
|
| sft device-info | Shows your client's device info as JSON. | |
| sft enroll | Adds your new client to your client inventory on the Advanced Server Access platform. |
|
| sft fleet enrolls | Enrolls multiple clients silently within a fleet. See Silently enroll the Advanced Server Access client. |
|
| sft help | Shows a list of commands or help for one command. | |
| sft list-accounts | Lists the accounts that this client is configured to use. |
|
| sft list-teams
sft list-teams command is an alias for the sft list-accounts command. Okta recommends using the sft list-teams command. |
Lists the teams that this client is configured to use. |
|
| sft list-projects | Lists available projects for the team. |
|
| sft list-servers | Lists the servers available in the current team. |
|
| sft list-servers-rjson | Lists the servers available in the current team in an RJSON format. You can save this output to a file and used in Royal TSX to create a dynamic folder. See Use Royal TSX with Advanced Server Access. |
|
| sft login | If logged out of your client's current team, creates a session, authenticating with your team's Identity Provider.
An active, authorized client session allows the Advanced Server Access client to request credentials in the background as needed. |
|
| sft logout | Logs out from the current session. |
|
| sft proxycommand | Used with OpenSSH ProxyCommand to enable transparent use of sft command with ssh, scp, rsync, ftp, and so on. |
|
| sft rdp | Connects via RDP to a target passed as an argument. |
|
| sft register-url-handler |
(Windows only) Opens the ScaleFT application when a user clicks the Connect button on the My Servers page. For this to work correctly, you must update the Windows Registry with the following entry: Computer\HKEY_CLASSES_ROOT\ScaleFTProtocolHandler\shell\open\command. The connect button won't launch the ScaleFT application if this entry is missing on your Windows Registry. |
|
| sft resolve | Resolves a single-server matching the specified hostname or instance-details. |
|
| sft session-logs verify | Verifies the integrity of a specified session log against the Advanced Server Access gateway signing key registered with Advanced Server Access. Log files without valid signatures may be inaccurate or corrupted by an attacker. |
|
| sft session-logs export | Exports session logs to a particular format. By default, logs are exported to JSON format. Session logs are also verified during the export process. Log files without valid signatures may be inaccurate or corrupted by an attacker. |
|
| sft ssh | Connects through Secure Shell to a target passed as an argument.
Generally, Advanced Server Access works with ssh using OpenSSH ProxyCommand integration. The sft ssh command is provided for ssh support in environments or contexts where OpenSSH isn't available. The command can also be used when you want to explicitly pass Advanced Server Access-specific options such as --via. |
|
| sft ssh-config | Prints an OpenSSH configuration block suitable for use in your ~/.ssh/config file, which will enable your local ssh binary to use Advanced Server Access authentication. This SSH configuration is used only when your client has a currently active and authorized session. |
|
| sft support collect | Collects local diagnostic information for Okta Support. | |
| sft support submit | Submits diagnostic information for Okta Support. | |
| sft unenroll | Removes the currently active client from your client inventory in the Advanced Server Access platform. |
|
| sft use | Sets an enrolled team as the current default for use in your current session. |
|
Selectors
- -l, --selector the selector (label query) to filter on.
Commands that take a selector as an optional argument can filter their results based on an arbitrary selector query.
Selector syntax is based on Kubernetes label queries. See Labels and Selectors.
Example:
sft list-servers -l os_type=windows,project_name=Demo
The example uses a selector to filter the list of servers you have access to. It returns a list of Windows servers that are enrolled in the demo project.
Configure the client
You can view or set configuration options with the sft config command.
No configuration file exists when the Advanced Server Access client is installed. The configuration file is created when you set your first configuration option.
Default settings are used until you explicitly set a configuration value. The defaults provided for the Advanced Server Access client are intended to provide the most security and ease of use for the most common situations. Aside from personal preferences, such as the setting for rdp.screensize, you may not need to set any client configurations at all.
Advanced Server Access client configurations are grouped into sections. Currently these sections include rdp, ssh, ssh_agent, service_auth, and update.
View your configuration
- sft config display your current configurations
- sft config [section.key] view the current value of a specific configuration indicated by section.key
Set a configuration value
You can set a configuration value with the command syntax: sft config [section.key] [value].
RDP configuration options
|
Key |
Description |
Examples |
|---|---|---|
| rdp.screensize | Set this to a string value, such as 1024x768 that describes your preferred RDP window size. | sft config rdp.screensize 800x600 sft config rdp.screensize 1024x768 |
| rdp.fullscreen | Set this to true to have RDP sessions open in fullscreen mode. When set to true, the value of rdp.screensize is ignored. | sft config rdp.fullscreen true sft config rdp.fullscreen false |
| rdp.client | (macOS only) Set this to your preferred RDP client, either royaltsx for Royal TSX, or macfreerdp for MacFreeRDP. If this option isn't set, Advanced Server Access attempts to use Royal TSX, and then MacFreeRDP if Royal TSX is unavailable. | sft config rdp.client royaltsx sft config rdp.client macfreerdp |
SSH configuration options
|
Key |
Description |
Examples |
|---|---|---|
| ssh.save_privatekey_passwords | If set to true, the Advanced Server Access client stores any passphrases entered by the user in the workstation's local cryptographic store. | sft config ssh.save_privatekey_passwords true sft config ssh.save_privatekey_passwords false |
| ssh.port_forward_method | Set this to netcat to have Advanced Server Access remotely execute netcat (nc) as a means of port forwarding, rather than using the default native SSH port forwarding. | sft config ssh.port_forward_method netcat sft config ssh.port_forward_method native |
|
ssh.insecure_forward_agent This feature is not compatible with the Windows client. |
Set this to host to set the ForwardAgent when executing SSH commands. Advanced Server Access-issued credentials aren't added to the ssh-agent, so this option is for use with hosts that are configured to accept an externally managed credential, such as an SSH public key that's Advanced Server Access does not manage. Not setting this option, or setting it to the value none, causes Advanced Server Access to not forward the SSH agent. |
sft config ssh.insecure_forward_agent host sft config ssh.insecure_forward_agent none |
SSH agent configuration options
|
Key |
Description |
Examples |
|---|---|---|
| ssh_agent.enable | If set to true, Advanced Server Access client uses an SSH agent when authenticating. | sft config ssh_agent.enable true sft config ssh_agent.enable false |
| ssh_agent.keys |
Set this to a JSON array of one or more paths to SSH private keys to load into the SSH agent. You can append values to this list by using the --append flag.
Tip: When writing a JSON literal in Windows PowerShell, escape inner quotes; for example: sft config ssh_agent.keys '[\"C:\\Users\\alice\\.ssh\\id_rsa\"]' |
sft config ssh_agent.keys '["/Users/alice/.ssh/id_rsa"]' sft config ssh_agent.keys --append /Users/alice.ssh/id_rsa sft config ssh_agent.keys '[]' |
Network configuration options
|
Key |
Description |
Examples |
|---|---|---|
| network.forward_proxy | If you configure this option, the Advanced Server Access client uses the specified HTTP or HTTPS URL as an HTTP tunnel. | sft config network.forward_proxy https://your-proxy.example.com:3141 |
|
network.tls_use_bundled_cas |
If set to true, Advanced Server Access client uses a bundled CA certificate list for TLS validation. If set to false, the client uses the operating system's CA list. This option is set to true by default and it's highly advised that you don't change it to false, as certain operating systems can have CA list issues, and the performance can be measurably worse than using bundled CA certificate lists. |
sft config network.tls_use_bundled_cas true sft config network.tls_use_bundled_cas false |
Miscellaneous configuration options
|
Key |
Description |
Examples |
|---|---|---|
| service_auth.enable | If set to true, the Advanced Server Access client supports authentication for service users. See Service users. | sft config service_auth.enable true sft config service_auth.enable false |
| update.release_channel | The Advanced Server Access client defaults to the stable update channel, but you can opt into receiving more frequent releases by setting this option to use the test update channel. | sft config update.release_channel test sft config update.release_channel stable |
| client.timeout_seconds |
Defines the maximum time that the client waits for a response from a server before resending the request.
|
sft config client.timeout_seconds 60 sft config client.timeout_seconds -1 |
Environment variables
|
Variable |
Description |
Examples |
|---|---|---|
| SFT_DEBUG | When set, any command run prints internal logs and timing messages to stderr |
SFT_DEBUG=1 sft list-servers |
| SFT_ALLOW_INSECURE_USERNAMES | Allows connections with usernames that include non-standard characters. | SFT_ALLOW_INSECURE_USERNAMES=1 sft ssh ... |
|
SFT_ALLOW_INSECURE_SHA1_SSH |
Disables the warning prompt when connecting to servers in a project using SHA1 certificates. To eliminate this prompt, consider changing the project to use the ssh-ed25519 algorithm. |
SFT_ALLOW_INSECURE_SHA1_SSH=1 sft ssh ... |
SFT Keyring
If you enable the SFT keyring, all plaintext tokens in the state.json file will be encrypted. Once the SFT keyring is established on a system, it is automatically updated when the user logs in to Okta Privileged Access or attempts to access a server.
After the SFT keyring is activated, it can't be reversed. Okta Privileged Access employs the compat keyring for all operating systems, which doesn't offer encryption. To revert to the default compat keyring, users need to re-enroll and relogin.
Before you begin
- SFT keyring encrypts access tokens. If the keys used to decrypt the tokens are unavailable, decryption is impossible. This prevents unauthorized data exfiltration.
- SFT keyring on Linux uses D-Bus to connect to a desktop-specific SecretService and proactively secures access tokens. If sft can't reach an unlocked SecretService, it will not be able to decrypt those tokens. This may result in being locked out of your tokens while in non-desktop mode if you use Linux on both desktop and non-desktop. To avoid this, you can use the insecure compact keyring by setting SFT_KEYRING to compat in your shell initialization scripts and then re-enrol.
Setting up the Keyring
SFT keyring must be configured on every device. The operating system comes with a default keyring, and it determines the most suitable one to use. By using the system variable in the configuration, the operating system automatically selects the optimal keyring for use.
macOS
SFT keyring encrypts by default on macOS. You can set the keyring using the User Defaults framework:
$ defaults write com.scaleft.ScaleFT SFTKeyring system
Alternatively, you can enable it by setting an environment variable:
export SFT_KEYRING=system
If both are set, the environment variable takes precedence.
To disable encryption, use compat instead of system in the environment variable, and then re-enroll in the team.
Windows
SFT keyring encrypts by default on Windows. You can set the keyring using the registry:
HKEY_LOCAL_MACHINE\Software\ScaleFT\SFT\Keyring
Or
HKEY_CURRENT_USER\Software\ScaleFT\SFT\Keyring
Alternatively, you can set the keyring using the SFT_KEYRING environment variable.
HKEY_LOCAL_MACHINE takes precedence over both the environment variable and CURRENT_USER entry. The environment variable takes precedence over the CURRENT_USER entry.
To disable encryption, set the registry key to compat instead of system, and then re-enroll in the team.
FreeBSD / Linux
In FreeBSD and Linux, keyrings only work in a D-Bus desktop environment. In Linux, the default encryption method is system, while in FreeBSD, it's compat.
To set or update the SFT_KEYRING environment variable to either compat or system, add the following to the shell profile:
export SFT_KEYRING=system
Or
export SFT_KEYRING=compat