Database Connections with Native Clients

This section describes how to establish database connections with native clients through PrivX.

Users can connect to databases through SSH tunnels between the client and PrivX SSH bastion. PrivX controls the access to target databases based on user's roles, and - depending on the used database wire protocol - injects the target database user credentials to the protocol stream or forwards the unmodified protocol stream to the target database server.

These instructions are visible for end users in the PrivX UI when clicking an accessible DB connection target under Connections -> Hosts.

Prerequisites

Your PrivX license must have Database Access feature enabled, see Licensable Features.
Target database has been configured as a host DB service and database user has been configured as a host account with a role granting access for the PrivX user

Connecting to PrivX SSH Bastion

The SSH connection to PrivX SSH bastion is established as described in SSH Connections with Native Clients. Use SSH client command line options or SSH configuration directives to request tunneling to the target database.

When connecting interactively, choose "PrivX SSH Bastion" from the interactive target list:

$ ssh -p 2222 privxuser@privx.example.com -L 5432:target-db.example.com:5432
privxuser
PrivX SSH Bastion @ privx.example.com
privx > Enter privxuser's password
(privxuser@privx.example.com) privx > Password: 
privxuser
privx > Showing targets 1-10
          1:  privxuser@privx.example.com (PrivX SSH Bastion)
(privxuser@privx.example.com) privx > Select target (1-10), enter target (user@hostname), (N)ext or search (? <keywords>): 1

When connecting directly, use the bastion syntax:

$ ssh -p 2222 privxuser%privx.example.com%privxuser@privx.example.com -L 5432:target-db.example.com:5432

SSH connections can be authenticated with:

Password, with MFA optionally.
Authorized keys.
OIDC either when session passwords are enabled or when PrivX does not manage the target-database user credentials. For more information about enabling session passwords, see Session Password Authentication.

Once the SSH connection is authenticated, you will see the PrivX Bastion CLI prompt:

Welcome to PrivX SSH Bastion CLI

Type 'help' for list of available CLI commands.

cli> help
commands:
connections      List open tunneled connections
sessionpw        Show session password
exit             Exit network target access shell
help             Display this help
cli>

The SSH tunnel is now connected and the SSH client listens for incoming connections on the requested listener port.

SSH client is not required to open the shell channel for tunneling to work. This may be useful in some machine-to-machine use cases. Refer to your SSH client documentation on how to disable the shell channel.

If session passwords are enabled for the user directory, then the PrivX Bastion CLI command sessionpw can be used for checking out the session password.

Connecting to Target Database

Connect the native database client to SSH client's local listener port providing the target database username and optional database name to the database client.

Connecting to Target Database with PrivX managed Credentials

If the database client and target database server use either MySQL or PostgreSQL wire protocol, PrivX can manage the database user credentials. In this use case the host DB service is configured to use the MySQL or PostgreSQL protocol, the host account type is Explicit and the database user password has been configured to the host account.

When connecting the database client, you provide the PrivX user password (or session password) when the database client prompts it. PrivX authenticates the database client connection and replaces the target database user password in the protocol stream.

$ psql -h localhost -p 5432 -U dbuser dbname
Password for user dbuser: 
psql (14.8 (Ubuntu 14.8-0ubuntu0.22.04.1))
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_128_GCM_SHA256, bits: 128, compression: off)
Type "help" for help.

dbname=#

Connecting to Target Database in Passthrough Mode

The host DB service can be configured to use one of two passthrough modes as the protocol:

Passthrough: forward the unmodified database protocol stream to target database server
TLS: terminate the client initiated TLS connection, establish a TLS connection to database server and forward the decrypted database protocol stream between the TLS connections

In both passthrough modes PrivX does not manage the target database user credentials. Thus the end user is required to know the database user password. In this use the host DB service is configured with the appropriate passthrough mode and the host account type is User-defined.

When connecting the database client, you provide the target database user password when the database client prompts it.

When using passthrough modes, by default all bytes in the protocol stream are session recorded. Typically the database user credentials are sent in the start of the protocol stream. To avoid the credentials ending up in the session recording, instruct PrivX to omit recording the authentication phase of the protocol stream by setting a suitable value for Audit Skip (Bytes) in the host DB service.

With MySQL and PostgreSQL protocols the authentication phase is implicitly omitted from the session recording.

Verifying PrivX Database Proxy TLS Certificate

When using MySQL, PostgreSQL protocols or TLS mode, the database client is required to use TLS to encrypt the communication. For TLS connections, PrivX generates TLS server certificates using the "PrivX Database Proxy CA" keypair.

Depending on database client configuration, the client may verify the server TLS certificate and may require that the server TLS certificate has been issued by a trusted CA. For this purpose the "PrivX Database Proxy CA" certificate can be copied from PriVX UI under Monitoring -> Certificates.

Refer to your database client documentation on how to configure it to verify and accept server TLS certificates issued by a trusted CA, and how to configure trusted CAs.