SSH Connections with Native Clients

Users can connect to target hosts or accounts using the SSH clients installed on their workstations without the PrivX GUI. PrivX authenticates and authorizes these connections before granting access to the target account.

Native SSH client connections can be made through PrivX SSH Bastion or directly to the target host:

• When connecting through PrivX SSH Bastion, the SSH client connects to PrivX first, and then PrivX routes the connection to the selected target.
• When connecting directly to the target host, PrivX is still used for authentication or access control, for example through PrivX Agent or certificate-based machine-to-machine access.

Native SSH clients use the same authentication method that PrivX allows for the target account. For example, if PrivX allows access to a target account with certificate authentication, the native SSH client also uses certificate authentication and does not prompt the user for target-account credentials.

IMPORTANT

The PrivX SSH Bastion only supports the SSHv2 protocol. SSHv1 is not supported because of its security vulnerabilities.

Prerequisites

Before you begin, make sure that the following requirements are met:

• Roles that may be used for SSH native client connections are specified.
• The SSH Bastion feature is enabled in your PrivX license. For more information, see Licensable Features.
• If you use native SSH client connections through Extenders, upgrade PrivX and download the updated extender-config.toml file. For more information on the Extender configuration file, see Setting up PrivX Components.
• If you connect with PrivX Agent, make sure:
  • The Use with PrivX agent option is enabled for the roles assigned to the relevant users. You can enable this option in Administration → Roles.
  • PrivX Agent is installed and configured on the user's workstation. For setup instructions, see PrivX-Agent Setup.

Connecting through PrivX Bastion

With native SSH clients, you can connect to target hosts through PrivX SSH Bastion. By default, PrivX SSH Bastion runs on port 2222. PrivX SSH Bastion supports several native SSH client connection modes:

• Interactive: Access PrivX Bastion to list and select possible targets.
• Direct: Specify your connection target directly to the native client.
• Direct using ProxyCommand: Specify your PrivX username in ssh_config.
• Direct using privx-cmd: Similar to ProxyCommand but supports OIDC users.

tip

PrivX Bastion connections are verified against the PrivX Bastion host key. You can verify and install the host keys in Connections → Native Clients.

User sessions with native SSH clients can be monitored. For more information about viewing session audit data, see Viewing Audit Data. For more information about setting up session recording for a host, see Session-Recording Setup.

SSH Bastion connections prompt users to log in to PrivX. For automated, scripted access, set up public key authentication as described in Public-Key Authentication (SSH Bastion).

Connecting Interactively

To connect through PrivX Bastion interactively:

1. Connect to PrivX SSH Bastion with your PrivX account. Use one of the following commands:

   $ ssh -p 2222 privxuser@privx.example.com                         # Connect with SSH
   $ sftp -P 2222 privxuser@privx.example.com                        # Connect with SFTP
   $ scp -P 2222 local/path privxuser@privx.example.com:remote/path  # Upload with SCP
   $ scp -P 2222 privxuser@privx.example.com:remote/path local/path  # Download with SCP

   IMPORTANT

   Use uppercase -P for the sftp and scp port. For ssh, use lowercase -p.

2. Replace the example values as follows:

   • privxuser: PrivX username.
   • privx.example.com: PrivX Server address.
   • local/path: local file/directory path for scp.
   • remote/path: remote file/directory path for scp.

3. When prompted, enter your PrivX user password.

4. From the list of available targets, select the target you want to connect to.

Connecting Directly

To connect through PrivX SSH Bastion directly:

1. Provide the following connection details:

   • Target user name
   • Target host address
   • PrivX username
   • PrivX Server address
   • [Optional] Extender name
   • [Optional] Target port

   By default, PrivX Bastion runs on your PrivX Servers on port 2222.

2. Select the bastion syntax based on your PrivX components:

   • Use the following full syntax when the connection goes through an Extender and uses a custom target port:

     targetuser%extender%targethost%targetport%privx-user@privx.example.com

   • If you do not use an Extender or a custom target port, omit those values from the connection string:

     targetuser%targethost%privx-user@privx.example.com

   • With OpenSSH 10.0p2 and later, replace each % character with %%. For example:

     targetuser%%extender%%targethost%%targetport%%privx-user@privx.example.com

3. Connect to the target host with ssh, scp, or sftp.

   IMPORTANT

   Use uppercase -P for the sftp and scp port. For ssh, use lowercase -p.

   $ ssh -p 2222 targetuser%targethost%privx-user@privx.example.com
   $ scp -P 2222 targetuser%targethost%privx-user@privx.example.com:example.txt \
   /target/directory
   $ sftp -P 2222 targetuser%targethost%privx-user@privx.example.com

   To connect through PrivX Extender, include its name in the connection string:

   $ ssh -p 2222 targetuser%extender%targethost%privx-user@privx.example.com
   $ scp -P 2222 example.txt \
   targetuser%extender%targethost%privx-user@privx.example.com:/tmp

4. [Optional] To shorten future commands, save the connection parameters in the SSH client configuration file, which is typically located at /etc/ssh/ssh_config or ~/.ssh/config.

   For example, if you add the following Host block to the SSH client configuration file:

   Host targethost.example.com
       Port 2222
       User targetuser%targethost%privx-user
       Hostname privx.example.com

   You can then connect by running:

   $ ssh targethost.example.com

Connecting Directly Using ProxyCommand

Use ProxyCommand to define connection settings in the SSH client configuration file. This method requires public key authentication to PrivX SSH Bastion. Make sure the SSH client user has an SSH key pair.

IMPORTANT

OIDC users cannot use this method because public keys cannot be explicitly associated with OIDC user accounts. For similar functionality, see Connecting Directly Using privx-cmd instead.

To connect directly using ProxyCommand:

1. Add PrivX Bastion host keys to the SSH client's known_hosts file. You can get the Bastion host keys in Connections → Native Clients.

2. Add the client user's authorized key to their PrivX account, as described in Public-Key Authentication (SSH Bastion).

3. Configure the SSH client to use public key authentication and a proxy when connecting to target hosts in the configuration file, which is typically at /etc/ssh/ssh_config or ~/.ssh/config. By default, PrivX Bastion listens for proxy connections on port 1080.

   Example, where privx.example.com is your PrivX address:

   Host *
       IdentityFile ~/.ssh/id_privx
       HostKeyAlias privx.example.com:2222
       ProxyCommand nc -X connect -x privx.example.com:1080 %h %p

   The supported nc parameters may vary depending on the nc implementation. You can replace nc with another proxy command that supports HTTP CONNECT or SOCKS5/4a.

4. Connect to the target host:

   • If you added the configuration options to the SSH client configuration file, run:

     ssh targetuser@targethost

   • Alternatively, specify the configuration options directly in the ssh command. For example:

     ssh -o "IdentityFile ~/.ssh/id_privx" \
     -o "HostKeyAlias privx.example.com:2222" \
     -o "ProxyCommand nc -X connect -x privx.example.com:1080 %h %p" \
     targetuser@targethost

After you complete these steps, PrivX routes the connection through PrivX SSH Bastion to the target host. The connection to PrivX SSH Bastion is authenticated with public key authentication.

tip

If the connection fails when using nc, check your nmap-ncat version. A known issue in nmap-ncat 7.91 causes the nc command to fail when connecting to an HTTP CONNECT or SOCKS proxy. Use one of the following workarounds:

• Upgrade to newer version of the nmap-ncat package
• Install the BSD netcat package
• Use the socat command.

Connecting Directly Using privx-cmd

privx-cmd is included in the PrivX Agent package, available from Get PrivX software.

With privx-cmd, users connect directly through PrivX Bastion and log in with a browser. For example with OIDC, as part of an SSH native client connection. This method is similar to Connecting Directly Using ProxyCommand, with the following differences:

• The SSH client uses privx-cmd as its ProxyCommand.
• The client machine has access to a web browser to log in to PrivX.
• PrivX OIDC users have the 'authorized-keys-manage' permission.

To connect directly using privx-cmd:

1. Install the privx-cmd binary on the client machine. The file is available from Get PrivX software.

2. Add PrivX Bastion host keys to the SSH client's known_hosts file. To get the Bastion host keys, navigate to Connections → Native Clients.

3. Configure privx-cmd as the ProxyCommand in the SSH client configuration file.

   For OpenSSH

   Add the following Host block to the SSH client configuration file, which is typically at /etc/ssh/ssh_config or ~/.ssh/config:

   Host *
       IdentityFile ~/.ssh/id_privx
       HostKeyAlias privx.example.com:2222
       ProxyCommand privx-cmd -privx https://privx.example.com %h %p

   Replace privx.example.com with your PrivX address and ~/.ssh/id_privx with the path to your private key.

   For PuTTY

   1. In Connection → Proxy, set the Proxy Type: parameter to Local and specify privx-cmd in the Telnet command, or local proxy command field:

        C:\Program Files (x86)\SSH Communications Security\PrivX Cmd\privx-cmd.exe -privx https://master.privx.ssh.com %host %port

   2. Set the Do DNS name lookup at proxy end: parameter to Yes.

   3. In Connection → SSH → Auth, set Private key file for authentication.

4. Establish a trust relationship with PrivX Server by running the following command:

   privx-cmd -command probe -privx https://privx.example.com

   where privx.example.com is your PrivX address.

   This command checks the PrivX Server's certificate. If the certificate is not signed by a trusted CA, privx-cmd prompts the user to accept the certificate. Accepted certificates are stored in ~/.privx/agent.json.

5. Connect to the target host:

   ssh targetuser@targethost

   If required, privx-cmd launches a browser for the user to log in to PrivX. After a successful login, privx-cmd obtains an access token and a refresh token. The refresh token is saved to ~/.privx/token.json, and privx-cmd reuses it for later connections. After that privx-cmd:

   • Registers the user's public key as an authorized key to PrivX.
   • Connects to the SSH Bastion's proxy port 1080, requests a connection to the target host, and starts forwarding data between the SSH client and SSH Bastion.

After you complete these steps, PrivX routes the connection through PrivX SSH Bastion to the target host. The connection to PrivX Bastion is authenticated using public key authentication.

For subsequent SSH connections, privx-cmd uses the saved refresh token to obtain access tokens. If the refresh token is valid, the user does not need to log in to PrivX again, and the browser-based login step is skipped. To remove saved refresh tokens from the file system, run:

privx-cmd -command logout

You can use the privx-cmd command-line options to override the default values used in previous examples. Use these options in the following cases:

• You want to store your SSH key pair in a different file.
• You do not want to save the refresh token to the file system.
• You want to use a non-default browser for login.
• The SSH Bastion proxy listener hostname differs from the PrivX Server hostname.

privx-cmd Options

The following options are available for privx-cmd:

Option	Description	Default values
-browser string	Specifies the command used for launching a browser.	—
-command string	Runs connect, probe, or logout.	connect
-config string	Specifies the PrivX Agent configuration file.	~/.privx/agent.json
-d	Enables debug mode.	—
-no-token	Prevents privx-cmd from saving the refresh token to the file system.	—
-privx string	Specifies the PrivX base URL.	—
-proxy-host string	Specifies the PrivX SSH Bastion proxy hostname.	—
-proxy-port int	Specifies the PrivX SSH Bastion proxy port.	1080
-pub string	Specifies the SSH public key file.	~/.ssh/id_privx.pub
-token string	Specifies the token storage file.	~/.privx/token.json
-v	Displays version information and exits.	—

Connecting without PrivX Bastion

Connecting with PrivX Agent

Linux and macOS

After installing and configuring PrivX Agent on your workstation, follow these steps to connect to target hosts on Linux or macOS:

1. Log in to the workstation as the user for which PrivX Agent is configured.

2. Verify that PrivX Agent is running:

   $ privx-agent-ctl status

   This command returns output similar to the following:

   PrivX SSH Agent Status
   PrivX Server          https://privx.example.com
   Login status          logged out

   If PrivX Agent is not running, start it manually:

   $ ./privx-agent-unix bash

3. In a terminal, log in to PrivX with your PrivX credentials:

   $ privx-agent-ctl login username

   Replace username with your PrivX username.

   Verify your login status with:

   $ privx-agent-ctl status

4. After you log in to PrivX, native SSH clients such as ssh authenticate connections through PrivX. To list the targets that you can access, run:

   $ privx-agent-ctl target list

5. Connect to a target host using a native SSH client. For example:

   $ ssh alice@10.1.55.144 -p 222

Windows

After installing and configuring PrivX Agent on your workstation, follow these steps to connect to target hosts on Windows:

1. Right-click the PrivX Agent icon in the notification area and select Login to log in with your PrivX credentials. Complete multifactor authentication (MFA), if required.

   If login fails with the Failed: Login through web UI is required message, log in to the PrivX GUI using a web browser and configure MFA. For more information, see Multi-Factor Authentication.

2. Right-click the PrivX Agent icon in the notification area, and select Connections to connect to a target host.

   Provide the following connection settings and select Connect:

   • [Optional] Role: The PrivX role used for the connection. If the role is not selected, PrivX uses any applicable role.
   • Target: The target host.
   • Client: The native client used for the connection. Select PuTTY for SSH connections or PSFTP for SFTP connections.

   Alternatively, you can also connect directly from your SSH client.

Connecting with Certificates

Connecting through PrivX Agent requires user interaction and might not be suitable for machine-to-machine (M2M) use cases. For M2M use cases and automated access, applications can fetch ephemeral certificates from PrivX and use them to connect directly to SSH targets. This method requires integration with the PrivX SDK. The following instructions use the PrivX Python SDK.

Prerequisites

Before you begin, make sure that the following requirements are met:

• You are familiar with the PrivX Python SDK.
• A role, for example m2m_automation, is configured to access the target host with certificate authentication and includes the 'connections-authorize' permission. This permission enables access to fetch credentials from the Authorizer REST API.
  For more information, see Script-Based Certificate Authentication Setup.

IMPORTANT

Certificate authentication is not supported for accounts configured with --delegated-principals or --delegated-principals-all options.

M2M Certificate Connection Setup

To configure an M2M certificate connection:

1. In Administration → Deployment → Integrate with PrivX using API clients, create an API client.

2. Grant roles to this API client. In this example, grant the m2m_automation role with the 'connections-authorize' permission.

3. In Administration → Roles, enable the Use with PrivX agent parameter for the m2m_automation role.

4. Create a public and private key pair, or use an existing key pair.
   For example, id_rsa.pub/id_rsa under ~/.ssh.

5. Create a Python script similar to get_cert.py.
   Copy the contents of id_rsa.pub to the public_key value in the script for the API endpoint.

   tip

   Public keys generated with ssh-keygen are already Base64-encoded and do not require additional encoding. If PrivX does not accept the public key, remove the trailing = character and try again.

6. Run the script.
   If the request succeeds, PrivX returns two ephemeral certificates with different signature algorithms.

7. Save the returned certificate as id_rsa.cert.

8. Connect to the target host with the certificate:

   ssh -o CertificateFile=id_rsa.cert -i ~/.ssh/id_rsa targetuser@targethost

Enabling Proxy Protocol Support

Enable Proxy Protocol support if PrivX SSH Bastion is behind a nontransparent load balancer, such as HAProxy.

When Proxy Protocol support is enabled, PrivX SSH Bastion reads Proxy Protocol headers and uses the client IP address from the header as the original connection source. Without Proxy Protocol, PrivX SSH Bastion uses the remote IP address of the TCP connection.

To enable Proxy Protocol support, complete the following steps on all PrivX Servers:

1. In the PrivX SSH Bastion configuration file /opt/privx/etc/ssh-mitm.toml, set use_proxy_protocol to true.

2. [Optional] To require Proxy Protocol headers and restrict allowed client addresses, specify the addresses from which users connect to PrivX SSH Bastion in proxy_protocol_trusted_source_addresses.

3. Restart PrivX Server services to apply the changes.