Teleport

Access AWS With Teleport Application Access

Available for:
OpenSource
Team
Cloud
Enterprise

AWS IAM Federation using Teleport

Length: 09:16

Teleport can automatically sign your users into the AWS management console with appropriate IAM roles. Teleport also provides API access to AWS Command Line Interface (CLI) or any applications using AWS SDKs like Terraform.

This guide will explain how to:

Access AWS Management Console through Teleport.
View Teleport users' AWS console activity in CloudTrail.
Access the AWS Command Line Interface (CLI) through Teleport.
Access applications using AWS SDKs through Teleport.

Prerequisites

A running Teleport cluster. For details on how to set this up, see the Getting Started guide.
The tctl admin tool and tsh client tool version >= 14.2.1.

See Installation for details.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport v14.2.1 git:api/14.0.0-gd1e081e go1.21
  tsh version
Teleport v14.2.1 go1.21
Proxy version: 14.2.1Proxy: teleport.example.com

A Teleport Team account. If you don't have an account, sign up to begin your free trial.
The Enterprise tctl admin tool and tsh client tool, version >= 14.1.3.

You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v14.1.3 git:api/14.0.0-gd1e081e go1.21
  tsh version
Teleport v14.1.3 go1.21
Proxy version: 14.1.3Proxy: teleport.example.com

A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.
The Enterprise tctl admin tool and tsh client tool version >= 14.2.1.

You can download these tools by visiting your Teleport account workspace.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v14.2.1 git:api/14.0.0-gd1e081e go1.21
  tsh version
Teleport v14.2.1 go1.21
Proxy version: 14.2.1Proxy: teleport.example.com

A Teleport Enterprise Cloud account. If you don't have an account, sign up to begin a free trial of Teleport Team and upgrade to Teleport Enterprise Cloud.
The Enterprise tctl admin tool and tsh client tool version >= 14.1.3.

You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v14.1.3 git:api/14.0.0-gd1e081e go1.21
  tsh version
Teleport v14.1.3 go1.21
Proxy version: 14.1.3Proxy: teleport.example.com

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 protected]
tctl status
Cluster  teleport.example.com
Version  14.2.1
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 or other instance you can assign an IAM role where you will run the Teleport Application Service. The instance must be running a Linux distribution.
IAM permissions in the AWS account you want to connect.
aws command line interface (CLI) tool in PATH. Installing or updating the latest version of the AWS

Note

If using Teleport deployed in AWS EKS, you cannot use Helm chart annotations to specify the IAM permissions; you must associate the policy with the cluster role for the worker nodes. Otherwise, you will receive "400 Bad Request" errors from AWS.

Step 1/9. [Optional] Configure Read Only and Power User roles

AWS provides the ReadOnlyAccess and PowerUserAccess IAM policies that can be incorporated into roles. Skip this step if you already have the roles you want to provide access to.

Note

These policies may provide too much or not enough access for your intentions. Validate these meet your expectations if you plan on using them.

Create the example Read Only role

Go to the IAM -> Access Management -> Roles. Press Create Role.

Select the ReadOnlyAccess policy

Press Next and Select the ReadOnlyAccess. Sorting the Policy Name table from Z-A will make it faster to select.

Press next through the tags

Confirm role

Enter a role name and press create role.

Repeat for Power User

Follow the same steps and select PowerUserAccess IAM Policy to create a ExamplePowerUser role.

Step 2/9. Update IAM role trust relationships

Note

This step is only required if you are allowing access from another account. The trust relationship will already exist for the same account.

Teleport uses AWS federation to generate sign-in URLs for users, which relies on the AssumeRole API for getting temporary security credentials. You will need to update your IAM roles' "Trusted entities" to include your AWS account ID.

Go to the Roles list, pick a role and create the following trust policy for it by clicking on "Edit trust relationship" button on the "Trust relationships" tab:

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

See How to use trust policies with IAM roles for more details. After saving the trust policy, the account will show as a trusted entity.

From the EC2 dashboard select Actions -> Security -> Modify IAM Role.

Do this for each IAM role your Teleport users will need to assume.

Step 3/9. Give Teleport permissions to assume roles

Next, create a Role using this IAM policy to allow Teleport to assume IAM roles:

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

Note

You can make the policy more strict by providing specific IAM role resource ARNs in the Resource field instead of using a wildcard.

Attach this policy to the IAM role/user your Teleport Application Service agent is using.

Step 4/9. Configure Teleport IAM role mapping

The next step is to give your Teleport users permissions to assume IAM roles.

You can do this by creating a role with the aws_role_arns field listing all IAM role ARNs this particular role permits its users to assume:

kind: role
version: v5
metadata:
  name: aws-console-access
spec:
  allow:
    app_labels:
      '*': '*'
    aws_role_arns:
    - arn:aws:iam::1234567890:role/ExamplePowerUser
    - arn:aws:iam::1234567890:role/ExampleReadOnlyAccess

The aws_role_arns field supports template variables so they can be populated dynamically based on your users' identity provider attributes. See Role Templates for details.

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

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

  roles:
   - access
   - auditor
   - editor
+  - aws-console-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-console-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-console-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-console-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-console-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-console-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-console-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 5/9. Register AWS console application in Teleport

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 Edition

curl https://goteleport.com/static/install.sh | bash -s 14.2.1

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 cloud.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport-ent-updater

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"
sudo yum install teleport-ent-updater
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 cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
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/cloud/teleport-yum.repo")"

Install teleport
sudo dnf install teleport-ent-updater

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 Zypper repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use Zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")

Install teleport
sudo zypper install teleport-ent-updater

OS repository channels

The following channels are available for APT, YUM, and Zypper repos. They may be used in place of stable/v14 anywhere in the Teleport documentation.

Channel name	Description
`stable/<major>`	Receives releases for the specified major release line, i.e. `v14`
`stable/cloud`	Rolling channel that receives releases compatible with current Cloud version
`stable/rolling`	Rolling channel that receives all published Teleport releases

Before installing a teleport binary with a version besides v14, read our compatibility rules to ensure that the binary is compatible with Teleport Cloud.

When running multiple teleport binaries within a cluster, the following rules apply:

Patch and minor versions are always compatible, for example, any 8.0.1 component will work with any 8.0.3 component and any 8.1.0 component will work with any 8.3.0 component.
Servers support clients that are 1 major version behind, but do not support clients that are on a newer major version. For example, an 8.x.x Proxy Service is compatible with 7.x.x resource services and 7.x.x tsh, but we don't guarantee that a 9.x.x resource service will work with an 8.x.x Proxy Service. This also means you must not attempt to upgrade from 6.x.x straight to 8.x.x. You must upgrade to 7.x.x first.
Proxy Services and resource services do not support Auth Services that are on an older major version, and will fail to connect to older Auth Services by default. This behavior can be overridden by passing --skip-version-check when starting Proxy Services and resource services.

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