Version: 14.x

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.

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.

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.

Not yet a Teleport user?

If you have not yet deployed the Auth Service and Proxy Service, you should follow one of our getting started guides or try our Teleport application access interactive learning track.

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

Application Access and DNS

Teleport assigns a subdomain to each application you configure for Application Access. For example, if you enroll Grafana as a resource, Teleport assigns the resource to the grafana.teleport.example.com subdomain.

If you host the Teleport cluster on your own network, you should update your DNS configuration to account for application subdomains. You can update DNS in one of two ways:

Create a single DNS address (A) or canonical name (CNAME) record using wildcard substitution for the subdomain name. For example, create a DNS record with the name *.teleport.example.com.
Create a separate DNS address (A) or canonical name (CNAME) record for each application subdomain.

Modifying DNS ensures that the certificate authority—for example, Let's Encrypt—can issue a certificate for each subdomain and that clients can verify Teleport hosts regardless of the application they are accessing.

If you use the Teleport cloud platform, no DNS updates are needed because your Teleport cluster automatically provides the subdomains and signed TLS certificates for your applications under your tenant address.

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:

Create Role Step 1

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

Create Role Step 2

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

Create Role Step 3

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 <<EOF
resource "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.

Apply least-privilege permissions

AmazonAthenaFullAccess may provide too much access for your intentions. To use a different IAM policy to reduce permissions, see Identity and access management in Athena for more details.

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 <<EOF
kind: role
version: v5
metadata:
  name: aws-athena-access
spec:
  allow:
    app_labels:
      '*': '*'
    aws_role_arns:
    - arn:aws:iam::aws-account-id:role/ExampleTeleportAthenaRole
EOF

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

Templating "aws_role_arns" in role definitions

The aws_role_arns field supports template variables so they can be populated dynamically based on your users' identity provider attributes. Here are some examples:

local users
SSO users

Use {{internal.aws_role_arns}} in the role definition:

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

Then specify the IAM roles through user traits:

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']

Let's assume that an IAM role has been created for each Teleport user, and the name of the IAM role corresponds to their Email addresses without the Email domain suffix.

Then aws_role_arns can be templated with external.email:

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)}}']

See Role Templates for details.

Create the new role:

$ tctl create -f aws-athena-access.yaml

Assign the aws-athena-access role to your Teleport user by running the appropriate commands for your authentication provider:

Local User
GitHub
SAML
OIDC

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

  roles:
   - access
   - auditor
   - editor
+  - aws-athena-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-athena-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-athena-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-athena-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-athena-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-athena-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-athena-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/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.

non-standard AWS regions

Replace https://console.aws.amazon.com with https://console.amazonaws-us-gov.com for AWS GovCloud (US) regions or https://console.amazonaws.cn for AWS China regions.

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.

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

Teleport Community Edition
Teleport Enterprise
Teleport Enterprise Cloud

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

# 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