Amazon Athena Access

You can set up secure access to Amazon Athena using Teleport's support for the AWS CLI and Console.

This guide will help you to:

• Install the Teleport Application Service.
• Set up AWS CLI and Console access.
• Connect to your Athena databases.

Prerequisites

• AWS account with Athena databases.
• IAM permissions to create IAM roles.
• aws Command Line Interface (CLI) tool installed in PATH.
• A host, e.g., an EC2 instance, where you will run the Teleport Application Service.

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

We will assume your Teleport cluster is accessible at teleport.example.com and *.teleport.example.com. You can substitute the address of your Teleport Proxy Service. (For Teleport Cloud customers, this will be similar to mytenant.teleport.sh.)

Step 1/5. Create an IAM role for Athena access

Create an IAM role that provides access to your Athena resources. Teleport Application Service will assume this IAM role on behalf of the Teleport user that accesses these Athena resources.

There are several methods to create an IAM role:

• Using AWS Console
• Using AWS CLI
• Using Terraform

Visit the Roles page of the AWS Console, then press "Create Role".

Select the "AWS account" option, which creates a default trust policy to allow other entities in this account to assume this role:

Press "Next". Find the AWS-managed policy AmazonAthenaFullAccess and then select the policy:

Press "Next". Enter role name ExampleTeleportAthenaRole and press "Create role":

Create a file with the following trust policy. Replace aws-account-id with your AWS Account ID:

cat > trust-relationship.json <<EOF{  "Version": "2012-10-17",  "Statement": [    {      "Effect": "Allow",      "Principal": {        "AWS": "arn:aws:iam::aws-account-id:root"      },      "Action": "sts:AssumeRole"    }  ]}EOF

Create an IAM role with name ExampleTeleportAthenaRole:

aws iam create-role --role-name ExampleTeleportAthenaRole --assume-role-policy-document file://trust-relationship.json

Attach managed policy AmazonAthenaFullAccess to the role:

aws iam attach-role-policy --role-name ExampleTeleportAthenaRole --policy-arn arn:aws:iam::aws:policy/AmazonAthenaFullAccess

Add the following resources to your Terraform deployment. Replace aws-account-id with your AWS Account ID:

cat > teleport_iam_role_ExampleTeleportAthenaRole.tf <<EOFresource "aws_iam_role" "teleport-ExampleTeleportAthenaRole" {  name = "ExampleTeleportAthenaRole"  assume_role_policy = jsonencode({    Version = "2012-10-17"    Statement = [      {        Effect = "Allow"        Principal = {          AWS = "arn:aws:iam::aws-account-id:root"        }        Action = "sts:AssumeRole"      },    ]  })}resource "aws_iam_role_policy_attachment" "teleport-ExampleTeleportAthenaRole-AmazonAthenaFullAccess" {  role       = aws_iam_role.teleport-ExampleTeleportAthenaRole.name  policy_arn = "arn:aws:iam::aws:policy/AmazonAthenaFullAccess"}EOF

Then terraform apply.

Step 2/5. Configure the Teleport IAM role mapping

Give your Teleport users permissions to assume IAM roles in your Teleport cluster.

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

cat > aws-athena-access.yaml <<EOFkind: roleversion: v5metadata:  name: aws-athena-accessspec:  allow:    app_labels:      '*': '*'    aws_role_arns:    - arn:aws:iam::aws-account-id:role/ExampleTeleportAthenaRoleEOF

Remember to replace aws-account-id with your AWS Account ID.

kind: role
version: v5
metadata:
  name: aws-athena-access
spec:
  allow:
    app_labels:
      '*': '*'
    aws_role_arns: ['{{internal.aws_role_arns}}']

kind: user
version: v2
metadata:
  name: alice
spec:
  roles: ['aws-athena-access']
  traits:
    aws_role_arns: ['arn:aws:iam:123456789000:role/role_for_alice']
---
kind: user
version: v2
metadata:
  name: bob
spec:
  roles: ['aws-athena-access']
  traits:
    aws_role_arns: ['arn:aws:iam:123456789000:role/role_for_bob']

kind: role
version: v5
metadata:
  name: aws-athena-access
spec:
  allow:
    app_labels:
      '*': '*'
    aws_role_arns: ['arn:aws:iam:123456789000:role/{{email.local(external.email)}}']

Create the new role:

tctl create -f aws-athena-access.yaml

Assign the aws-athena-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:

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

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

tctl create -f out.yaml

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

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

tctl create -f github.yaml

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

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

tctl create -f saml.yaml

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

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

tctl create -f oidc.yaml

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

Step 3/5. Install the Teleport Application Service

Generate a token

A join token is required to authorize a Teleport Application Service instance to join the cluster. Generate a short-lived join token and save the output of the command:

tctl tokens add \    --type=app \    --app-name=aws \    --app-uri=https://console.aws.amazon.com/console/home

On the host where you will run the Teleport Application Service, copy the token to a file called /tmp/token.

Install and start Teleport

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

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

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

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

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

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

sudo dnf install teleport-ent-fips

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

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

Edit the Teleport configuration file (/etc/teleport.yaml) to include the following information, adjusting the value of proxy_server to specify the host and port of your Teleport Proxy Service:

version: v3
teleport:
  join_params:
    token_name: "/tmp/token"
    method: token
  proxy_server: "teleport.example.com:443"
auth_service:
  enabled: off
proxy_service:
  enabled: off
ssh_service:
  enabled: off
app_service:
  enabled: true
  apps:
  - name: aws
    uri: https://console.aws.amazon.com/home/home

Grant the Teleport Application Service access to credentials that it can use to authenticate to AWS. If you are running the Teleport Application Service on an EC2 instance, you should use the EC2 Instance Metadata Service method. Otherwise, you must use environment variables:

AWS_ACCESS_KEY_ID=00000000000000000000
AWS_SECRET_ACCESS_KEY=0000000000000000000000000000000000000000
AWS_DEFAULT_REGION=<YOUR_REGION>

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

sudo systemctl enable teleport
sudo systemctl 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 Application Service with systemctl status teleport and view its logs with journalctl -fu teleport.

Step 4/5. Give Teleport permissions to assume roles

Next, attach the following policy to the IAM role or IAM user the Teleport Application Service instance is using, which allows the Application Service to assume the IAM roles:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": "*"
    }
  ]
}

Step 5/5. Connect

Once the Application Service has started and joined the cluster, you can start connecting to your Athena database.

Using AWS Management Console

Log in to the Teleport Web UI at https://teleport.example.com (replace with your Proxy Service's public address).

Navigate to the Applications tab in your Teleport cluster's control panel and click on the Launch button for the AWS application. This will bring up an IAM role selector:

Click on the role ExampleTeleportAthenaRole and you will get redirected to the AWS Management Console, signed in with the selected role.

In the console's top-right corner, you should see that you're logged in through federated login and the name of your assumed IAM role is ExampleTeleportAthenaRole/<teleport-username> where the session name is your Teleport username.

Using AWS CLI

Log into the previously configured AWS app on your desktop:

tsh apps login --aws-role ExampleTeleportAthenaRole aws
Logged into AWS app aws. Example AWS CLI command:
tsh aws s3 ls

The --aws-role flag allows you to specify the AWS IAM role to assume when accessing the AWS API. You can either provide a role name like --aws-role ExampleTeleportDynamoDBRole or a full role ARN like arn:aws:iam::123456789000:role/ExampleTeleportAthenaRole.

Now you can use the tsh aws command like the native aws command-line tool:

tsh aws athena list-work-groups

To log out of the aws application and remove credentials:

tsh apps logout aws

Using other Athena applications

First, log into the previously configured AWS app if you haven't already done so:

tsh apps login --aws-role ExampleTeleportAthenaRole aws

Connect to Athena with the ODBC or JDBC driver:

• Connect with ODBC
• Connect with JDBC
• Connect with DBeaver

Start a local HTTPS proxy:

tsh proxy aws --port 8443 --format athena-odbc
Started AWS proxy on http://127.0.0.1:8443.
Set the following properties for the Athena ODBC data source:
[Teleport AWS Athena Access]
AuthenticationType = IAM Credentials
UID = abcd1234-this-is-an-example
PWD = zyxw9876-this-is-an-example
UseProxy = 1;
ProxyScheme = http;
ProxyHost = 127.0.0.1;
ProxyPort = 8443;
TrustedCerts = <local-ca-bundle-path>
Here is a sample connection string using the above credentials and proxy settings:
DRIVER=Simba Amazon Athena ODBC Connector;AuthenticationType=IAM Credentials;UID=abcd1234-this-is-an-example;PWD=zyxw9876-this-is-an-example;UseProxy=1;ProxyScheme=http;ProxyHost=127.0.0.1;ProxyPort=8443;TrustedCerts=<local-ca-bundle-path>;AWSRegion=<region>;Workgroup=<workgroup>

Use the provided connection string in your Athena application with ODBC driver.

Start a local HTTPS proxy:

tsh proxy aws --port 8443 --format athena-jdbc
Started AWS proxy on http://127.0.0.1:8443.
First, add the following certificate to your keystore:
<local-ca-bundle-path>
For example, to import the certificate using "keytool":
keytool -noprompt -importcert -alias teleport-aws -file <local-ca-bundle-path> -keystore <keystore>
Then, set the following properties in the JDBC connection URL:
User = abcd1234-this-is-an-example
Password = zyxw9876-this-is-an-example
ProxyHost = 127.0.0.1;
ProxyPort = 8443;
Here is a sample JDBC connection URL using the above credentials and proxy settings:
jdbc:awsathena://User=abcd1234-this-is-an-example;Password=zyxw9876-this-is-an-example;ProxyHost=127.0.0.1;ProxyPort=8443;AwsRegion=<region>;Workgroup=<workgroup>

Follow the printed instructions to add the local certificate to your Java Keystore. The default Java Keystore is usually located at:

$ ls $(java -XshowSettings:properties -version 2>&1 | grep 'java.home' | awk '{print $3}')/lib/security/cacerts

Then use the provided JDBC connection URL for your Athena application with JDBC driver.

Start a local HTTPS proxy:

tsh proxy aws --port 8443 --format athena-jdbc
Started AWS proxy on http://127.0.0.1:8443.
First, add the following certificate to your keystore:
<local-ca-bundle-path>
For example, to import the certificate using "keytool":
keytool -noprompt -importcert -alias teleport-aws -file <local-ca-bundle-path> -keystore <keystore>
Then, set the following properties in the JDBC connection URL:
User = abcd1234-this-is-an-example
Password = zyxw9876-this-is-an-example
ProxyHost = 127.0.0.1;
ProxyPort = 8443;
Here is a sample JDBC connection URL using the above credentials and proxy settings:
jdbc:awsathena://User=abcd1234-this-is-an-example;Password=zyxw9876-this-is-an-example;ProxyHost=127.0.0.1;ProxyPort=8443;AwsRegion=<region>;Workgroup=<workgroup>

Note that DBeaver uses its own Java Keystore instead of the default one. For example, on macOS, the Keystore location is /Applications/DBeaver.app/Contents/Eclipse/jre/Contents/Home/lib/security/cacerts.

Follow Importing CA Certificates into DBeaver to setup the Keystore for DBeaver. Then follow the printed instruction from above tsh proxy aws command to add the local certificate to the Keystore.

Start DBeaver and add an "Athena" connection. Enter the username (AWS access key) and password (AWS secret key) from the tsh proxy aws output:

Then fill in the ProxyHost and ProxyPort settings in "Driver properties":

Click "Finish". Now you can connect to your Athena database.

To log out of the aws application and remove credentials:

tsh apps logout aws

Next steps

• More information on AWS Management and API with Teleport Application Access.
• Learn more about AWS service endpoints.