Teleport Database Access: Replacing Static Database Credentials with Short-Lived mTLS Certificates

The problem with standing database credentials

Shared database passwords accumulate risk over time. They are copied into CI pipelines, developer laptops, and application configuration files. Rotation is difficult because every consumer must be updated simultaneously, and database-native logs usually record the shared account rather than the human who connected. Teleport Database Access addresses this by removing the long-lived secret from the workflow entirely.

The practical takeaway: a Teleport db_service agent registers each database with labels, an RBAC (role-based access control) role grants access based on those labels, and the auth service issues a short-lived client certificate. The database authenticates that certificate instead of a password. The user connects through a local mTLS tunnel built by tsh db connect.

How the mechanism works

Database Access sits between the user and the database. The agent runs the db_service and reports registered databases to the Teleport cluster. When a user requests a connection, the proxy checks the user's roles against the database's agent-reported labels. If the labels match, the auth service signs a short-lived certificate. tsh uses that certificate to open a mutually authenticated TLS (mTLS) tunnel to the database. Because the certificate expires quickly, a stolen credential has a narrow window of usefulness.

Worked example: read-only analyst access to PostgreSQL

The following example assumes PostgreSQL configured for certificate authentication. The database account must already exist; Teleport does not provision database users.

Register the database on the agent

On the host that runs the Teleport agent, edit teleport.yaml to register the database. Run this as the Teleport service user; the agent requires permission to read the configuration and reach the database endpoint.

db_service:
  enabled: true
  resources:
    - name: prod-analytics
      protocol: postgres
      uri: "postgres.example.internal:5432"
      labels:
        env: prod
        team: data

The labels map is the authorization surface. The name is what users reference in tsh. The uri is the database endpoint the agent reaches directly.

Grant access with a role

Create a role that matches the agent labels. Apply this with tctl or the web UI using cluster-admin credentials.

kind: role
version: v7
metadata:
  name: db-analyst
spec:
  allow:
    db_labels:
      env: prod
      team: data
    db_users:
      - analyst
    db_names:
      - "*"
  options:
    require_session_mfa: true

db_labels selects which registered databases are visible. db_users names the database account Teleport will request; that account must exist inside PostgreSQL and be configured to accept certificate authentication. db_names limits which databases inside the server are reachable. A wildcard "*" grants all names. Deny rules are evaluated against the same agent-reported label set and take precedence.

Connect and inspect the certificate

As the analyst user, run the following locally on the workstation:

tsh db connect prod-analytics --db-user=analyst

Teleport prints a local endpoint, typically on localhost, that is ready for a standard PostgreSQL client. The command holds the tunnel open for the lifetime of the certificate. On the same workstation, inspect what was issued:

openssl x509 -noout -text -in ~/.tsh/keys/proxy.example.com/certs/analytics.pem

Confirm the certificate identity matches the requested database user and that the validity period is short. The exact filename varies by cluster and proxy name; check the tsh db connect output for the path it references.

What the role does not control

Teleport authorization is connection-level. Once the tunnel is open, the user holds every privilege granted to the mapped database account. If analyst can read all tables, the Teleport role cannot restrict that to specific rows or columns. Sensitive access still requires least-privilege database accounts or in-database controls such as row-level security.

Supported engines and engine-specific authentication modes vary by Teleport version. PostgreSQL, MySQL, and MongoDB have different certificate requirements. Verify the exact protocol and authentication settings for your version before relying on certificate-only access.

Common mistakes and operational limits

Pointing GUI clients at the proxy

Many database GUI clients cannot speak the Teleport proxy protocol. Running tsh db connect produces a local mTLS endpoint, but a GUI tool may need a plain TLS endpoint instead. Use:

tsh proxy db prod-analytics --db-user=analyst

and configure the GUI client to connect to the local port that tsh proxy db prints. Pointing the client directly at the Teleport proxy host is a common failure mode; the proxy expects the Teleport client protocol, not a raw database wire protocol.

Forgetting certificate expiration

The issued certificate expires. When it does, the tunnel closes and the client must reconnect. Users need to re-login or run tsh db login to obtain a fresh certificate. Keep certificate TTLs short by default; this is the security benefit, but it means long-running queries or idle GUI sessions will drop.

Mislabeled agents

Label wildcards match the agent-reported label set, not the database's own notion of environment. If an operator registers a production database with env: staging, the RBAC rule will silently grant or deny the wrong population. Audit the db_service.resources labels on every agent.

Version and edition drift

Teleport major versions rename configuration fields and CLI flags. The kind: role version and the db_service block may differ across releases. Some capabilities, including per-session MFA defaults and moderated sessions, differ between Teleport Community and Enterprise editions. Run teleport version on the cluster and tsh version on the client to confirm both sides are the same major version before applying configuration.

Verification checklist

1. Run teleport version on the auth server and tsh version on the client. Confirm matching major versions.
2. As a test user with the role, run tsh db ls on the workstation and confirm only label-matching databases appear.
3. Run tsh db connect prod-analytics --db-user=analyst on the workstation and inspect the certificate with openssl x509 -noout -text for the expected identity and lifetime.
4. Check the Teleport audit log or session recording UI for the connect event to confirm identity attribution and that require_session_mfa was enforced.
5. Negative test: as a test user without the role, attempt tsh db connect from a workstation and confirm the denial happens at the proxy, not at the database.

Treat Teleport as the identity and audit layer, not the authorization layer. Map roles to narrowly scoped, pre-existing database accounts so that a broad Teleport grant cannot silently become broad data access.