Introduction to Teleport

Teleport is an open-source access platform designed to enhance security and ease of access for infrastructure components such as servers, Kubernetes clusters, and databases. It provides features like identity-based access management, session recording, and role-based access control (RBAC). Teleport simplifies the process of securing access to resources while ensuring compliance with modern security standards.

Teleport is particularly useful for managing access to databases, allowing users to securely connect to PostgreSQL and other databases without exposing them directly to the public internet. It supports mutual TLS authentication, Single Sign-On (SSO), and just-in-time access provisioning.

In this guide, we will configure Teleport Community Edition to securely connect to a local PostgreSQL database. The steps include setting up Teleport, configuring TLS authentication, defining roles, and establishing a secure connection.

How Teleport Works

Teleport operates as a proxy-based authentication system, meaning all connections pass through a Teleport Proxy Service, which handles authentication and authorization. The Auth Service issues short-lived certificates, which are then used for accessing the infrastructure securely.

For a more in-depth understanding, refer to the official documentation: How Teleport Works.

Step 1: Basic Configuration

Run the following command to generate a default Teleport configuration file:

sudo teleport configure | sudo tee /etc/teleport.yaml

This command generates a configuration file (teleport.yaml) with default settings and stores it in /etc/teleport.yaml.

Step 2: Start and Enable the Teleport Service

sudo systemctl start teleport
sudo systemctl enable teleport

start ensures the Teleport service is running.
enable ensures Teleport starts automatically on system reboot.

Step 3: Create an Admin User

sudo tctl users add admin --roles=access,editor,auditor --logins=root

Output :

User "admin" has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h:
https://localhost:3080/web/invite/488f6cb892809e3d737cb84926c2ab30

Step 4: Generate & Configure Certificates for PostgreSQL TLS Mode

sudo tctl auth sign --format=db --host=localhost --out=server --ttl=2190h --insecure

Output :

Database credentials have been written to server.key, server.crt, server.cas.
To enable mutual TLS on your PostgreSQL server, add the following to its postgresql.conf configuration file:

ssl = on
ssl_cert_file = '/path/to/server.crt'
ssl_key_file = '/path/to/server.key'
ssl_ca_file = '/path/to/server.cas'

These certificates enable mutual TLS authentication for PostgreSQL

These three generated files for the server.crt , server.key & server.cas move to the dir : /var/lib/postgresql/16/main

Update PostgresSQL Configuration(postgresql.conf):

ssl = on
ssl_cert_file = '/var/lib/postgresql/16/main/server.crt'
ssl_key_file = '/var/lib/postgresql/16/main/server.key'
ssl_ca_file = '/var/lib/postgresql/16/main/server.cas'

Update PostgresSQL Authentication(pg_hba.conf):

hostssl all all ::/0 cert
hostssl all all 0.0.0.0/0 cert

Set correct file ownership:

sudo chown postgres:postgres /var/lib/postgresql/16/main/server.*

Step 5: Configure Teleport Roles for Database Access

Create a roles.yaml file:

kind: role
version: v4 
metadata:
  name: db
spec:
  allow:
    db_labels:
      '*': '*'
    db_names:
      - '*'
    db_users:
      - '*'

Apply the role:

sudo tctl create -f roles.yaml --insecure

Also, from the UI of Teleport, add the ‘db’ user to the roles section.

Step 6: Generate Authentication Token

sudo tctl tokens add --type=db --insecure

Output :

Generated token: 3cbcf1add7a989089e3577488b4c1374

teleport db configure create \
   --token=3cbcf1add7a989089e3577488b4c1374 \ --ca-pin=sha256:876056245dc1f6a114660c304dc64ced953f7f11d681d0c207db57829b499209 \
   --proxy=localhost:3080 \
   --name=postgres \
   --protocol=postgres \
   --uri=localhost:5432 \
   --output file:///etc/teleport.yaml

This token allows the database to authenticate with Teleport.

Step 7: Configure Database Proxy

Create a script:

echo "#!/usr/bin/env sh
teleport db configure create \
   --token=3cbcf1add7a989089e3577488b4c1374 \
   --ca-pin=sha256:876056245dc1f6a114660c304dc64ced953f7f11d681d0c207db57829b499209 \
   --proxy=localhost:3080 \
   --name=postgres \
   --protocol=postgres \
   --uri=localhost:5432 \
   --output file:///etc/teleport.yaml" > create-db-proxy.sh

Set executable permissions:

sudo chmod +x create-db-proxy.sh

Run the script:

sudo ./create-db-proxy.sh

Step 8: Start Teleport with the New Configuration

sudo teleport start -c /etc/teleport.yaml --insecure

This starts the Teleport service with the provided configuration.

In the new terminal, log in as the Teleport admin role to perform the following operations :

Step 9: List Available Databases

tsh db ls

Output :

Name      Description  Labels  
--------  -----------  ------
postgres

Step 10: Connect to PostgreSQL via Teleport

tsh db login --db-user=postgres --db-name=postgres postgres --insecure

Output :

Connection information for database "postgres" has been saved.

You can now connect to it using the following command:

  tsh db connect Postgres

You can view the connect command for the native database CLI client:

  tsh db config --format=cmd postgres

Connect to the database:

tsh db connect postgres --db-user=postgres --db-name=postgres --insecure

Output :

This enters the PostgreSQL database securely using Teleport authentication.

Why Use `--insecure` in Commands?

Many of the commands in this guide use the --insecure flag. This flag is typically used when connecting to a local development instance where strict security is not a priority. In production environments, it is recommended to use secure settings with properly configured TLS certificates to avoid potential security risks.

Conclusion

In this guide, we successfully set up Teleport to provide secure access to a PostgreSQL database using mutual TLS authentication. By configuring authentication tokens, certificates, and role-based access control, we ensured a secure and efficient database connection without relying on traditional passwords. Teleport simplifies database access while enhancing security through identity-based authentication and auditing.