Database Access with Elasticsearch

Teleport can provide secure access to Elasticsearch via the Teleport Database Service. This allows for fine-grained access control through the Teleport RBAC system.

The Teleport Database Service proxies traffic from database clients to self-hosted databases in your infrastructure. Teleport maintains a certificate authority for database clients. You configure your database to trust the Teleport database client CA, and the Teleport Database Service presents certificates signed by this CA when proxying user traffic. With this setup, there is no need to store long-lived credentials for self-hosted databases.

Meanwhile, the Teleport Database Service verifies self-hosted databases by checking their TLS certificates against either the Teleport database CA or a custom CA chosen by the user.

In this guide, you will:

1. Configure your Elasticsearch database for Teleport access.
2. Add the database to your Teleport cluster.
3. Connect to the database via Teleport.

How it works

The Teleport Database Service authenticates to your self-hosted Elasticsearch database using mutual TLS. Elasticsearch trusts the Teleport certificate authority for database clients, and presents a certificate signed by either the Teleport database CA or a custom CA. When a user initiates a database session, the Teleport Database Service presents a certificate signed by Teleport. The authenticated connection then proxies client traffic from the user.

Prerequisites

• A running Teleport cluster version 17.0.0-dev or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• The tctl admin tool and tsh client tool.

  Visit Installation for instructions on downloading tctl and tsh.

• A self-hosted Elasticsearch database. Elastic Cloud does not support client certificates, which are required for setting up the Database Service.

• A host where you will run the Teleport Database Service.

  See Installation for details.

• Optional: a certificate authority that issues certificates for your self-hosted database.

• To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials.

  For example:

  tsh login --proxy=teleport.example.com --user=email@example.com
  tctl status
  Cluster  teleport.example.com
  Version  17.0.0-dev
  CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

  If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/5. Set up the Teleport Database Service

The Database Service requires a valid join token to join your Teleport cluster. Run the following tctl command and save the token output in /tmp/token on the server that will run the Database Service:

tctl tokens add --type=db --format=text
abcd123-insecure-do-not-use-this

Install and configure Teleport where you will run the Teleport Database Service:

sudo teleport db configure create \   -o file \   --token=/tmp/token \   --proxy=example.teleport.sh \   --name=myelastic \   --protocol=elastic \   --uri=elasticsearch.example.com:9200 \   --labels=env=dev 

sudo teleport db configure create \   -o file \   --token=/tmp/token \   --proxy=example.teleport.sh:443 \   --name=myelastic \   --protocol=elastic \   --uri=elasticsearch.example.com:9200 \   --trust_system_cert_pool \   --labels=env=dev

sudo systemctl enable teleport
sudo systemctl start teleport

sudo teleport install systemd -o /etc/systemd/system/teleport.service
sudo systemctl enable teleport
sudo systemctl start teleport

helm repo add teleport https://charts.releases.teleport.dev

helm repo update

roles: db
proxyAddr: example.teleport.sh
# Set to false if using Teleport Community Edition
enterprise: true
authToken: "JOIN_TOKEN"
databases:
  - name: myelastic
    uri: elasticsearch.example.com:9200
    protocol: elastic
    static_labels:
      env: dev

Step 2/5. Create a Teleport user

tctl users add \  --roles=access \  --db-users="*" \  --db-names="*" \  alice

tctl users add \  --roles=access,requester \  --db-users="*" \  --db-names="*" \  alice

For more detailed information about database access controls and how to restrict access see RBAC documentation.

Step 3/5. Create a role mapping

Define a role mapping in Elasticsearch to assign your Teleport user(s) or role(s) to an Elasticsearch role. The example below maps the Teleport user alice to the user role in Elasticsearch.

curl -u elastic:your_elasticsearch_password -X POST "https://elasticsearch.example.com:9200/_security/role_mapping/mapping1?pretty" -H 'Content-Type: application/json' -d'
{  "roles": [ "user"],  "enabled": true,  "rules": {    "field" : { "username" : "alice" }  },  "metadata" : {    "version" : 1  }}'

curl -u elastic:your_elasticsearch_password -X POST "https://elasticsearch.example.com:9200/_security/role_mapping/mapping1?pretty" -H 'Content-Type: application/json' -d'
{  "roles": [ "monitoring"],  "enabled": true,  "rules": {    "field" : { "username" : "*@example.com" }  },  "metadata" : {    "version" : 1  }}'

Step 4/5. Set up mutual TLS

Teleport uses mutual TLS authentication with self-hosted databases. These databases must be able to verify certificates presented by the Teleport Database Service. Self-hosted databases also need a certificate/key pair that Teleport can verify.

By default, the Teleport Database Service trusts certificates issued by a certificate authority managed by the Teleport Auth Service. You can either:

• Configure your self-hosted database to trust this CA, and instruct Teleport to issue a certificate for the database to present to the Teleport Database Service.
• Configure the Database Service to trust a custom CA.

Use the generated secrets to enable mutual TLS in your elasticsearch.yml configuration file:

xpack.security.http.ssl:
  certificate_authorities: /path/to/server.cas
  certificate: /path/to/server.crt
  key: /path/to/server.key
  enabled: true
  client_authentication: required
  verification_mode: certificate

xpack.security.authc.realms.pki.pki1:
  order: 1
  enabled: true
  certificate_authorities: /path/to/server.cas

Restart Elasticsearch to enable this configuration. Once mutual TLS has been enabled, you will no longer be able to connect to the cluster without providing a valid client certificate. You can set xpack.security.http.ssl.client_authentication to optional to allow connections from clients that do not present a certificate, using other methods like username and password.

Step 5/5. Connect

Log into your Teleport cluster and see available databases:

tsh login --proxy=teleport.example.com --user=alice
tsh db ls
Name                        Description Allowed Users Labels  Connect--------------------------- ----------- ------------- ------- ------------------------> myelastic (user: elastic)             [*]           env=dev tsh db connect myelastic

tsh login --proxy=mytennant.teleport.sh --user=alice
tsh db ls
Name                        Description Allowed Users Labels  Connect--------------------------- ----------- ------------- ------- ------------------------> myelastic (user: elastic)             [*]           env=dev tsh db connect myelastic

To connect to a particular database instance:

tsh db connect myelastic --db-user=alice

To log out of the database and remove credentials:

Remove credentials for a particular database instance.
tsh db logout myelastic
Remove credentials for all database instances.
tsh db logout

Tunneled connection example

We can create a tunneled connection to Elasticsearch to use with GUI applications like Elasticvue:

tsh proxy db myelastic --db-user=alice --tunnel
Started authenticated tunnel for the Elasticsearch database "myelastic" in cluster "teleport.example.com" on 127.0.0.1:53657.
Use one of the following commands to connect to the database:
  * interactive SQL connection: 
  $ elasticsearch-sql-cli http://localhost:53657/
  * run single request with curl: 
  $ curl http://localhost:53657/

Note the assigned port, and provide it to your GUI client:

Next steps

• Learn how to restrict access to certain users and databases.

• View the High Availability (HA) guide.

• Take a look at the YAML configuration reference.

• See the full CLI reference.

• For more information on configuring security settings in Elasticsearch, see: Security settings in Elasticsearch