Teleport

Access AWS With Teleport Application Access

OpenSource
Enterprise
Cloud

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 one of our Getting Started guides.
The tctl admin tool and tsh client tool version >= 13.0.3.
```
tctl version
Teleport v13.0.3 go1.20
tsh version
Teleport v13.0.3 go1.20
```
See Installation for details.

A running Teleport Enterprise cluster. For details on how to set this up, see our Enterprise Getting Started guide.
The Enterprise tctl admin tool and tsh client tool version >= 13.0.3, which you can download by visiting your Teleport account.
```
tctl version
Teleport Enterprise v13.0.3 go1.20
tsh version
Teleport v13.0.3 go1.20
```

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

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.
A host running the teleport daemon with the Application Service enabled. Follow the Getting Started or Connecting Apps guides to get it running.
IAM permissions in the AWS account you want to connect.
AWS EC2 or other instance where you can assign a IAM Security Role for the Teleport Agent.
aws command line interface (CLI) tool in PATH. Installing or updating the latest version of the AWS CLI

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

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

Apply your changes:

tctl create -f oidc.yaml

Warning

Note the --with-secrets flag in the tctl get command. This adds the value of spec.signing_key_pair.private_key to oidc.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 5/9. Register AWS console application in Teleport

Configure the Application Service

Add the AWS management console to your Application Service configuration by editing /etc/teleport.yaml on the host that runs the Application Service:

version: v3
teleport:
  # Data directory for the Application Proxy service. If running on the same
  # node as Auth/Proxy service, make sure to use different data directories.
  data_dir: /var/lib/teleport-app
  # Instructs the service to load the auth token from the specified file
  # during initial registration with the cluster.
  auth_token: /var/lib/teleport-app/token
  # Proxy address to connect to. Note that it has to be the proxy address
  # because the app service always connects to the cluster over a reverse
  # tunnel.
  proxy_server: teleport.example.com:3080
app_service:
  enabled: "yes"
  apps:
  - name: "awsconsole"
  # The public AWS Console is used after authenticating the user from Teleport
    uri: "https://console.aws.amazon.com/ec2/v2/home"
auth_service:
  enabled: "no"
ssh_service:
  enabled: "no"
proxy_service:
  enabled: "no"

Note that the URI must start with one of the following values in order to be recognized as an AWS console:

Regions	AWS Console URL
Standard AWS regions	`https://console.aws.amazon.com`
AWS GovCloud (US) regions	`https://console.amazonaws-us-gov.com`
AWS China regions	`https://console.amazonaws.cn`

If you have multiple AWS accounts and would like to logically separate them in the UI, register an application entry for each and set aws_account_id label to the account ID:

app_service:
  enabled: "yes"
  apps:
  - name: "awsconsole-test"
    uri: "https://console.aws.amazon.com/ec2/v2/home"
    labels:
      aws_account_id: "1234567890"
      env: test
  - name: "awsconsole-prod"
    uri: "https://console.aws.amazon.com/ec2/v2/home"
    labels:
      aws_account_id: "0987654321"
      env: prod
  - name: "awsconsole-third-party"
    uri: "https://console.aws.amazon.com/ec2/v2/home"
    labels:
      aws_account_id: "1234554321"
    aws:
      external_id: "example-external-id"

When showing available IAM roles, Teleport will display only role ARNs that belong to the specific account.

For AWS accounts that require external IDs for accessing their resources, set the external_id field, which the Application Service uses when assuming the AWS roles in these accounts.

Start the Teleport Application Service

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

Teleport will detect when it is running on an EC2 instance and use the Instance Metadata Service to fetch credentials.

The EC2 instance should be configured to use an EC2 instance profile. For more information, see: Using Instance Profiles.

Teleport's built-in AWS client reads credentials from the following environment variables:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_DEFAULT_REGION

When you start the Application Service, the service reads environment variables from a file at the path /etc/default/teleport. Obtain these credentials from your organization. Ensure that /etc/default/teleport has the following content, replacing the values of each variable:

AWS_ACCESS_KEY_ID=00000000000000000000
AWS_SECRET_ACCESS_KEY=0000000000000000000000000000000000000000
AWS_DEFAULT_REGION=<YOUR_REGION>

Teleport's AWS client loads credentials from different sources in the following order:

Environment Variables
Shared credentials file
Shared configuration file (Teleport always enables shared configuration)
EC2 Instance Metadata (credentials only)

While you can provide AWS credentials via a shared credentials file or shared configuration file, you will need to run the Application Service with the AWS_PROFILE environment variable assigned to the name of your profile of choice.

If you have a specific use case that the instructions above do not account for, consult the documentation for the AWS SDK for Go for a detailed description of credential loading behavior.

Configure the 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 Application Service.

On the host where you will run the Application Service, enable and start Teleport:

sudo systemctl enable teleport
sudo systemctl start teleport

On the host where you will run the Application Service, create a systemd service configuration for Teleport, enable the Teleport service, and 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 Application Service with systemctl status teleport and view its logs with journalctl -fu teleport.

non-standard AWS regions

For non-standard AWS regions such as AWS GovCloud (US) regions and AWS China regions, please set the corresponding region in the AWS_REGION environment variable or in the AWS credentials file so that the Application Service can use the correct STS endpoint.

Step 6/9. Connect to AWS console with assumed IAM role

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

Click on the role you want to assume 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:

Note that your federated login session is marked with your Teleport username.

Session Duration

If Teleport is running with temporary security credentials, the management console session will be limited to a maximum of one hour.

Step 7/9. Use CloudTrail to see Teleport user activity

To view CloudTrail events for your federated sessions, navigate to the CloudTrail dashboard and go to "Event history".

Each Teleport federated login session uses a Teleport username as the federated username which you can search for to get the events history:

Step 8/9. Access AWS CLI

Before beginning this step, make sure that the aws command line interface (CLI) tool is installed in PATH. For more information, read Installing or updating the latest version of the AWS CLI.

First, log into the previously configured AWS console app on your desktop:

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

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

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

tsh aws s3 ls

To log out of the aws application and remove credentials:

tsh apps logout awsconsole-test

Step 9/9. Access applications using AWS SDKs

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

tsh apps login --aws-role ExamplePowerUser awsconsole-test

Now, use the following command to start a local HTTPS proxy server your applications will be connecting to:

tsh proxy aws -p 23456
Started AWS proxy on http://127.0.0.1:23456.
Use the following credentials and HTTPS proxy setting to connect to the proxy:
  AWS_ACCESS_KEY_ID=abcd1234-this-is-an-example
  AWS_SECRET_ACCESS_KEY=zyxw9876-this-is-an-example
  AWS_CA_BUNDLE=<ca-bundle-path>
  HTTPS_PROXY=http://127.0.0.1:23456

Use the displayed AWS credentials and HTTPS proxy settings when configuring your application.

It is important to check how AWS credentials and HTTPS proxy setting can be configured for your application. For example, many command line tools like terraform or eksctl support setting the above AWS credentials and the HTTPS proxy using environment variables:

export AWS_ACCESS_KEY_ID=abcd1234-this-is-an-example
export AWS_SECRET_ACCESS_KEY=zyxw9876-this-is-an-example
export AWS_CA_BUNDLE=<ca-bundle-path>
export HTTPS_PROXY=http://127.0.0.1:23456
terraform plan

If you are developing your own applications using AWS SDKs, some SDKs may require extra environment variables (e.g. AWS_SDK_LOAD_CONFIG=true for AWS SDK for Go v2) or require configuring the HTTPS proxy through code (e.g. AWS SDK for JavaScript).

To log out of the AWS application and remove credentials:

tsh apps logout awsconsole-test

Next steps

Take a closer look at role-based access controls.
Explore other application access guides.

Have a suggestion or can’t find something?

IMPROVE THE DOCS