Teleport

Database Access with AWS OpenSearch

OpenSource
Enterprise
Cloud

Access to AWS OpenSearch can be provided by Teleport Database Access. This allows for fine-grain access control through Teleport's RBAC.

This guide will help you to:

Install the Teleport Database Service.
Set up the Teleport Database Service to access AWS OpenSearch Service via REST API.
Connect to your AWS OpenSearch Service through the Teleport Database Service.

Prerequisites

AWS OpenSearch domain.
Enabled AWS OpenSearch Service fine-grained access control
IAM permissions to create IAM roles.
opensearchsql Command Line Interface (CLI) tool installed in $PATH.

A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.
The tctl admin tool and tsh client tool version >= 13.0.3.
```
tctl version
Teleport v13.0.3 go1.20
tsh version
Teleport v13.0.3 go1.20
```
See Installation for details.

A running Teleport Enterprise cluster. For details on how to set this up, see our Enterprise Getting Started guide.
The Enterprise tctl admin tool and tsh client tool version >= 13.0.3, which you can download by visiting your Teleport account.
```
tctl version
Teleport Enterprise v13.0.3 go1.20
tsh version
Teleport v13.0.3 go1.20
```

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

A host, e.g., an EC2 instance, where you will run the Teleport Database Service. This guide assumes an EC2 instance when creating and applying IAM roles, and must be adjusted accordingly for custom configurations.
Make sure you can connect to Teleport. Log in to your cluster using tsh, then use tctl remotely:
```
tsh login --proxy=teleport.example.com [email protected]
tctl status
Cluster  teleport.example.com
Version  13.0.3
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
You can run subsequent tctl commands in this guide on your local machine.
For full privileges, you can also run tctl commands on your Auth Service host.

Example Access Control

This guide provides an example configuration of IAM access roles as a model, and uses an EC2 instance to serve the Teleport Database Service. The level of access provided may not suit your needs, or may not fit your organization's access conventions. You should adjust the AWS IAM permissions to fit your needs.

Step 1/4. Create IAM roles for OpenSearch Managed Cluster access

The setup described in this guide requires two IAM roles:

One associated with the EC2 instance running the Teleport Database Service, which lets it assume additional roles granted to the user.
One that can be assumed by the EC2 instance role and grants access to OpenSearch manage cluster to users.

EC2 instance role

Visit the IAM > Roles page of the AWS Console, then press "Create Role". Under Trusted entity type select "AWS service". Under Use case select "EC2", then click Next.

On the "Add Permissions" page, you can simply click Next since this role does not require any permissions. In this guide, we will use the example name TeleportDatabaseService for this role. Once you have chosen a name, click Create Role to complete the process.

OpenSearch Mange Cluster access role

Navigate back to the Roles page and create a new role. Select the "AWS account" option, which creates a default trust policy to allow other entities in this account to assume this role:

Click Next. On the next page, enter a role name. In this guide we'll use the example name ExampleTeleportOpenSearchRole for this role.

Under "Select trusted entities", update the JSON to allow the TeleportDatabaseService role to assume this role:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    "arn:aws:iam::abcd1234-this-is-an-example:role/TeleportDatabaseService"
                ]
            },
            "Action": "sts:AssumeRole",
            "Condition": {}
        }
    ]
}

Finally, click Create Role.

Configure Cluster Fine-grained access control IAM Role mapping in Amazon OpenSearch Managed Custer

Teleport AWS OpenSearch service integration leverages the OpenSearch Fine-grained access control where the IAM role or user is mapped to the OpenSearch role.

In order to configure Role Mapping log into OpenSearch Domain Dashboard using the master user and go to the Security settings:

Create a new role with least privilege permissions, or select an existing one. For the purpose of this example the readall OpenSearch role will be used. Select the OpenSearch role and go to the Mapped users tab:

Add mapping between the OpenSearch role and AWS IAM ExampleTeleportOpenSearchRole role created in the previous step.

Finally, click the Map button to apply the settings.

Step 2/4. Configure the Teleport IAM role mapping

The next step is to give your Teleport users permissions to assume AWS IAM roles when accessing AWS resources through your Teleport cluster.

You can do this by creating a Teleport role with the db_users field listing the IAM role ARN created in the previous step. Create a file called aws-opensearch-access.yaml with the following content:

kind: role
version: v6
metadata:
  name: aws-opensearch-access
spec:
  allow:
    db_labels:
      'env': 'dev'
    db_users:
    - 'ExampleTeleportOpenSearchRole'

Create the new role:

tctl create -f aws-opensearch-access.yaml

Assign the aws-opensearch-access role to your Teleport user by running the following commands, depending on whether you authenticate as a local Teleport user or via the github, saml, or oidc authentication connectors:

Retrieve your local user's configuration resource:

tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml

Edit out.yaml, adding aws-opensearch-access to the list of existing roles:

  roles:
   - access
   - auditor
   - editor
+  - aws-opensearch-access

Apply your changes:

tctl create -f out.yaml

Retrieve your github configuration resource:

tctl get github/github --with-secrets > github.yaml

Edit github.yaml, adding aws-opensearch-access to the teams_to_roles section. The team you will map to this role will depend on how you have designed your organization's RBAC, but it should be the smallest team possible within your organization. This team must also include your user.

Here is an example:

  teams_to_roles:
    - organization: octocats
      team: admins
      roles:
        - access
+       - aws-opensearch-access

Apply your changes:

tctl create -f github.yaml

Warning

Note the --with-secrets flag in the tctl get command. This adds the value of spec.signing_key_pair.private_key to github.yaml. This is a sensitive value, so take precautions when creating this file and remove it after updating the resource.

Retrieve your saml configuration resource:

tctl get --with-secrets saml/mysaml > saml.yaml

Edit saml.yaml, adding aws-opensearch-access to the attributes_to_roles section. The attribute you will map to this role will depend on how you have designed your organization's RBAC, but it should be the smallest group possible within your organization. This group must also include your user.

Here is an example:

  attributes_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - aws-opensearch-access

Apply your changes:

tctl create -f saml.yaml

Warning

Note the --with-secrets flag in the tctl get command. This adds the value of spec.signing_key_pair.private_key to saml.yaml. This is a sensitive value, so take precautions when creating this file and remove it after updating the resource.

Retrieve your oidc configuration resource:

tctl get oidc/myoidc --with-secrets > oidc.yaml

Edit oidc.yaml, adding aws-opensearch-access to the claims_to_roles section. The claim you will map to this role will depend on how you have designed your organization's RBAC, but it should be the smallest group possible within your organization. This group must also include your user.

Here is an example:

  claims_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - aws-opensearch-access

Apply your changes:

tctl create -f oidc.yaml

Warning

Note the --with-secrets flag in the tctl get command. This adds the value of spec.signing_key_pair.private_key to oidc.yaml. This is a sensitive value, so take precautions when creating this file and remove it after updating the resource.

Log out of your Teleport cluster and log in again to assume the new role.

Step 3/4. Install the Teleport Database Service

Create an EC2 instance to host the Teleport Database Service, and attach the TeleportDatabaseService AWS IAM role to it. If you're hosting the service another way, you must provide AWS credentials to the service - see AWS credentials configuration for more details.

non-standard AWS regions

For non-standard AWS regions such as AWS GovCloud (US) regions and AWS China regions, please set the corresponding region in the AWS_REGION environment variable or in the AWS credentials file so that the Database Service can use the correct STS endpoint.

Generate a token

For users with a lot of infrastructure in AWS, or who might create or recreate many instances, consider alternative methods for joining new EC2 instances running Teleport:

The Database Service requires a valid auth token to connect to the cluster. Generate one by running the following command against your Teleport Auth Service and save it in /tmp/token on the node that will run the Database Service:

tctl tokens add --type=db

Use the token provided by the output of this command in the next step.

Install and start Teleport

Install Teleport on the host where you will run the Teleport Database Service. See our Installation page for options besides Linux servers.

Use the appropriate commands for your environment to install your package.

Teleport Edition

Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc
Source variables about OS version
source /etc/os-release
Add the Teleport APT repository for v13. You'll need to update this
file for each major release of Teleport.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v13" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null
sudo apt-get update
sudo apt-get install teleport

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for v13. You'll need to update this
file for each major release of Teleport.
sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v13/teleport.repo")"
sudo yum install teleport
Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for v13. You'll need to update this
file for each major release of Teleport.
Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v13/teleport.repo")"
Install teleport
sudo dnf install teleport
Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

In the example commands below, update $SYSTEM_ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

curl https://get.gravitational.com/teleport-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gz
shasum -a 256 teleport-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gz
cd teleport
sudo ./install

Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc
Source variables about OS version
source /etc/os-release
Add the Teleport APT repository for v13. You'll need to update this
file for each major release of Teleport.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v13" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null
sudo apt-get update
sudo apt-get install teleport-ent

For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

sudo apt-get install teleport-ent-fips

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for v13. You'll need to update this
file for each major release of Teleport.
sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v13/teleport.repo")"
sudo yum install teleport-ent
Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

sudo yum install teleport-ent-fips

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for v13. You'll need to update this
file for each major release of Teleport.
Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v13/teleport.repo")"
Install teleport
sudo dnf install teleport-ent
Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

sudo dnf install teleport-ent-fips

In the example commands below, update $SYSTEM_ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

curl https://get.gravitational.com/teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gz
shasum -a 256 teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gz
cd teleport-ent
sudo ./install

For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:

curl https://get.gravitational.com/teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-fips-bin.tar.gz
shasum -a 256 teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-fips-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-fips-bin.tar.gz
cd teleport-ent
sudo ./install

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

On the host where you will run the Teleport Database Service, start Teleport with the appropriate configuration.

Note that a single Teleport process can run multiple different services, for example multiple Database Service agents as well as the SSH Service or Application Service. The step below will overwrite an existing configuration file, so if you're running multiple services add --output=stdout to print the config in your terminal, and manually adjust /etc/teleport.yaml.

Generate a configuration file at /etc/teleport.yaml for the Database Service:

teleport db configure create \   -o file \   --token=/tmp/token \   --proxy=proxy-address \   --name=example-opensearch \   --protocol=opensearch \   --uri=your-opensearch-domain-url.eu-central-1.es.amazonaws.com:443 \   --aws-account-id=abcd1234-this-is-an-example  \   --labels=env=dev

On the host where you will run , start Teleport:

sudo systemctl enable teleport
sudo systemctl start teleport

On the host where you will run , create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport:

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

Modify your Teleport Database Service static configuration file:

db_service:
  enabled: "yes"
  databases:
  - name: example-opensearch
    aws:
      account_id: "abcd1234-this-is-an-example"
    protocol: opensearch
    uri: your-opensearch-domain-url.eu-central-1.es.amazonaws.com:443
    static_labels:
      env: dev

Restart the Teleport Database Service for the configuration file changes to take effect.

Create a dynamic database resource to dynamically register an AWS database in an external account and proxy connections to it.

kind: db
version: v3
metadata:
  name: "example-opensearch"
  description: "Example dynamic database resource"
  labels:
    env: "dev"
spec:
  protocol: "opensearch"
  uri: your-opensearch-domain-url.eu-central-1.es.amazonaws.com:443
  aws:
    account_id: "abcd1234-this-is-an-example"

Save the configuration to a file like database.yaml and create it with tctl:

tctl create database.yaml

For more information about database registration using dynamic database resources, see: Dynamic Registration.

Step 4/4. Connect

Once the Database Service has started and joined the cluster, you can start accessing AWS OpenSearch API:

Create a proxy tunnel:

tsh proxy db --tunnel --port=8000 --db-user=ExampleTeleportOpenSearchRole example-opensearch
Started authenticated tunnel for the OpenSearch database "example-opensearch" in cluster "teleport.example.com" on 127.0.0.1:8000.
Use one of the following commands to connect to the database or to the address above using other database GUI/CLI clients:
  * start interactive session with opensearchsql:
  $ opensearchsql http://localhost:8000
  * run request with opensearch-cli:
  $ opensearch-cli --profile teleport --config /Users/alice/.tsh/teleport.example.dev/example-opensearch/opensearch-cli/8a5ce249.yml curl get --path /
  * run request with curl:
  $ curl http://localhost:8000/

You can now interact with AWS OpenSearch API via local tunnel created by the tsh proxy db command:

curl http://localhost:8000/movies/_search \   -H 'Content-Type: application/json'  \   -d '{ "query": { "match_all": {} } }'
{"took":170,"timed_out":false,"_shards":{"total":5,"successful":5,"skipped":0,"failed":0},"hits":{"total":{"value":1,"relation":"eq"},"max_score":1.0,"hits":[{"_index":"movies","_id":"1","_score":1.0,"_source":{"director": "Burton, Tim", "genre": ["Comedy","Sci-Fi"], "year": 1996, "actor": ["Jack Nicholson","Pierce Brosnan","Sarah Jessica Parker"], "title": "Mars Attacks!"}}]}}

Interactive session can be started using the tsh db connect command, which invokes the opensearchsql binary with interactive mode under the hood:

tsh db connect example-opensearch --db-user=ExampleTeleportOpenSearchRole
____                  _____                      __
/ __ \____  ___  ____ / ___/___  ____ ___________/ /_
/ / / / __ \/ _ \/ __ \\__ \/ _ \/ __ `/ ___/ ___/ __ \
/ /_/ / /_/ /  __/ / / /__/ /  __/ /_/ / /  / /__/ / / /
\____/ .___/\___/_/ /_/____/\___/\__,_/_/   \___/_/ /_/
/_/
Server: OpenSearch 2.5.0
CLI Version: 1.0.0
Endpoint: http://localhost:56766
Query Language: sql
opensearchsql> select * from movies;
fetched rows / total rows = 1/1
+----------------+---------+---------------+--------+-------------+
| actor          | genre   | title         | year   | director    |
|----------------+---------+---------------+--------+-------------|
| Jack Nicholson | Comedy  | Mars Attacks! | 1996   | Burton, Tim |
+----------------+---------+---------------+--------+-------------+
opensearchsql>

Have a suggestion or can’t find something?

IMPROVE THE DOCS