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

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 from the Connections→Native Clients page.

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-user name.
   • 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, 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

   after that, you can connect with the following command:

   $ 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

For OIDC users, make sure Expire Implicit Roles are enabled for their OIDC directory. For other configurations, use 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 on the Connections→Native Clients page.

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. To work around this issue, choose one of the following options: install a newer version of the nmap-ncat package, install the BSD netcat package, or use the socat command.

Connecting Directly Using privx-cmd

Connecting directly via PrivX Bastion using privx-cmd allows users to perform a browser-based login, for example OIDC login, as part of the SSH native client connection. This method is similar to the Connecting Directly Using ProxyCommand method, with the following differences:

• The privx-cmd binary is used as the SSH ProxyCommand.
• The client machine has access to a web browser for PrivX login.
• 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.

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

3. Configure the SSH client to use privx-cmd as the ProxyCommand when connecting to target hosts in the configuration file. These configuration options can be specified in the client user's client configuration.

   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

   where privx.example.com is your PrivX address.

   In this example, the user's private and public key are stored in ~/.ssh/id_privx and ~/.ssh/id_privx.pub respectively.

   For PuTTY

   1. Under 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. Under 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 into PrivX. After successful login, privx-cmd gets an access token/refresh token. The refresh token is saved to ~/.privx/token.json, so that 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.

On subsequent SSH connections, privx-cmd attempts to use the saved refresh token to get access tokens. If this succeeds, 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.

Connecting without PrivX Bastion

Connecting with Certificates

For machine-to-machine (M2M) use cases, applications can fetch short-lived SSH certificates from PrivX and use them to connect directly to SSH targets. This method does not require PrivX SSH Bastion.

Use this method when you need automated access to SSH targets without interactive login. The implementation 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, which enables fetching access credentials from 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. Create an API client under Administration→Deployment→Integrate with PrivX using API clients.

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

3. Under Administration→Roles, enable Use with PrivX agent 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 your id_rsa.pub and use it in the script as the public_key value 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 asid_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 non-transparent 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, perform the following steps on all PrivX Servers:

1. In the SSH-Bastion configuration /opt/privx/etc/ssh-mitm.toml file, 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.