KeeperDB-Proxy

Passwordless zero-trust database access through Keeper tunnels using any native tools

Overview

KeeperDB is a fully-feature database management application that is built into the Keeper vault for interactive, passwordless zero-trust access to any managed database. KeeperDB-Proxy extends the capability of KeeperDB by providing customers with a zero trust connection using any native application, such as MySQL Workbench, Microsoft SQL Server Studio, DBeaver or proprietary software.

With KeeperDB-Proxy enabled, ephemeral database credentials flow directly from the Keeper Vault to the target database through the Gateway. Users simply connect their database client to a local port— no passwords required.

This feature is coming soon with the release of Keeper Gateway v1.8.0 and Vault 17.7. ETA March 2026

Key Benefits

Zero-Knowledge Database Access

• Users connect without seeing or entering credentials

• No copying/pasting passwords into database clients

• Credentials never exposed to clipboard or local applications

• True zero-knowledge access from vault to database

Session Management

• Idle timeout - automatically close inactive sessions

• Maximum duration - enforce session time limits

• Connection limits - control concurrent connections

• Enhanced logging - detailed session activity

Supported Databases

• MySQL

• PostgreSQL

• SQL Server

How It Works

1. User starts a database tunnel from Keeper Desktop

2. Gateway starts KeeperDB Proxy and retrieves credentials from the Vault

3. User connects their database client to localhost:<port> with no password

4. Proxy automatically authenticates to the target database

5. User has full database access without ever seeing credentials

Credential Security

• Never exposed to users - Credentials go directly from Vault to proxy to database

• Never stored on Gateway - Delivered per-session via secure handshake

• Never on clipboard - No copy/paste of sensitive passwords

• Audit trail - All access logged through Keeper

Activating KeeperDB-Proxy

Prerequisites

• Keeper Gateway version 1.8.0 or later

• PAM Database record configured with tunneling enabled

• See Setting up Tunnels for initial tunnel configuration

Enable the Proxy

1. Navigate to your PAM Configuration

2. Locate the Connection settings

3. Set allowKeeperDBProxy to true

4. Save your configuration

Once enabled, database tunnels using this configuration will provide credential-free access.

Note: If the proxy is unavailable, tunnels fall back to standard mode where users must enter credentials manually.

Ephemeral Accounts (JIT)

KeeperDB-Proxy supports Just-In-Time (JIT) ephemeral accounts for database access. Instead of using static credentials, a temporary database user is created on-demand and automatically deleted when the session ends.

How Ephemeral Accounts Work

1. User starts a tunnel to a database with JIT enabled

2. Gateway creates a temporary database user with a random username

3. Configured roles are assigned to the ephemeral user

4. Proxy authenticates using the ephemeral credentials

5. When the session ends, the user and role memberships are automatically cleaned up

Configuring Ephemeral Access

1. Enable JIT Ephemeral Accounts on your KeeperPAM resource record

2. Configure Group & Role Elevation:

   • Set Elevation Method to role

   • Set Elevation String to the database roles (comma-separated)

3. Ensure the roles exist on your target database with appropriate privileges

Creating Database Roles

Roles must exist on the database before they can be assigned. Example for MySQL:

-- Create a role
CREATE ROLE 'app_readonly';
-- Grant privileges to the role
GRANT SELECT ON mydb.* TO 'app_readonly';
-- For full access
CREATE ROLE 'app_admin';
GRANT ALL PRIVILEGES ON mydb.* TO 'app_admin';

MySQL Role Configuration

MySQL 8.0+ requires roles to be explicitly activated. For ephemeral accounts to work correctly:

Required MySQL Setting:

SET GLOBAL activate_all_roles_on_login = ON;

To make permanent, add to your MySQL configuration (my.cnf):

[mysqld]
activate_all_roles_on_login = ON

Without this setting, ephemeral users will have roles granted but not activated, resulting in no database access.

PostgreSQL and SQL Server

Unlike MySQL, PostgreSQL and SQL Server activate roles immediately upon grant—no additional configuration required.

Configuration

Default Behavior

• Idle timeout - Sessions close after 5 minutes of inactivity

• Max duration - Sessions are limited to 1 hour maximum

• Max connections - Up to 100 concurrent connections allowed

Environment Variables

• KEEPER_GATEWAY_DB_PROXY_IDLE_TIMEOUT_SECS

  • Description: Session idle timeout in seconds

  • Default: 300 (5 minutes)

• KEEPER_GATEWAY_DB_PROXY_MAX_DURATION_SECS

  • Description: Maximum session duration in seconds

  • Default: 3600 (1 hour)

• KEEPER_GATEWAY_DB_PROXY_MAX_CONNECTIONS

  • Description: Maximum concurrent connections allowed

  • Default: 100

• KEEPER_GATEWAY_DB_PROXY_MAX_QUERIES

  • Description: Maximum queries per session (0 = unlimited)

  • Default: 0

• KEEPER_GATEWAY_DB_PROXY_SINGLE_CONNECTION

  • Description: Enforce single connection per session

  • Default: false

Troubleshooting

Still prompted for credentials

Cause: Proxy may not be enabled or running

Solutions:

1. Verify allowKeeperDBProxy is enabled in PAM Configuration

2. Confirm Gateway version is 1.8.0 or later

3. Check Gateway logs for: Starting database proxy on-demand...

Fallback to manual authentication

Log message: Database proxy is enabled but not running - falling back to direct tunnel mode

Cause: Proxy failed to start. Tunnel works but requires manual credential entry.

Solutions:

1. Check Gateway logs for proxy startup errors

2. Verify the Gateway has the keeperdb-proxy component installed

3. Restart the Gateway if needed

Session disconnected unexpectedly

Possible causes:

• Idle timeout reached (default: 5 minutes)

• Max duration reached (default: 1 hour)

Solution: Adjust timeout settings for your use case.

FAQ

How do users connect if they don't have the password?

Users connect to localhost:<port> with no password or a placeholder. The proxy intercepts the connection and injects the real credentials automatically.

Can users still see credentials in the Vault?

Access to view credentials is controlled by Keeper permissions. Users can have tunnel access without permission to reveal passwords.

Does this work with all database clients?

Yes - MySQL Workbench, pgAdmin, Microsoft SQL Studio, Azure Data Studio, DBeaver, command-line clients, and any tool that connects via standard database protocols.

What happens if the proxy is unavailable?

Tunnels fall back to standard mode. Users can still connect but must enter credentials manually (if they have permission to view them in the vault).

Can I use ephemeral accounts with the proxy?

Yes. When JIT ephemeral accounts are enabled in the vault, the proxy creates a temporary database user for each session. The user is automatically deleted when the session ends. This provides the highest level of security since no persistent credentials exist.

Why does my ephemeral MySQL user have no access?

MySQL 8.0+ requires activate_all_roles_on_login = ON for roles to take effect automatically. Without this setting, roles are granted but not activated. See the Ephemeral Accounts section for configuration details.