SSH Connections with Native Clients

This section describes how to establish SSH connections with native clients.

Users can connect to target hosts/accounts using the SSH clients installed on their workstations, without needing to use the PrivX GUI. Connections are authenticated against PrivX. For example, if PrivX allows you to access a target account with certificate authentication, your native clients will also connect using certificate authentication without prompting you for target-account credentials.

The PrivX SSH bastion only supports the SSHv2 protocol. SSHv1 protocol is intentionally not supported due to its known security vulnerabilities.

Prerequisites

• Specify which roles may be used for SSH-native-client connections.

• Your PrivX license must have SSH Bastion feature enabled, see Licensable Features.

• After ugrading PrivX, you may need to re-download the extender-config.toml file for the native client connections to work with via Extenders. For more instructions about extender configuration file, see Setting up PrivX Components.

• For agent-based connections only:

  • The Use with PrivX agent option is enabled in the relevant users' roles, at Administration→Roles.

  • PrivX agent must be set up on the user's workstation. For instructions setting up PrivX agents, see PrivX-Agent Setup.

Connecting via PrivX Bastion

Using native SSH clients, you can connect to targets via PrivX SSH Bastion. By default PrivX SSH Bastion runs on port 2222. PrivX SSH Bastion provides the following 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 via ssh_config.

• Direct using privx-cmd: Similar to ProxyCommand, but supports OIDC users.

Connecting Interactively

To connect via PrivX Bastion interactively:

1. Connect to PrivX SSH Bastion using your PrivX account. For example, with ssh, sftp, or scp:

   $ ssh -p 2222 privxuser@privx.example.com

   $ sftp -P 2222 privxuser@privx.example.com

   $ scp -P 2222 local/path privxuser@privx.example.com:remote/path

   $ scp -P 2222 privxuser@privx.example.com:remote/path local/path

   Replace the example values as follows:

   • privxuser - Your PrivX-user name.

   • privx.example.com - Your PrivX-server address.

   • local/path - Local file/directory path for scp.

   • remote/path - Remote file/directory path for scp.

   Provide your PrivX-user password when prompted.

2. You will be presented with a list of possible targets. Select a target to connect to it.

Connecting Directly

To directly connect via PrivX Bastion, provide:

• Target-user name

• Target-host address

• PrivX-user name

• PrivX-server address

• (Optional) Extender name

• (Optional) Target port

By default bastion runs on your PrivX servers, port 2222.

Full bastion syntax is as follows:

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

Common case leaves out the extender and the target port, leaving the syntax as following:

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

Following are examples of ssh, scp and sftp usage with the connection string:

$ 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

Following is an example using PrivX Extender:

$ 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

If you use native-client connections with bastion syntax often, consider specifying the connection parameters in the users' client configuration (typically at /etc/ssh/ssh_config or ~/.ssh/config) using Host blocks. For example:

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

After which you can connect with much simpler syntax:

$ ssh targethost.example.com

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 you to log in to PrivX. For automated, scripted access, set up public-key authentication as described in Public-Key Authentication (SSH Bastion).

Connecting Directly Using ProxyCommand

Connecting directly via PrivX Bastion using ProxyCommand allows you to apply most configurations in the client-users' SSH configuration. This method requires you to use public-key authentication to PrivX Bastion. The SSH-client user must have an SSH keypair.

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 from 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 SSH client to use public-key authentication and a proxy when connecting to target hosts. These configuration options can be specified in the client-user's client configuration (typically at /etc/ssh/ssh_config or ~/.ssh/config), for example:

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

   In the example, replace privx.example.comwith your PrivX address.

   Note that the parameters your nc command accepts may be different from the example. You can substitute nc with another proxy command that supports http connect or SOCKS5/4a proxy protocol.

   By default PrivX Bastion listens for proxy connections on port 1080.

4. Connect to target. If you provided the configuration options in the client-user's client configuration:

   ssh targetuser@targethost

   Alternatively you may provide the configuration options 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

   Your connection will be routed via PrivX Bastion to the final target. Connection to PrivX Bastion is authenticated using public-key authentication.

Connecting Directly Using privx-cmd

privx-cmd can be found from the PrivX Agent package, available via Get PrivX software.

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:

• Users need to use the privx-cmd binary as the SSH ProxyCommand.
• Client machine must be capable of launching a browser for the user to login to PrivX.
• PrivX OIDC user needs to 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 from the Connections→Native Clients page.

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

   OpenSSH

   In the client configuration (typically at /etc/ssh/ssh_config or ~/.ssh/config), add settings similar to the following:

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

   In the example, replace privx.example.com with 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.

   PuTTY

   PuTTY supports local proxy command configuration under Connection→Proxy.

   1. Select Proxy Type: Local and specify privx-cmd in Telnet command, or local
      proxy command:

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

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

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

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

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

   In the example, replace privx.example.comwith your PrivX address. This command probes PrivX server's certificate, and - unless the certificate is signed by a trusted CA - prompts the user to accept the certificate. Accepted certificates are stored in ~/.privx/agent.json.

5. Connect to a target host:

   ssh targetuser@targethost

   This command performs the following:

   • If needed, privx-cmd launches a browser for the user to log into PrivX. Upon successful login privx-cmd gets an access token/refresh token. The refresh token is saved to ~/.privx/token.json for privx-cmd to reuse for later connections.
   • privx-cmd registers the user's public key as an authorized key to PrivX.
   • privx-cmd connects to SSH-Bastion's proxy port 1080, requests a connection to the target host, and starts forwarding data between the SSH client and SSH Bastion.

   Your connection to the final target is routed via PrivX Bastion. Connection to PrivX Bastion is authenticated using public-key authentication.

On subsequent SSH connections privx-cmd attempts to use the saved refresh token to fetch access tokens. If this succeeds the user is not required to re-login to PrivX, so no browsers are launched. Note that the command privx-cmd -command logout removes any saved refresh tokens from the file system, which forces the user to re-login on next SSH connection.

You can use privx-cmd command-line options to override the default values used in previous examples. This is required if, for example:

• You want to store your SSH keypair to another file.
• Do not want to save the refresh token to file system.
• Want to use a non-default browser for login.
• Your SSH-Bastion proxy listener hostname is different from your PrivX-server hostname.

Usage of privx-cmd:
  -browser string
        Command for launching browser
  -command string
        Command: connect, probe, logout (default "connect")
  -config string
        PrivX agent configuration file (default "~/.privx/agent.json")
  -d    Debug mode.
  -no-token
        Do not persist refresh token to file
  -privx string
        PrivX base URL
  -proxy-host string
        PrivX proxy hostname
  -proxy-port int
        PrivX proxy port (default 1080)
  -pub string
        SSH public key file (default "~/.ssh/id_privx.pub")
  -token string
        Token storage file (default "~/.privx/token.json")
  -v    Output version information and exit

Connecting without PrivX Bastion

Connecting via PrivX Agent

Linux and MacOS

After PrivX agent is set up for your workstation account, you can establish connections to targets using native clients with the agent. To do this on Linux or MacOS:

1. Log into the workstation as the user for whom native clients have been set up.

   You may verify that the agent is running with:

   $ privx-agent-ctl status

   The command should return a message similar to the following:

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

   If necessary, you can manually start the PrivX agent with:

   $ ./privx-agent-unix bash

2. Via the terminal, authenticate against PrivX using your PrivX credentials. For example (replace username with your PrivX user name):

   $ privx-agent-ctl login username

   You may verify your login status with:

   $ privx-agent-ctl status

   After entering your PrivX credentials correctly, your native SSH clients (such as ssh) will authenticate connections via PrivX. For a list of valid connection targets, run:

   $ privx-agent-ctl target list
   
   Accessible targets and granting roles:
   
     bilberry
         alice@10.1.55.144:222           Example Role 01
     ...

   You could then connect to one of the listed targets. In this example, by running:

   $ ssh alice@10.1.55.144 -p 222

Windows

After PrivX agent is set up for your workstation account, you can establish connections to targets using native clients with the agent. To do this on Windows:

1. Use the PrivX agent to authenticate with PrivX. To do this, right click the PrivX-agent tray icon, then click Login. Log in using your PrivX credentials. Complete multi-factor authentication if required.

1. To connect to a target host, right click PrivX agent tray icon, and click Connections.

   Provide the following connection settings:

   • Role (optional): You may choose to log in with the permissions of a specifc PrivX role. By default, you are logged in using any applicable role.

   • Target: The target host.

   • Client: The native client used for connecting; PuTTY for connecting through SSH or PSFTP through SFTP.

   After providing the connection settings, click Connect. Alternatively, you can directly use your SSH client for connecting.

Connecting with Certificate

Connecting via PrivX Agent requires user interaction, and may not be ideal for Machine-to-Machine (M2M) use cases. For M2M use cases, you may fetch ephemeral certificates to directly login to SSH targets. This approach requires some coding with PrivX SDK. These instructions use the PrivX Python SDK.

Prerequisites

• You are familiar with the PrivX Python SDK
• You have configured a role e.g. m2m_automation to access the target host with certificate authentication. See Script-Based Certificate-Authentication Setup

M2M Certificate-Connection Setup

1. Create an api client under Administration→Deployment→Integrate with PrivX using API clients.

2. Grant roles to this api client. In this example we grant the m2m_automation role.

3. Enable Use with PrivX agent for the m2m_automation role, at Administration→Roles.

4. Create public/private key pair or use existing ones, for example id_rsa.pub/id_rsa under ~/.ssh

5. Create a python script, similar to get_cert.py.

   You must provide your public_key for the API endpoint: copy the contents of your id_rsa.pub as the value.

6. Run the script. Upon success you will receive two ephemeral certificates with different signature algorithms.

7. Create an id_rsa.cert file by pasting the intended certificate to the file.

8. Run ssh -o CertificateFile=id_rsa.cert -i ~/.ssh/id_rsa targetusert@targethost. This will login to the target host with the ephemeral certificate.