Teleport

Database Access with AWS OpenSearch

Available for:
OpenSource
Team
Cloud
Enterprise

Teleport can provide secure access to AWS OpenSearch via the Teleport Database Service. This allows for fine-grained access control through Teleport's RBAC.

In this guide, you will:

Configure an AWS OpenSearch Service via REST API with IAM Authentication.
Join the AWS OpenSearch database to your Teleport cluster.
Connect to the AWS OpenSearch database via the Teleport Database Service.

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

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 the Getting Started guide.
The tctl admin tool and tsh client tool version >= 14.0.0.

See Installation for details.

A Teleport Team account. If you don't have an account, sign up to begin your free trial.
The Enterprise tctl admin tool and tsh client tool, version >= 13.3.9.

You can download these tools from the Cloud Downloads page.

A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.
The Enterprise tctl admin tool and tsh client tool version >= 14.0.0.

You can download these tools by visiting your Teleport account workspace.

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

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21

tsh version
Teleport v13.3.9 go1.21
Proxy version: 13.3.9Proxy: teleport.example.com

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.
A running Teleport Discovery Service if you plan to use Database Auto-Discovery.
To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands on your administrative workstation using your current credentials. For example:
```
tsh login --proxy=teleport.example.com --user=[email protected]
tctl status
Cluster  teleport.example.com
Version  14.0.0
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.

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 Service 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: v7
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 appropriate commands for your authentication provider:

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
```
Sign out of the Teleport cluster and sign in again to assume the new role.

Retrieve your github authentication connector:
```
tctl get github/github --with-secrets > github.yaml
```
Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the github.yaml file. Because this key contains a sensitive value, you should remove the github.yaml file immediately after updating the resource.
Edit github.yaml, adding aws-opensearch-access to the teams_to_roles section.

The team you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the team must include your user account and should be the smallest team possible within your organization.

Here is an example:
```
  teams_to_roles:
    - organization: octocats
      team: admins
      roles:
        - access
+       - aws-opensearch-access
```
Apply your changes:
```
tctl create -f github.yaml
```
Sign out of the Teleport cluster and sign in again to assume the new role.

Retrieve your saml configuration resource:
```
tctl get --with-secrets saml/mysaml > saml.yaml
```
Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the saml.yaml file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource.
Edit saml.yaml, adding aws-opensearch-access to the attributes_to_roles section.

The attribute you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.

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
```
Sign out of the Teleport cluster and sign in again to assume the new role.

Retrieve your oidc configuration resource:
```
tctl get oidc/myoidc --with-secrets > oidc.yaml
```
Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the oidc.yaml file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource.
Edit oidc.yaml, adding aws-opensearch-access to the claims_to_roles section.

The claim you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.

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
```
Sign out of the Teleport cluster and sign in again to assume the new role.

Step 3/4. Install the Teleport Database Service

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

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:

Install Teleport on the host where you will run the Teleport Database Service:

Select an edition, then follow the instructions for that edition to install Teleport.

Teleport Edition

curl https://goteleport.com/static/install.sh | bash -s 14.0.0

Add the Teleport repository to your repository list:

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 cloud.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport-ent-updater

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"
sudo yum install teleport-ent-updater
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 cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
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/cloud/teleport-yum.repo")"

Install teleport
sudo dnf install teleport-ent-updater

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 Zypper repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use Zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")

Install teleport
sudo zypper install teleport-ent-updater

OS repository channels

The following channels are available for APT, YUM, and Zypper repos. They may be used in place of stable/v14 anywhere in the Teleport documentation.

Channel name	Description
`stable/<major>`	Receives releases for the specified major release line, i.e. `v14`
`stable/cloud`	Rolling channel that receives releases compatible with current Cloud version
`stable/rolling`	Rolling channel that receives all published Teleport releases

Before installing a teleport binary with a version besides v13, read our compatibility rules to ensure that the binary is compatible with Teleport Cloud.

When running multiple teleport binaries within a cluster, the following rules apply:

Patch and minor versions are always compatible, for example, any 8.0.1 component will work with any 8.0.3 component and any 8.1.0 component will work with any 8.3.0 component.
Servers support clients that are 1 major version behind, but do not support clients that are on a newer major version. For example, an 8.x.x Proxy Service is compatible with 7.x.x resource services and 7.x.x tsh, but we don't guarantee that a 9.x.x resource service will work with an 8.x.x Proxy Service. This also means you must not attempt to upgrade from 6.x.x straight to 8.x.x. You must upgrade to 7.x.x first.
Proxy Services and resource services do not support Auth Services that are on an older major version, and will fail to connect to older Auth Services by default. This behavior can be overridden by passing --skip-version-check when starting Proxy Services and resource services.

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 v14. 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/v14" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport-ent