Skip to main content
Version: 14.x

Database Access with AWS OpenSearch

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:

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

OpenSearch Self-Hosted

Prerequisites​

  • A running Teleport cluster version 14.3.33 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 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 using your current credentials. tctl is supported on macOS and Linux machines. For example: 
    $ tsh login --proxy=teleport.example.com [email protected]
    $ tctl status
    # Cluster  teleport.example.com
    # Version  14.3.33
    # 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.

Create Role to Identify EC2 Instance

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:

Create Role Step 1

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:

Select Get Started

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:

Mapped User

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

IAM Role mapping

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:

  1. Retrieve your local user's configuration resource:

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

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

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

  3. Apply your changes:

    $ tctl create -f out.yaml

  4. 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 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
Alternative methods

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.

The following command updates the repository for the package manager on the local operating system and installs the provided Teleport version:

$ curl https://cdn.teleport.dev/install-v14.3.33.sh | bash -s 14.3.33

Databases can be registered dynamically by Discovery Service, tctl, etc.

Generate a Database Service configuration that monitors the dynamic database resources:

$ sudo teleport db configure create \
   -o file \
   --proxy=mytenant.teleport.sh:443 \
   --token=/tmp/token \
   --dynamic-resources-labels env=prod

This command will place the Database Service configuration at the /etc/teleport.yaml location.

Enable auto-discovery for AWS OpenSearch in Discovery Service?

In your Teleport Discovery Service's configuration, use AWS matcher type opensearch, and update region and tags that match your OpenSearch databases:

discovery_service:
  enabled: "yes"
  aws:
  - types: ["opensearch"]
    regions: ["us-west-1"]
    tags:
      "env": "prod" # Match database resource tags where tag:env=prod

Restart the Discovery Service.

Configure the Database Service to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed the Database Service.

On the host where you will run the Database Service, enable and start Teleport:

$ sudo systemctl enable teleport
$ sudo systemctl start teleport

You can check the status of the Database Service with systemctl status teleport and view its logs with journalctl -fu teleport.

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>

Next steps​

  • See the YAML configuration reference for updating dynamic resource matchers or static database definitions.