{"token_count": 6132} # Database Access with Amazon OpenSearch Teleport can provide secure access to Amazon OpenSearch via the [Teleport Database Service](https://goteleport.com/docs/enroll-resources/database-access.md). This allows for fine-grained access control through [Teleport's RBAC](https://goteleport.com/docs/enroll-resources/database-access/rbac.md). In this guide, you will: 1. Configure your Amazon OpenSearch database via REST API with IAM Authentication. 2. Add the database to your Teleport cluster. 3. Connect to the database via Teleport. ## How it works The Teleport Database Service makes use of [fine-grained access control](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/fgac.html), which maps an IAM role to a backend OpenSearch role. Teleport users choose an IAM role and connect to OpenSearch via a local proxy server. The local proxy server forwards requests to the Teleport Database Service via the Teleport Proxy Service. The Database Service assumes the user's chosen IAM role, rewrites requests with AWS credentials, and forwards them to the OpenSearch API. **Self-Hosted** ![OpenSearch Self-Hosted](/docs/assets/images/opensearch_selfhosted-d6fcbcf1944d30489a692d8c8464fed6.png) **Teleport Enterprise Cloud** ![OpenSearch Cloud](/docs/assets/images/opensearch_cloud-cdfaf8c04b8f907c2062a6820a9e1da5.png) This guide shows how to register a single OpenSearch database with your Teleport cluster. For a more scalable approach, learn how to set up [Database Auto-Discovery](https://goteleport.com/docs/enroll-resources/auto-discovery/databases.md) to automatically enroll all AWS databases in your infrastructure. ## Prerequisites - Amazon OpenSearch domain. - [Enabled Amazon OpenSearch Service fine-grained access control](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/fgac.html#fgac-enabling) - IAM permissions to create IAM roles. - [opensearchsql](https://github.com/opensearch-project/sql-cli) Command Line Interface (CLI) tool installed in `$PATH`. * A running Teleport cluster accessible at a hostname with a valid TLS certificate. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md). * The `tctl` and `tsh` clients. Installing `tctl` and `tsh` clients 1. Determine the version of your Teleport cluster. The `tctl` and `tsh` clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at `/v1/webapi/find` and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service: **Mac/Linux** ``` $ TELEPORT_DOMAIN=teleport.example.com:443 $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')" ``` **Windows - Powershell** ``` $ $TELEPORT_DOMAIN = "teleport.example.com:443" $ $TELEPORT_VERSION = (Invoke-RestMethod -Uri "https://${TELEPORT_DOMAIN}/v1/webapi/find").server_version ``` 2. Follow the instructions for your platform to install `tctl` and `tsh` clients: **Mac** Download the signed macOS .pkg installer for Teleport, which includes the `tctl` and `tsh` clients: ``` $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg ``` In Finder double-click the `pkg` file to begin installation. --- DANGER Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v$TELEPORT_VERSION-windows-amd64-bin.zip Unzip the archive and move the `tctl` and `tsh` clients to your %PATH% NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP. Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation/single-machine.md). ``` $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ cd teleport $ sudo ./install Teleport binaries have been copied to /usr/local/bin ``` Connecting with TLS routing disabled This guide's commands assume your Teleport cluster uses TLS routing (`proxy_listener_mode: multiplex`), where the `tctl` and `tsh` clients reach every Teleport service through the Proxy Service's web address on port `443`. If you're not sure whether this applies to your cluster, check with whoever manages it. If your cluster uses separate listener ports instead, adjust ports as follows: - **`tsh` commands** (e.g., `tsh login --proxy=...`): continue using the Proxy Service web address on port `3080` (or `443` if behind a load balancer). Do not change these to port `3025`. - **Direct `tctl` or Auth Service API commands**: use port `3025` for the Auth Service gRPC listener: ``` $ tctl status --auth-server=teleport.example.com:3025 ``` - 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. - Check that you can connect to your Teleport cluster and verify that you can run `tctl` and `tsh` commands using your current credentials. 1. Assign teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username. 2. Authenticate to your Teleport cluster. This depends on whether your shell is interactive or not. **In an interactive shell:** Run the following command. By default, this triggers a multi-factor authentication prompt: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ tctl status Cluster teleport.example.com Version 18.10.0 CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 ``` **On non-interactive environments:** If you are running `tsh` and `tctl` as an AI agent, in a CI/CD environment, or similar, make sure the `TELEPORT_IDENTITY_FILE` environment variable is assigned to a valid file path with credentials for your cluster. `tsh` and `tctl` read the file path from the environment variable and do not require a separate authentication step. If there is no identity file available, we recommend that you [set up Machine ID](https://goteleport.com/docs/machine-workload-identity/getting-started.md) to provision one automatically. When executing `tctl` commands with an identity file, you must pass the `--auth-server` flag to provide the Teleport Auth Service address, which is not included in the identity file. If you provide the Proxy Service address, `tctl` connects to the Proxy Service, which forwards traffic to and from the Teleport Auth Service. Update 443 to `3025` if you are contacting the Auth Service directly with `tctl`: ``` $ tctl status --auth-server=teleport.example.com:443 ``` For `tsh` commands that read an identity file, you must pass the `--proxy` flag, which points `tsh` to the address of the Teleport Proxy Service: ``` $ tsh status --proxy=teleport.example.com ``` Ensure client commands can access your identity file. Replace path/to/identity/file with the path to your identity file: ``` $ export TELEPORT_IDENTITY_FILE="${TELEPORT_IDENTITY_FILE:-path/to/identity/file}" ``` Add the `--auth-server` or `--proxy` flags to all subsequent `tctl` and `tsh` commands. 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. 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. --- DASHBOARD IN PRIVATE NETWORK To access the OpenSearch Dashboard deployed within private VPC subnets using Teleport, you can enroll the Dashboard as a [Web application](https://goteleport.com/docs/enroll-resources/application-access/protect-apps/connecting-apps.md) in Teleport. --- ## 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](https://console.aws.amazon.com/iamv2/home#/roles) 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](/docs/assets/images/create-ec2-role-c5e2bc5e7e018b08556152f637d48233.png) 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](/docs/assets/images/create-role-1-de95f8631ab398d51ab1f49ebf5fb258.png) 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 Cluster Teleport Amazon 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](/docs/assets/images/01-opensearch_get_started-4aa44edd94af119ed1d4940b452201d7.png) 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](/docs/assets/images/02-opensearch_mapped_users-ed8b1ad3acdf681e52a981d1e6c945f5.png) Add mapping between the OpenSearch role and AWS IAM `ExampleTeleportOpenSearchRole` role created in the previous step. ![IAM Role mapping](/docs/assets/images/03-opensearch_iam_role_mapping-ed215b6d93d186785944128389fb426d.png) 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 ``` --- TIP You can also create and edit roles using the Web UI. Go to **Access -> Roles** and click **Create New Role** or pick an existing role to edit. --- Assign the `aws-opensearch-access` role to your Teleport user. The commands to run depend on how you authenticate to Teleport, that is, whether you have a local Teleport user, a single sign-on authentication connector, or a non-interactive user: **Local User** 1. Retrieve your local user's roles as a comma-separated list: ``` $ ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")') ``` 2. Edit your local user to add the new role: ``` $ tctl users update $(tsh status -f json | jq -r '.active.username') \ --set-roles "${ROLES?},aws-opensearch-access" ``` 3. Sign out of the Teleport cluster and sign in again to assume the new role. **GitHub** 1. Open your `github` authentication connector in a text editor: ``` $ tctl edit github/github ``` 2. Edit the `github` connector, 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 ``` 3. Apply your changes by saving and closing the file in your editor. 4. Sign out of the Teleport cluster and sign in again to assume the new role. **SAML** 1. 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. 2. 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 ``` 3. Apply your changes: ``` $ tctl create -f saml.yaml ``` 4. Sign out of the Teleport cluster and sign in again to assume the new role. **OIDC** 1. 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. 2. 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 ``` 3. Apply your changes: ``` $ tctl create -f oidc.yaml ``` 4. Sign out of the Teleport cluster and sign in again to assume the new role. **Non-Interactive** For non-interactive users such as AI agents and CI/CD runners, follow these steps. If you are using Machine ID to issue identity files to your user: 1. Add the new role to your bot. Assign mybot to the name of the Machine ID bot that issues your certificate: ``` $ tctl bots update mybot --add-roles aws-opensearch-access ``` 2. Force `tbot` to regenerate the certificate: ``` $ pkill -HUP tbot ``` The bot will also generate a certificate with the new role on its next renewal. Otherwise, update your user and regenerate your identity file: 1. Retrieve your local user's roles as a comma-separated list. Make sure username is the Teleport user you want to assign the new role to. ``` $ ROLES=$(tctl get user/username --format=json | jq -r '.[].spec.roles | join(",")') ``` 2. Edit your local user to add the new role: ``` $ tctl users update username \ --set-roles "${ROLES?},aws-opensearch-access" ``` 3. Regenerate the identity file. Make sure path/to/identity/file corresponds to the correct output path: ``` $ tctl auth sign \ --user=username \ --out=path/to/identity/file \ --overwrite ``` ## 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](https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html) 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 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: - [Configure Teleport to Automatically Enroll EC2 instances](https://goteleport.com/docs/enroll-resources/auto-discovery/servers/ec2-discovery.md) - [Joining Teleport Services via AWS IAM Role](https://goteleport.com/docs/installation/agents/aws-iam.md) - [Joining Teleport Services via AWS EC2 Identity Document](https://goteleport.com/docs/installation/agents/aws-ec2.md) 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 ``` Use the token provided by the output of this command in the next step. ### Install and start Teleport To install Teleport binaries on your Linux server, the recommended installation method is the cluster install script. It will select the correct version, edition, and installation mode for your cluster. 1. Remove any existing Teleport binaries on your system: ``` $ sudo rm -f /usr/local/bin/{tsh,teleport,tctl,tbot,fdpass-teleport,teleport-update} ``` 2. Assign teleport.example.com:443 to your Teleport cluster hostname and port, but not the scheme (https\://). 3. Run your cluster's install script: ``` $ curl "https://teleport.example.com:443/scripts/install.sh" | sudo bash ``` 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. Set the `--proxy` command-line option to the address for your Teleport cluster and database parameters to your AWS environment. Assign opensearch-uri to the hostname of your OpenSearch instance: ``` $ sudo teleport db configure create \ -o file \ --token=/tmp/token \ --proxy=teleport.example.com:443 \ --name=example-opensearch \ --protocol=opensearch \ --uri=opensearch-uri:443 \ --aws-account-id=abcd1234-this-is-an-example \ --labels=env=dev ``` Start the Teleport Database Service. The instructions depend on how you installed the Teleport Database Service and whether your system supports systemd: **Package Manager** Configure the Teleport Database Service to start automatically when the host boots up by creating a systemd service for it. On the host where you will run the Teleport Database Service, enable and start Teleport: ``` $ sudo systemctl enable teleport $ sudo systemctl start teleport ``` You can check the status of the Teleport Database Service with `systemctl status teleport` and view its logs with `journalctl -fu teleport`. **TAR Archive** Configure the Teleport Database Service to start automatically when the host boots up by creating a systemd service for it. On the host where you will run the Teleport Database Service, 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 ``` You can check the status of the Teleport Database Service with `systemctl status teleport` and view its logs with `journalctl -fu teleport`. **No systemd** On the host where you will run the Teleport Database Service, start Teleport: ``` $ sudo teleport start --config=/etc/teleport.yaml ``` Teleport runs in the foreground and outputs logs for the services it is running. ## Step 4/4. Connect Once the Database Service has started and joined the cluster, you can start accessing Amazon 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.com/example-opensearch/opensearch-cli/8a5ce249.yml curl get --path / * run request with curl: $ curl http://localhost:8000/ ``` You can now interact with Amazon 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> ```