Sign In

Sign in to Teleport

Teleport Cloud LoginLogin to your Teleport AccountDashboard LoginLegacy Login & Teleport Enterprise Downloads
Get Started
Fork me on GitHub

Teleport

Database Access with Redshift Serverless on AWS

Version 12.x
Improve

This guide will help you to:

  • Set up Teleport to access your AWS Redshift Serverless workgroups.
  • Connect to your databases through Teleport.
Teleport Database Access Redshift Self-Hosted

Prerequisites

  • A pre-existing Teleport 12.1.1 cluster. If you don't already have Teleport running, see How to Choose a Teleport Edition to learn more about your options, and how to set up Teleport.
  • AWS account with a Redshift Serverless configuration and permissions to create and attach IAM policies.
  • Command-line client psql installed and added to your system's PATH environment variable.
  • A host where you will run the Teleport Database Service. This guide assumes an EC2 instance, and provides a corresponding example of access control.

  • To 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  12.1.1
    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.

    To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

    tsh login --proxy=myinstance.teleport.sh [email protected]
    tctl status
    Cluster  myinstance.teleport.sh
    Version  12.1.2
    CA pin   sha256:sha-hash-here

    You must run subsequent tctl commands in this guide on your local machine.

Step 1/5. Create an IAM policy for Teleport

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.

Teleport needs AWS IAM permissions to be able to:

  • Discover and register Redshift Serverless workgroups and their associated VPC endpoints.
  • Manage IAM user or IAM role policies.

If you don't already have one, create a role to apply to the EC2 instance that the Teleport Database Service will run on. This guide uses the example name teleport-redshift-serverless-node.

Under Trusted entity type choose "AWS service", and under Use case choose "EC2".

Create and attach a policy to the teleport-redshift-serverless-node role to allow Teleport to bootstrap access to AWS Redshift Serverless:

Tip

This policy is required for Automatic Teleport bootstrapping, documented below. You can optionally skip this policy, and select the "Manual" option when you reach step 4.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "iam:AttachRolePolicy",
                "iam:PutRolePermissionsBoundary"
            ],
            "Resource": [
                "arn:aws:iam::abcd1234-this-is-an-example:role/teleport-redshift-serverless-node"
            ],
            "Effect": "Allow"
        },
        {
            "Action": [
                "iam:GetPolicy",
                "iam:CreatePolicy",
                "iam:TagPolicy",
                "iam:ListPolicyVersions",
                "iam:CreatePolicyVersion"
            ],
            "Resource": [
                "arn:aws:iam::abcd1234-this-is-an-example:policy/DatabaseAccess",
                "arn:aws:iam::abcd1234-this-is-an-example:policy/DatabaseAccessBoundary"
            ],
            "Effect": "Allow"
        }
    ]
}

Remember to replace the example AWS account ID. The policies defined in the Resources array will be created later in this guide.

Apply the teleport-redshift-serverless-node role to the EC2 instance the Teleport Database Service will be installed in.

Step 2/5. Create an IAM Role for user access

Create an AWS IAM role to provide user access to Redshift Serverless. This role will be granted to Teleport users via a corresponding Teleport role. In this guide we will use the example name teleport-redshift-serverless-access.

Under Trusted entity type choose "Custom trust policy". Edit the trust policy to allow the IAM role generated in the previous step to assume this role, so that the Teleport node can use the permissions granted by this role to access databases:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Statement1",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::abcd1234-this-is-an-example:role/teleport-redshift-serverless-node",
                "Service": "ec2.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Remember to replace the example AWS account ID.

Create and apply a permission policy to allow access to Redshift Serverless. This policy can allow access to all instances:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "redshift-serverless:GetCredentials",
            "Resource": "*"
        }
    ]
}

Or you can restrict the Resource line to a specific Redshift Serverless workgroup:

{
...
      "Resource": "arn:aws:redshift-serverless:us-west-2:1234567890:workgroup/some-workgroup-id"
...
}

Step 3/5. Create a Teleport role for Redshift Serverless access

On your workstation logged in to your Teleport cluster with tsh, define a new role to provide access to Redshift Serverless. Our example file is redshift-role.yaml:

version: v5
kind: role
metadata:
  name: redshift-serverless-access
spec:
  allow:
    db_labels:
      '*': '*'
    db_names:
    - dev
    db_users:
    - 'teleport-redshift-serverless-access'
  • The value of db_users corresponds to the IAM role created in the previous step. You can provide either the role name or the full AWS ARN of the IAM role.
  • The value(s) for db_names will depend on your Redshift Serverless configuration, but dev is the default name applied by AWS. You can also provide * to grant access to all instances.

Save this file and apply it to your Teleport cluster:

tctl create -f redshift-role.yaml
role 'redshift-serverless-access' has been created

Assign the redshift-serverless-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 redshift-serverless-access to the list of existing roles:

  roles:
   - access
   - auditor
   - editor
+  - redshift-serverless-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 redshift-serverless-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
+       - redshift-serverless-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 saml.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 redshift-serverless-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
+       - redshift-serverless-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 redshift-serverless-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
+       - redshift-serverless-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.

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

Step 4/5. Install and start 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

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

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

Teleport Edition

Open Source

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 v12. You'll need to update this
file for each major release of Teleport.
Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE'
and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'.
Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v12" \| 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 v12. You'll need to update this
file for each major release of Teleport.
Note: if using a fork of RHEL/CentOS or Amazon Linux you may need to use '$ID_LIKE'
and the codename your distro was forked from instead of '$ID'
Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L133-L153
sudo yum-config-manager --add-repo $(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v12/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
Optional:  Use DNF on newer distributions
$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
$ sudo dnf install teleport

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-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
shasum -a 256 teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
cd teleport
sudo ./install

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.

After Downloading the .deb file for your system architecture, install it with dpkg. The example below assumes the root user:

dpkg -i ~/Downloads/teleport-ent_12.1.1_$SYSTEM-ARCH.deb
Selecting previously unselected package teleport-ent.
(Reading database ... 30810 files and directories currently installed.)
Preparing to unpack teleport-ent_12.1.1_$SYSTEM_ARCH.deb ...
Unpacking teleport-ent 12.1.1 ...
Setting up teleport-ent 12.1.1 ...

After Downloading the .rpm file for your system architecture, install it with rpm:

rpm -i ~/Downloads/teleport-ent-12.1.1.$SYSTEM-ARCH.rpm
warning: teleport-ent-12.1.1.$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY
curl https://get.gravitational.com/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
shasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v12.1.1-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-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz
shasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v12.1.1-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 same host, create a Teleport configuration file:

teleport db configure create \   -o file \   --proxy=teleport.example.com:443 \   --token=/tmp/token \   --redshift-serverless-discovery=us-west-1
  • Replace teleport.example.com with your Teleport proxy URI or cloud tenant address (e.g. mytenant.teleport.sh).
  • Provide the token from the previous step to the --token flag.
  • Update the value of --redshift-serverless-discovery to match your AWS region.

This command will generate a Database Service configuration with Redshift Serverless auto-discovery enabled and place it at /etc/teleport.yaml.

Filter with AWS tags

Use --aws-tags <key>=<value>,<key>=<value> to only match Redshift Serverless workgroups with specified AWS resource tags.

For example, if a workgroup has multiple VPC endpoints but only one of the VPC endpoints will be accessed through Teleport, add the resource tag teleport.dev/discovery with value true to the VPC endpoint, and then specify --aws-tags teleport.dev/discovery=true when running teleport db configure create.

Bootstrap access to Redshift Serverless

Teleport can bootstrap IAM permissions for the Database Service based on its configuration using the teleport db configure bootstrap command. You can use this command in automatic or manual mode:

  • In automatic mode, Teleport will attempt to create appropriate IAM policies and attach them to the specified IAM identity (user or role). This requires the IAM permissions we applied to the teleport-redshift-serverless-node role earlier.
  • In manual mode, Teleport will print required IAM policies. You can then create and attach them manually using the AWS management console.
AWS credentials

AWS Credentials are only required if you’re running the command in "automatic" mode. The command uses the default credential provider chain to find AWS credentials. The steps in this guide provide AWS credentials to the node by applying the teleport-redshift-serverless-node role to the instance. See Specifying Credentials for alternative methods of providing AWS credentials for non-EC2 nodes.

Run one of the following commands on your Database Service node:

Use this command to bootstrap the permissions automatically when your Teleport Database Service runs on a host with AWS credentials. Teleport will automatically determine the available role/user, or you can specify one with --attach-to-role or attach-to-user.

teleport db configure bootstrap -c /etc/teleport.yaml

Use this command to display required IAM policies which you will then create in your AWS console:

teleport db configure bootstrap -c /etc/teleport.yaml --manual

See the full bootstrap command reference for more information.

Start the Database service

Run the following command on the Database Service node, depending on how you installed Teleport:

sudo systemctl start teleport
sudo teleport install systemd --output=/etc/systemd/system/teleport.service;
sudo systemctl enable teleport
sudo systemctl start teleport

The Database Service will discover all Redshift databases according to the configuration and register them in the cluster. The Database Service will also attempt to configure IAM access policies for the discovered databases. Keep in mind that AWS IAM changes may not propagate immediately and can take a few minutes to come into effect.

Step 5/5. Connect

Once the Database Service has started and joined the cluster, log in to see the registered databases. Replace --proxy with the address of your Teleport Proxy Service or cloud tenant:

tsh login --proxy=mytenant.teleport.sh --user=alice
tsh db ls
Name        Description                    Labels
----------- ------------------------------ --------
my-redshift Redshift cluster in us-east-1  ...
Note

You can override the database name by applying the teleport.dev/database_name AWS tag to the resource. The value of the tag will be used as the database name.

To connect to the Redshift Serverless instance:

tsh db connect my-redshift --db-user=teleport-redshift-serverless-access --db-name=dev
psql (15.1, server 8.0.2)
WARNING: psql major version 15, server major version 8.0.
         Some psql features might not work.
SSL connection (protocol: TLSv1.3, cipher: TLS_CHACHA20_POLY1305_SHA256, compression: off)
Type "help" for help.
dev=>

To log out of the database and remove credentials:

tsh db logout my-redshift

Troubleshooting

User permission errors

The IAM role teleport-redshift-serverless-access will be automatically mapped as IAMR:teleport-redshift-serverless-access inside the Redshift Serverless database.

Users (database admins) can optionally set up this database user's permissions prior to logging in as this new IAM role to avoid or resolve user permission issues:

  1. Connect to the Redshift Serverless workgroup as the admin user, and execute:

    CREATE USER "IAMR:teleport-redshift-serverless-access" WITH PASSWORD DISABLE;

  2. Grant this user appropriate in-database permissions. For example:

    GRANT SELECT ON TABLE users  TO "IAMR:teleport-redshift-serverless-access";

Certificate error

If your tsh db connect error includes the following text, you likely have an RDS database created before July 28, 2020, which presents an X.509 certificate that is incompatible with Teleport:

x509: certificate relies on legacy Common Name field, use SANs instead

AWS provides instructions to rotate your SSL/TLS certificate.

No credential providers error

If you see the error NoCredentialProviders: no valid providers in chain in Database Service logs then Teleport is not detecting the required credentials to connect via AWS IAM permissions. Check whether the credentials or security role has been applied in the machine running the Teleport Database Service.

Timeout errors

The Teleport Database Service needs connectivity to your database endpoints. That may require enabling inbound traffic on the database from the Database Service on the same VPC or routing rules from another VPC. Using the nc program you can verify connections to databases:

nc -zv postgres-instance-1.sadas.us-east-1.rds.amazonaws.com 5432
Connection to postgres-instance-1.sadas.us-east-1.rds.amazonaws.com (172.31.24.172) 5432 port [tcp/postgresql] succeeded!

Next steps

Have a suggestion or can’t find something?
IMPROVE THE DOCS