Use the Okta Privileged Access client

Every Okta Privileged Accessclient 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 version.

Topics

Client commands

Command Description Options
sft ad list-domains

List Active Directory domains.
  • --team {value}: Uses the specified team.
  • --output, -o: Formats result in the specified format. Available options include: default, JSON, or describe.
sft ad list-accounts

List Active Directory accounts.
  • --team {value} --domain {value}: Uses the specified team and domain.
  • --output, -o: Formats result in the specified format. Available options are default, JSON, and describe.
sft ad reveal

Reveal the password associated with an Active Directory (AD) account.
  • --domain {value}: Uses the specified AD domain.
  • --ad-account username: Uses the specified AD account and username.
  • --team {value}: Uses the specified team.
  • --output, -o: Formats result in the specified format. Available options are default, JSON, and describe.
sft list-checked-out-resources List checkout resources.
  • --team {value}: Uses the specified team.
  • --instance {value}: Uses the specified instance of the Okta Privileged Access platform.
  • --output, -o: Formats result in the specified format. Available options include: default, JSON, or describe.
  • --resource-type {value}: Use this to display only resources of the specified type, along with other resource-specific details.
  • --include-pending-checkin: Use this to include checked out resources that are in the checkin process.
sft checkin Check in a resource.
  • --team {value}: Uses the specified team.
  • --instance {value}: Uses the specified instance of the Okta Privileged Access platform.
  • --resource-id {value}: The UUID or ORN of the resource to check in.
  • --resource-type {value}: The type of resource to check in. This field is required.
  • --force: Use this to check in resources checked out by other users.
sft config Gets and sets client configuration options. See Configure the client.
  • --config-file: Uses the specified configuration file.
  • --append: Adds the specified value to an array.

  • ssh.connection_failed_process_timeout_in_seconds {value}: Sets a timeout for how long the system waits for confirmation of a failed SSH connection before terminating the process.
sft dash Opens your team's dashboard in your browser.
  • --team {value}: Uses the specified team.
  • --instance: Uses the specified instance of the Okta Privileged Access platform.
  • --account: Uses the specified account.
  • --config-file: Uses the specified configuration file.
sft device-info Shows your client's device info as JSON. -
sft enroll Adds your new client to your client inventory on the Okta Privileged Access platform.
  • --default: Sets a new default team. (default: true)
  • --url: Sets the URL used to access an Okta Privileged Access instance.
  • --team: Uses the specified team.
  • --config-file: Uses the specified configuration file.
  • --force: Enrolls the client even if a duplicate exists (default: false)
sft fleet enroll Silently enroll clients multiple clients within a fleet. See Silently enroll the Okta Privileged Access client.
  • --default: Set a new team as the default. (default: true)
  • --token: Enroll the client with the specified token.
  • --token-file: Enroll the client using a secret token stored in the specified file.
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.
  • --config-file: Uses the specified configuration file.
  • -l, --selector: Filters results by the specified selector (label query). See Selectors.
  • --output, -o: Formats result in the specified format. Available options include: default, json, or describe.
  • --columns: Displays the specified column names in the output. Column names should be lowercase and collected in a comma-delimited list.
sft list-projects Lists available projects for the team.
  • --team {value}: Uses the specified team.
  • --instance: Uses the specified instance of the Okta Privileged Access platform.
  • --account: Uses the specified account.
  • --config-file: Uses the specified configuration file.
  • -l, --selector: Filters results by the specified selector (label query). See Selectors.
  • --output, -o: Formats result in the specified format. Available options include: default, json, or describe.
  • --columns: Displays the specified column names in the output. Column names should be lowercase and collected in a comma-delimited list.
sft list-servers Lists the servers available in the current team.
  • --team {value}: Uses the specified team.
  • --instance: Uses the specified instance of the Okta Privileged Access platform.
  • --account: Uses the specified account.
  • --config-file: Uses the specified configuration file.
  • -l, --selector: Filters results by the specified selector (label query). See Selectors.
  • -p, --project: Filters results by the specified project name.
  • --output, -o: Formats result in the specified format. Available options include: default, json, or describe.
  • --columns: Displays the specified column names in the output. The labels appear only if the column name is passed in for the columns option. For example, sft list-servers --column <ID>, <hostname>, <labels>. Column names should be lowercase and collected in a comma-delimited list.
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 Configure Royal TSX for Advanced Server Access .
  • --team {value}: Uses the specified team.
  • --instance: Uses the specified instance of the Okta Privileged Access platform.
  • --account: Uses the specified account.
  • --config-file: Uses the specified configuration file.
  • -l, --selector: Filters results by the specified selector (label query). See Selectors.
  • -p, --project: Filters results by the specified project name.
  • -f, --filename: Specify a path to store the file output.
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 Okta Privileged Accessclient to request credentials in the background as needed.
  • --team {value}: Uses the specified team.
  • --instance: Uses the specified instance of the Okta Privileged Access platform.
  • --account: Uses the specified account.
  • --config-file: Uses the specified configuration file.
sft logout Logs out from the current session.
  • --team {value}: Uses the specified team.
  • --instance: Uses the specified instance of the Okta Privileged Access platform.
  • --account: Uses the specified account.
  • --config-file: Uses the specified configuration file.
sft proxycommand Used with OpenSSH ProxyCommand to enable transparent use of sft with ssh, scp, rsync, ftp, and so on.
  • --team {value}: Uses the specified team.
  • --instance: Uses the specified instance of the Okta Privileged Access platform.
  • --account: Uses the specified account.
  • --config-file: Uses the specified configuration file.
  • --via, --bastion: Connects to the target through the specified Secure Shell bastion.
  • --config: Deprecated. Use sft ssh-config instead.
  • --sudo-display-name {value}, --sudo {value}: User Access Methods are filtered by this display name.
sft rdp Connects through RDP to a target passed as an argument.
  • --via, --bastion: Connects to the target through the specified SSH bastion.
  • --team {value}: Uses the specified team.
  • --instance: Uses the specified instance of the Okta Privileged Access platform.
  • --account: Uses the specified account.
  • --config-file: Uses the specified configuration file.
  • --share: Specify the absolute path to a directory to be shared with the target.
sft register-url-handler

(Windows only) Opens the ScaleFT application when a user clicks the Connect button on the My Servers page.

Running the command will create these folders.

  • Computer\HKEY_CLASSES_ROOT\ScaleFTProtocolHandler\shell\open\command

  • Computer\HKEY_CLASSES_ROOT\scaleft

The ScaleFT application can't be launched by the Connect button if the corresponding entry is missing from the Windows Registry.

See How the ASA/OPA Webpage Launches SFT for details.

-
sft resolve Resolves a single-server matching the specified hostname or instance-details.
  • --q, --quiet: Causes only fatal warnings to output to stderr.
  • --team {value}: Uses the specified team.
  • --instance: Uses the specified instance of the Okta Privileged Access platform.
  • --account: Uses the specified account.
  • --config-file: Uses the specified configuration file.
  • --sudo-display-name {value}, --sudo {value}: User Access Methods are filtered by this display name.
sft secrets Lists all available secrets commands. -
sft secrets list Lists all top-level secret folders and secrets.
  • --resource-group {resource group}: Uses the specified resource group.
  • --project {project}: Uses the specified resource group.
--path: Uses the specified path.
sft secrets create

Creates a secret.

The name can only contain alphanumeric characters (a-Z, 0–9), hyphens (-), underscores (_), and periods (.)
  • --resource-group {resource group}: Uses the specified resource group.
  • --project {project}: Uses the specified resource group.
  • --path: Uses the specified path.
  • --key {key}: Adds specified key.
  • --value {value}: Adds specified value.
  • --name {name}: The name for the new secret.
  • --description {description}: (Optional) A description of this secret.
sft secrets create-folder

Creates a secret folder.

The name can only contain alphanumeric characters (a-Z, 0–9), hyphens (-), underscores (_), and periods (.)
  • --resource-group {resource group}: Uses the specified resource group.
  • --project {project}: Uses the specified resource group.
  • --path: Uses the specified path.
  • --name {name}: The name for the new secret folder.
  • --description {description}: (Optional) A description of this secret folder.
sft secrets describe Shows metadata about the secret at path.
  • --resource-group {resource group}: Uses the specified resource group.
  • --project {project}: Uses the specified resource group.
  • --path: Uses the specified path.
  • --name {name}: The name of the secret.
sft secrets describe-folder Shows metadata about the secret folder at path.
  • --resource-group {resource group}: Uses the specified resource group.
  • --project {project}: Uses the specified resource group.
  • --path: Uses the specified path.
  • --name {name}: The name of the folder.
sft update-secret

Updates a secret's values.

Use update-secret-metadata to update a secret's name or description.
  • --resource-group {resource group}: Uses the specified resource group.
  • --project {project}: Uses the specified resource group.
  • --path: Uses the specified path.
  • --name {name}: The name for the new secret.
  • --key {key}: Key for a new value.
  • --value {value}: The new value for the previously mentioned key.
sft secrets delete Deletes the specified secret.
  • --resource-group {resource group}: Uses the specified resource group.
  • --project {project}: Uses the specified resource group.
  • --path: Uses the specified path.
  • --name {name}: The name for the new secret.
sft secrets delete-folder Deletes the specified secret folder. All the contents in that folder is also deleted.
  • --resource-group {resource group}: Uses the specified resource group.
  • --project {project}: Uses the specified resource group.
  • --path: Uses the specified path.
sft secrets reveal Displays the key names and secret value fields.
  • --resource-group {resource group}: Uses the specified resource group.
  • --project {project}: Uses the specified resource group.
  • --path: Uses the specified path.
  • --name {name}: The name for the new secret.
  • --key {key}: (Optional) Limit the response to only the specified keys.
secrets update-secret-metadata Updates the name or description of a secret.

  • --resource-group {resource group}: Uses the specified resource group.

  • --project {project}: Uses the specified resource group.

  • --path: Uses the specified path.

  • --name {name}: The name of the secret.

  • --new-name {name}: (Optional) The new name for the secret.

  • --description {description}: (Optional) A description of the secret. If this is excluded, the description isn't updated.

secrets update-folder-metadata Updates the name or description of a secret folder.
  • --resource-group {resource group}: Uses the specified resource group.
  • --project {project}: Uses the specified resource group.
  • --path: Uses the specified path.
  • --new-name {name}: The new name for the secret folder.
  • --description {description}: (Optional) A description of this folder. If this is excluded, the description isn't updated.
sft session-logs verify Verify the integrity of a specified session log against the Okta Privileged Access gateway signing key registered with Okta Privileged Access. Log files without valid signatures may be inaccurate or corrupted by an attacker.
--stdin: Returns session data from stdin, instead of from a session log file.
sft session-logs export Export 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.
  • --stdin: Returns session data from stdin, instead of from a session log file.
  • --insecure: Stops the client from verifying the integrity of the session log file
  • --format: Exports log in a specific format. Available options include: json or asciinema
  • --output: Stores the exported logs in the specified file instead of stdout
sft ssh Connects through Secure Shell to a target passed as an argument.

Generally, Okta Privileged 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 Okta Privileged Access-specific options such as --via.
  • --via, --bastion: Uses the specified SSH bastion host to connect to the target.
  • --team: Uses the specified team.
  • --instance: Uses the specified instance of the Okta Privileged Access platform.
  • --account: Uses the specified account.
  • --config-file: Uses the specified configuration file.
  • -L, --local-port-forward: Forwards the specified local port to a remote address.
  • -R, --remote-port-forward: Forwards the specified remote listener to a local address.
  • --command: Executes the specified command through SSH.

  • --sudo-display-name {value}, --sudo {value}: User Access Methods are filtered by this display name.
sft ssh-config Prints an OpenSSH configuration block suitable for use in your ~/.ssh/config file, which enables your local ssh binary to use Okta Privileged Access authentication. This SSH configuration is used only when your client has a currently active and authorized session.
  • --team {value}: Uses the specified team.
  • --instance: Uses the specified instance of the Okta Privileged Access platform.
  • --account: Uses the specified account.
  • --config-file: Uses the specified configuration file.
  • --via, --bastion: Connects to the target through the specified SSH bastion.
sft support collect Collect local diagnostic information for Okta Support. -
sft support submit Submit diagnostic information for Okta Support. -
sft unenroll Removes the currently active client from your client inventory in the Okta Privileged Access platform.
  • -y, --yes: Uses the specified team.
  • --team {value}: Uses the specified team.
  • --instance: Uses the specified instance of the Okta Privileged Access platform.
  • --config-file: Uses the specified configuration file.
  • --all: Unenroll all local clients.
sft use Sets an enrolled team as the current default for use in your current session.
  • --instance: Uses the specified instance of the Okta Privileged Access platform.
  • --config-file: Uses the specified configuration file.

sft workload authenticate

(abbreviate as sft wl auth)

 Used by a workload to authenticate to Okta Privileged Access using its identity proof (JWT) and retrieve an Okta Privileged Access token.
  • --connection=CONNECTION_NAME: Required. Specifies the unique name of the Workload Connection that Okta Privileged Access uses to verify the machine's identity.
  • --role-hint=WORKLOAD_ROLE_HINT: Optional. Passes a suggested Workload Role name to Okta Privileged Access.
  • --jwt-env=ENV_VAR: Required. Specifies the name of the environment variable that holds the Workload's Identity Proof (the JWT/OIDC token).

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.

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

Client configuration

You can view or set configuration options with the sft config command.

No configuration file exists when the Okta Privileged 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 Okta Privileged 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.

Okta Privileged 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 you don't set this option, Okta Privileged 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 Okta Privileged 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 Okta Privileged 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

Set this to host to set the ForwardAgent when you execute SSH commands. SSH credentials that are issued by Okta Privileged Access aren't added to the ssh-agent. This option is used for hosts that are configured to accept externally managed credentials, such as SSH public keys that aren't managed by Okta Privileged Access.

Not setting this option or setting it to the value none causes Okta Privileged Access to not forward the SSH agent.

prefer_bundled_ssh

If set to true, the bundled MSYS2 OpenSSH client is preferred over native OpenSSH.

 
sft config ssh.prefer_bundled_ssh true
sft config ssh.prefer_bundled_ssh false

SSH agent configuration options

Key

Description

Examples
ssh_agent.enable If set to true, the Okta Privileged Access client uses an SSH agent when a user authenticates. 
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 you write a JSON literal in Windows PowerShell, escape inner quotes; for example:

sft config ssh_agent.keys '[\"C:\\Users\\alice\\.ssh\\id_rsa\"]'

Network configuration options

Key

Description

Examples
network.forward_proxy If you configure this option, the Okta Privileged 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, the Okta Privileged Access client uses a bundled CA certificate list for TLS validation. Similarly, if set to false, the client uses the operating system's CA list.

 
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 Okta Privileged 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 Okta Privileged 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.

  • If this option is unset or set to 0, the client uses the default value of 300 seconds.
  • If this option is set to a negative value, the timeout is disabled.
 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 When set, allows connections with usernames that include non-standard characters. SFT_ALLOW_INSECURE_USERNAMES=1 sft ssh ...

Related topics

Install the Okta Privileged Access client

Managed Okta Privileged Access server agent

Requirements and limitations