Version: 14.x

Access AWS With Teleport Application Access

You can protect the AWS Management Console and AWS APIs with Teleport. This makes it possible to manage access to AWS infrastructure with Teleport features like Access Requests, Access Lists, and identity locking. You can also configure Teleport to provide different levels of AWS access automatically when users authenticate using your single sign-on solution.

This guide will explain how to:

Access the AWS Management Console through Teleport.
Access the AWS Command Line Interface (CLI) through Teleport.
Access applications using AWS SDKs through Teleport.

In this setup, the Teleport Application Service has an AWS IAM role that can assume one or more target IAM roles. Teleport users access the AWS Management Console and APIs through the Teleport Web UI and tsh. When a user visits the AWS Management Console or executes a command with an AWS client application, the Teleport Application Service checks the user's RBAC permissions and, if they are authorized, forwards the user's requests to AWS.

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.

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 --user=email@example.com
$ 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.
An AWS EC2 instance or Elastic Kubernetes Service (EKS) cluster where you will run the Teleport Application Service. EC2 instances must be running a Linux distribution. We recommend starting with a fresh demo instance or EKS cluster to get familiar with the procedure before following this guide in production.
Permissions to create IAM roles and policies in the AWS account you want to connect.
aws command line interface (CLI) tool in PATH. Read the AWS documentation to install or update the latest version of the AWS CLI.
If you plan to run the Teleport Application Service on EKS, you will need an IAM OIDC provider running in your Kubernetes cluster. See the AWS documentation for how to create an IAM OIDC provider.

To check whether you have an IAM OIDC provider running in your cluster, run the following aws command, assigning eks-region to the region where your EKS cluster is running and cluster-name to the name of your Kubernetes cluster:
```
$ aws --region=eks-region eks describe-cluster --name cluster-name --query "cluster.identity.oidc.issuer" --output text
```
If you have an IAM OIDC provider associated with your cluster, this command will print its ID.

Step 1/4. Configure AWS IAM

In this section, you will configure AWS IAM resources to allow the Teleport Application Service to proxy AWS APIs.

The rest of the guide assumes that you are protecting access to an IAM role called ExampleReadOnlyAccess, which allows read-only access to AWS resources through the AWS-managed ReadOnlyAccess policy. We recommend following this guide in a demo environment with the ExampleReadOnlyAccess role, and protecting production AWS roles when you are familiar with the procedure.

You will create the following resources:

Name	Resource	Function
`ExampleReadOnlyAccess`	IAM role	Example role to protect access to with Teleport.
`TeleportAWSAccess`	IAM role	Allows the Application Service to assume other roles in order to proxy user requests to AWS.
`AssumeRole`	IAM policy	Allows the Application Service to assume other roles in order to proxy user requests to AWS.
`TeleportAWSAccess` (for EC2 deployments)	EC2 instance profile	Associates the `TeleportAWSAccess` role with your EC2 instance.

Create a role for the Teleport Application Service

In this section, you will create an IAM role that allows the Teleport Application Service to assume other IAM roles in order to proxy user traffic to AWS APIs.

Define a trust policy to enable the Teleport Application Service to assume the role you will create.

Create a file called app-service-tp.json:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow", 
      "Principal": {
        "Service": "ec2.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Retrieve your OIDC issuer ID, assigning cluster-name to the name of your EKS cluster and eks-region to the AWS region where your EKS cluster is running:

$ aws --region=eks-region eks describe-cluster --name cluster-name --query "cluster.identity.oidc.issuer" --output text | grep -Eo "[A-Z0-9]+$"

AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

Create a file called app-service-tp.json with the following content, assigning oidc-issuer to the issuer string you retrieved and EKS_ACCOUNT to the ID of the AWS account that belongs to your EKS cluster:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::EKS_ACCOUNT:oidc-provider/oidc.eks.EKS_REGION.amazonaws.com/id/OIDC_ISSUER"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "oidc.eks.EKS_REGION.amazonaws.com/id/OIDC_ISSUER:aud": "sts.amazonaws.com",
                     "oidc.eks.EKS_REGION.amazonaws.com/id/OIDC_ISSUER:sub": "system:serviceaccount:teleport-agent:teleport-kube-agent"

                }
            }
        }
    ]
}

Later in this guide, we will install a Helm chart to deploy the Teleport Application Service. The chart assigns the Teleport pod to a service account called teleport-kube-agent. This trust policy authorizes workloads with this service account in the teleport-agent namespace to assume the IAM role we create in this section.

Create a role for the Teleport Application Service:

$ aws iam create-role --role-name "TeleportAWSAccess" \
--assume-role-policy-document file://app-service-tp.json

Get the ARN of the ExampleReadOnlyAccess role:

$ ROLE_ARN=$(aws iam get-role --role-name ExampleReadOnlyAccess --query "Role.Arn" --output text)

Define an IAM policy to allow the Teleport Application Service to assume the ExampleReadOnlyAccess role:

$ cat<<EOF > teleport-assume-role.json
{ "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": "${ROLE_ARN}"
    }
  ]
}
EOF

$ POLICY_ARN=$(aws iam create-policy --policy-name=AssumeExampleReadOnlyRole \
--policy-document file://teleport-assume-role.json | jq -r '.Policy.Arn')
$ aws iam attach-role-policy --role-name TeleportAWSAccess \
--policy-arn ${POLICY_ARN}

Configure a role for Teleport users to request

In this section, you will create a role that Teleport users can request access to when making requests to AWS APIs. The Teleport Application Service assumes this role when proxying requests:

Obtain AWS credentials for the account where you will run the Teleport Application Service and make them available to your terminal shell.
Create a trust policy document, which authorizes an entity to assume the role you want to protect access to. To do so, create a file called ro-access.json with the following content, replacing AWS_ACCESS_ACCOUNT with the ID of the AWS account where you will run the Teleport Application Service:
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::AWS_ACCESS_ACCOUNT:role/TeleportAWSAccess"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```
In the setup we show in this guide, the Teleport Application Service assumes the TeleportAWSAccess role, then uses that role to assume the ExampleReadOnlyAccess role. With the trust policy above, AWS authorizes this operation.
Cross-account access
If you are configuring the Application Service to proxy access to IAM roles in another AWS account, we recommend checking the external ID of the AWS account where the Application Service runs. Add the external ID to the trust policy as follows, assigning EXTERNAL_ID to the external ID:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::AWS_ACCESS_ACCOUNT:role/TeleportAWSAccess" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "EXTERNAL_ID" } } } ] }
See the AWS documentation for details on external IDs.

Run the following commands to create the ExampleReadOnlyAccess role:

$ aws iam create-role --role-name "ExampleReadOnlyAccess" \
--assume-role-policy-document file://ro-access.json

Get the ARN of the AWS-managed ReadOnlyAccess policy so you can attach it to your role:

$ ARN=$(aws iam list-policies --output text --query "Policies[?PolicyName=='ReadOnlyAccess'].Arn")

Attach the ReadOnlyAccess policy to the role:

$ aws iam attach-role-policy --role-name ExampleReadOnlyAccess --policy-arn $ARN

Associate a role with the Teleport Application Service

Now that you have created a role for the Teleport Application Service, associate the role with the service.

In this section, you will add the TeleportAWSAccess role to the instance profile of the EC2 instance where you will install the Teleport Application Service.

Create an instance profile:

$ aws iam create-instance-profile --instance-profile-name TeleportAWSAccess

Add the TeleportAWSAccess role to the profile:

$ aws iam add-role-to-instance-profile \
--instance-profile-name TeleportAWSAccess \
--role-name TeleportAWSAccess

Obtain the ID of the EC2 instance where you will install the Teleport Application Service.

Run the following command to associate the new instance profile with your instance:

$ aws ec2 associate-iam-instance-profile --iam-instance-profile Name="TeleportAWSAccess" \
--instance-id INSTANCE_ID --region AWS_REGION

Annotate the service account used by the Teleport Application Service to instruct it to assume the TeleportAWSAccess role:

$ kubectl annotate serviceaccount \
-n teleport-agent \
teleport-kube-agent eks.amazonaws.com/role-arn=arn:aws:iam::EKS_ACCOUNT:role/TeleportAWSAccess

Step 2/4. Configure Teleport IAM role mapping

In this step, you will define a Teleport role that confers access to the ExampleReadOnlyAccess IAM role you created in the previous step.

Create a file called aws-ro-access.yaml with the following content, replacing AWS_ACCOUNT with the ID of the account where you created the ExampleReadOnlyAccess role:
```
kind: role
version: v5
metadata:
  name: aws-ro-access
spec:
  allow:
    app_labels:
      '*': '*'
    aws_role_arns:
    - arn:aws:iam::AWS_ACCOUNT:role/ExampleReadOnlyAccess
```
The Teleport role called aws-ro-access enables users to visit the AWS Management Console or make requests to AWS APIs with the ExampleReadOnlyAccess role.
Create the role:
```
$ tctl create aws-ro-access.yaml
```
Assign the aws-ro-access role to your Teleport user by running the appropriate commands for your authentication provider:
- Local User
- GitHub
- SAML
- OIDC
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-ro-access to the list of existing roles:
  
  roles: - access - auditor - editor + - aws-ro-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.
1. 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.
2. Edit github.yaml, adding aws-ro-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-ro-access
3. Apply your changes:
  
  $ tctl create -f github.yaml
4. Sign out of the Teleport cluster and sign in again to assume the new role.
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-ro-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-ro-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.
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-ro-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-ro-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.

Step 3/4. Set up the Teleport Application Service

Now that you have configured RBAC resources in AWS and Teleport, the remaining step is to launch the Teleport Application Service.

Get a join token

Establish trust between your Teleport cluster and your new Application Service instance by creating a join token:

$ tctl tokens add --type=app --ttl=1h --format=text
abcd123-insecure-do-not-use-this

On the host where you will install the Teleport Application Service, create a file called /tmp/token that consists only of your token:

$ echo join-token | sudo tee /tmp/token

Install the Teleport Application Service

Run the following commands on the host where you will install the Teleport Application Service:

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