Draft for guide to enable the Postgres Event driver **only**

[programmerq]

Guide to Configure PostgreSQL for Teleport Event Backend

This guide will help you configure PostgreSQL to serve as an event backend for Teleport. It focuses solely on setting up audit event storage without addressing cluster state storage or database access.

Prerequisites

• PostgreSQL 13 or later.
• Access to the PostgreSQL server and ability to modify postgresql.conf.
• Kubernetes environment if deploying with the Teleport Cluster Helm chart.
• openssl for generating certificates.

Steps:

1. Deploy PostgreSQL Service

   • Use your preferred method to deploy a PostgreSQL instance. Ensure PostgreSQL 13 or later is used.

2. Configure PostgreSQL's Host TLS Certificates

   • Generate the certificates

     Use your organization's standard practice for provisioning a TLS
     certificate for PostgreSQL. If you are using a certificate authority that is
     not trusted by default, you can include that in Teleport's configuration later
     so it can verify the certificate. This can be a letsencrypt certificate, a
     self-signed, or a cert signed by a traditional certificate authority.

     In this guide, we will refer to these certificates as:

     • postgres.example.com.crt - CN=postgres.example.com
     • postgres.example.com.key - private key for server.crt
     • server_ca.crt - the certificate authority that issued postgres.example.com.crt - this will not need to be installed in postgresql.conf

     We advise users to follow the Postgres documentation to set up host certificates if you do not have an existing certificate process: https://www.postgresql.org/docs/current/ssl-tcp.html#SSL-CERTIFICATE-CREATION. Note that they use 'intermediate.crt' as the filename for what we will refer to as 'server_ca.crt' later in the guide.

   • Generate and Install Host TLS Certificates

     Update postgresql.conf to use your TLS certificates:

     ssl = on
     
     # Install the host certificate that postgresql will present
     ssl_cert_file = '/path/to/postgres.example.com.crt'
     ssl_key_file = '/path/to/postgres.example.com.key'

     We will come back to this file later to allow the Postgres service to trust the client certificates

3. Create Necessary User for Teleport

   • Connect to PostgreSQL and create a user and database for audit events:

     CREATE USER teleport WITH PASSWORD 'your-password';
     CREATE DATABASE teleport_audit OWNER teleport;

     Ensure that the teleport user has a search_path that resolves to a schema that exists and allows that user to create tables.

4. Generate Client Certificate for Teleport Auth Service

   If you have a standard procedure for issuing client certificates in your environment, that is allowed. You can use a CA-signed client certificate, or a self-signed client certificate. We will use the following file names:

   • teleport-client.crt - CN=teleport - a cert that is allowed to connect as the teleport user created previously
   • teleport-client.key - private key for the teleport-client.crt certificate
   • client-ca.crt - the certificate authority that is the issuer for teleport-client.crt. In the case of self-signed, it will be the same file.

   • Generate a self-signed client certificate for the Teleport Auth Service:

     This command will give you a 10 year cert for the 'teleport' user.

     openssl req -x509 -newkey rsa:4096 -keyout teleport-client.key -out teleport-client.crt -days 3650 -nodes -subj "/CN=teleport" -addext "keyUsage=critical,digitalSignature,keyEncipherment" -addext "extendedKeyUsage=clientAuth"
     cp teleport-client.crt client-ca.crt

5. Configure PostgreSQL to Trust the Teleport Client Certificate

   • Update pg_hba.conf to require client certificates for connections to the Teleport database:

     # TYPE  DATABASE        USER            CIDR-ADDRESS            METHOD
     hostssl teleport_audit  teleport        0.0.0.0/0               cert
     hostssl teleport_audit  teleport        ::/0                    cert

   • Copy teleport-client.crt to the PostgreSQL server and point ssl_ca_file to it in postgresql.conf:

     ssl = on
     
     # Install the host certificate that postgresql will present
     ssl_cert_file = '/path/to/postgres.example.com.crt'
     ssl_key_file = '/path/to/postgres.example.com.key'
     
     # Trust clients that connect with a client cert signed by this certificate authority
     ssl_ca_file = '/path/to/client-ca.crt'

     Restart Postgres.

6. Test Connection String

   • Compose and test the connection string ensuring proper mutual TLS setup:

     psql "postgresql://teleport@database-address/teleport_audit?sslmode=verify-full&sslcert=/path/to/teleport-client.crt&sslkey=/path/to/teleport-client.key&sslrootcert=/path/to/server-ca.crt"

   • If the command connects successfully, proceed to configure Teleport.

7. Configure Teleport Auth Server

   • Update your teleport.yaml configuration file:

     teleport:
       storage:
         audit_events_uri:
           - postgresql://teleport@database-address/teleport_audit?sslmode=verify-full&sslcert=/path/to/teleport-client.crt&sslkey=/path/to/teleport-client.key&sslrootcert=/path/to/server-ca.crt
     

8. Deploying with Teleport Cluster Helm Chart

   • Create a Kubernetes secret with the client certificates and CA:

     kubectl create secret generic teleport-db-client-credentials --from-file=server-ca.cas --from-file=teleport-client.crt --from-file=teleport-client.key

   • Add extraVolumes and extraVolumeMounts entries to your Helm values:

     auth:
       extraVolumes:
         - name: teleport-db-client-credentials
           secret:
             secretName: teleport-db-client-credentials
       extraVolumeMounts:
         - name: teleport-db-client-credentials
           mountPath: /etc/teleport-db-client
           readOnly: true
       teleportConfig:
         teleport:
           storage:
             audit_events_uri:
               - postgresql://teleport@database-address/teleport_audit?sslmode=verify-full&sslcert=/path/to/teleport-client.crt&sslkey=/path/to/teleport-client.key&sslrootcert=/path/to/server-ca.crt

   • Deploy the Helm chart and monitor the logs:

     helm upgrade --install your-teleport-release teleport/teleport-cluster -f values.yaml
     kubectl logs -f deploy/your-teleport-release-auth

Diagram

graph TB
    subgraph postgres.conf
        direction TB
        A1[<code style="color:black">postgres.example.com.crt</code><br>Issuer: server_ca<br>Subject: postgres.example.com]
        A2[<code style="color:black">postgres.example.com.key</code><br>private key]
        D1[client-ca.crt<br>CA for teleport-client.crt]
        J1[<code>ssl_cert_file = '<i style="color:black">postgres.example.com.crt</i>'<br>ssl_key_file = '<i style="color:black">postgres.example.com.key</i>'<br>ssl_ca_file = '<i style="color:black">client-ca.crt</i>'</code>]
    end

    subgraph Teleport Auth Connection String
        direction TB
        C1[<code style="color:black">teleport-client.crt</code><br>Issuer: client_ca<br>Subject: teleport]
        J2["<b>Connection String</b></br><code>postgresql://teleport@database-address/teleport_audit?<br>sslmode=verify-full&<br>sslcert=<i style="color:black">teleport-client.crt</i>&<br>sslkey=<i style="color:black">teleport-client.key</i>&<br>sslrootcert=<i style="color:black">server-ca.crt</i></code>"]
        C2[<code style="color:black">teleport-client.key</code><br>private key]
        B1[<code style="color:black">server_ca.crt</code><br>CA for postgres.example.com.crt]
    end

    B1 -- "trust these server certs" --> A1
    D1 -- "trust these client certs" --> C1
    A1 <--> A2
    C1 <--> C2
    class J1,J2 file
    classDef file color:#666,text-align:left,fill:white

Loading

Documentation References

• PostgreSQL SSL Setup: PostgreSQL Documentation
• Teleport PostgreSQL Backend: Teleport Documentation
• Kubernetes Secrets: Kubernetes Documentation
• Helm Chart Configuration: Teleport Helm Chart

[programmerq]

This is a working draft, and will likely have several revisions. Share feedback if you find any issues!