teleport/docs/pages/database-access/guides/elastic.mdx

---
title: Database Access with Elasticsearch
description: How to configure Teleport Database Access with Elasticsearch.
---

<Details
  title="Version warning"
  opened={true}
  scope={["oss", "enterprise"]}
  scopeOnly={true}
  min="10.3"
>
  Database access for Elasticsearch is available starting from Teleport `10.3`.
</Details>

This guide will help you to configure secured access to an Elasticsearch database using Teleport Database Access.

## Prerequisites

(!docs/pages/includes/edition-prereqs-tabs.mdx!)

- A self-hosted Elasticsearch database. Elastic Cloud [does not support client certificates](https://www.elastic.co/guide/en/cloud/current/ec-restrictions.html#ec-restrictions-security), which are required for setting up Database Access.

- A host where you will run the Teleport Database Service. If you are already running the Teleport
  Database Service, you must ensure that it uses Teleport version 10.3 or newer in order to connect
  to Elasticsearch. <ScopedBlock scope={["oss", "enterprise"]}> This can also be the same instance
  of Teleport running your Auth and/or Proxy service(s).</ScopedBlock>

  See [Installation](../../installation.mdx) for details.

(!docs/pages/includes/tctl.mdx!)

## Step 1/5. Set up the Teleport Database Service

(!docs/pages/includes/database-access/token.mdx!)

Install Teleport on the host where you will run the Teleport Database Service. Make sure you've selected your installation type (OSS, Enterprise, Cloud):

(!docs/pages/includes/install-linux.mdx!)

Start the Teleport Database Service, pointing the `--auth-server` flag to the
address of your Teleport Proxy Service:

<Tabs>
<TabItem label="Standalone Binary">

<ScopedBlock scope={["oss", "enterprise"]}>

```code
$ teleport db start \
  --token=/tmp/token \
  --auth-server=teleport.example.com:3080 \
  --name=myelastic \
  --protocol=elastic \
  --uri=elasticsearch.example.com:9200 \
  --labels=env=dev
```

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

```code
$ teleport db start \
  --token=/tmp/token \
  --auth-server=mytennant.teleport.sh:443 \
  --name=myelastic \
  --protocol=elastic \
  --uri=elasticsearch.example.com:9200 \
  --labels=env=dev
```

</ScopedBlock>

<Admonition type="note">

The `--auth-server` flag must point to the Teleport cluster's Proxy Service
endpoint because the Database Service always connects back to the cluster over a
reverse tunnel.

</Admonition>

</TabItem>
<TabItem label="Config File">
Configure `teleport.yaml` using the example below:

<ScopedBlock scope={["cloud"]}>

```yaml
version: v3
teleport:
  auth_token: <insert token here>
  proxy_server: mytenant.teleport.sh:443

# disable services that are on by default
ssh_service: { enabled: no }
proxy_service: { enabled: no }
auth_service: { enabled: no }

# db service config
db_service:
  enabled: "yes"
  resources:
  - labels:
      "*": "*"
  databases:
  - name: myelastic
    protocol: elasticsearch
    uri: elasticsearch.example.com:9200
    static_labels:
      env: dev
```

</ScopedBlock>

<ScopedBlock scope={["oss", "enterprise"]}>

```yaml
version: v3
teleport:
  auth_token: <insert token here>
  proxy_server: teleport.example.com

# disable services that are on by default
ssh_service: { enabled: no }
proxy_service: { enabled: no }
auth_service: { enabled: no }

# db service config
db_service:
  enabled: "yes"
  resources:
  - labels:
      "*": "*"
  databases:
  - name: myelastic
    protocol: elasticsearch
    uri: elasticsearch.example.com:9200
    static_labels:
      env: dev
```

</ScopedBlock>

Adjust for your environment, then start or restart Teleport. See the [YAML reference](../reference/configuration.mdx) for details.

</TabItem>
</Tabs>

## Step 2/5. Create a Teleport user

(!docs/pages/includes/database-access/create-user.mdx!)

## 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.

```code
$ 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
  }
}
'
```

<Details title="Role Mapping with wildcards" opened={false}>

In a scenario where Teleport is using [single sign-on](../../access-controls/sso.mdx) you may want to define a mapping for all users to a role:

```code
$ 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
  }
}
'
```

</Details>

## Step 4/5. Set up mutual TLS

(!docs/pages/includes/database-access/tctl-auth-sign.mdx!)

We will show you how to use `tctl auth sign` below.

To securely access your Elasticsearch database, sign the certificate for the hostname Teleport will
connect to.

For example, if your Elasticsearch server is accessible at `elastic.example.com`,
run:

```code
$ tctl auth sign --format=elasticsearch --host=elastic.example.com --out=elastic --ttl=2160h
Database credentials have been written to elastic.key, elastic.crt, elastic.cas.
```

(!docs/pages/includes/database-access/ttl-note.mdx!)

The command will create three files:

- `elastic.cas` with Teleport's certificate authority
- `elastic.key` with a generated private key
- `elastic.crt` with a generated host certificate

(!docs/pages/includes/database-access/rotation-note.mdx!)

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

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

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

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:

<Tabs>
  <TabItem label="Self-Hosted">
    ```code
    $ 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
    ```
  </TabItem>
  <TabItem label="Teleport Cloud">
    ```code
    $ 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
    ```
  </TabItem>
</Tabs>

To connect to a particular database instance:

```code
$ tsh db connect myelastic --db-user=alice
```

To log out of the database and remove credentials:

```code
#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:

```code
$ 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:

![ElasticVue](../../../img/database-access/guides/elasticvue.png)

## Next steps

(!docs/pages/includes/database-access/guides-next-steps.mdx!)
- For more information on configuring security settings in Elasticsearch, see:
[Security settings in Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html)