teleport/docs/pages/application-access/cloud-apis/aws-console.mdx

---
title: Access AWS With Teleport Application Access
description: How to access AWS with Teleport Application Access.
videoBanner: GVcy_rffxQw
---

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, either self hosted or in Teleport Cloud.
- A host running the `teleport` daemon with Application Access enabled. Follow
  the [Getting Started](../getting-started.mdx) or
  [Connecting Apps](../guides/connecting-apps.mdx) 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
](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)

<Admonition type="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.
</Admonition>

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

<Admonition type="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.
</Admonition>

### Create the example Read Only role

Go to the IAM -> Access Management -> [Roles](https://console.aws.amazon.com/iamv2/home#/roles).
Press Create Role.

![Create Role Step 1](../../../img/application-access/create-role-example-readonly-1.png)

### Select the ReadOnlyAccess policy

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

![Select Role Step 2](../../../img/application-access/create-role-example-readonly-2.png)

Press next through the tags

### Confirm role

Enter a role name and press create role.

![Create Role Step 3](../../../img/application-access/create-role-example-readonly-3.png)


### 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

<Admonition type="note">
This step is only required if you are allowing access from another account. The trust relationship will already exist for the same account.
</Admonition>

Teleport uses AWS [federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_enable-console-custom-url.html) 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](https://console.aws.amazon.com/iamv2/home#/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:

```yaml
{
  "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](https://aws.amazon.com/blogs/security/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.
![AWS trusted entities](../../../img/application-access/aws-trusted-entities@2x.png)

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:

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

<Admonition type="note">
You can make the policy more strict by providing specific IAM role resource
ARNs in the Resource field instead of using a wildcard.
</Admonition>

Attach this policy to the IAM role/user your Teleport application service agent
is using.

![AWS Attach Security Role](../../../img/application-access/attach-security-role.png)

## 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:

```yaml
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](../../access-controls/guides/role-templates.mdx) for details.

(!docs/pages/includes/add-role-to-user.mdx role="aws-console-access"!)

## 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:

```yaml
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` |

<Details title="Multiple AWS accounts">

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:

```yaml
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.

</Details>

### Start the Teleport Application Service

(!docs/pages/includes/aws-credentials.mdx service="the Application Service"!)

(!docs/pages/includes/start-teleport.mdx service="the Application Service"!)

<Admonition type="warning" title="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.
</Admonition>

## 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:

![IAM role selector](../../../img/application-access/iam-role-selector.png)

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:

![Federated login](../../../img/application-access/federated-login@2x.png)

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

<Admonition type="note" title="Session Duration">
    If Teleport is running with [temporary security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html),
    the management console session will be limited to a maximum of one hour.
</Admonition>

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

To view CloudTrail events for your federated sessions, navigate to the CloudTrail
[dashboard](https://console.aws.amazon.com/cloudtrail/home) 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:

![CloudTrail](../../../img/application-access/cloud-trail.png)

## 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](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html).

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

```code
$ 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:

```code
$ tsh aws s3 ls
```

To log out of the aws application and remove credentials:

```code
$ 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:

```code
$ 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:

```code
$ 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=(=aws.aws_access_key=)
  AWS_SECRET_ACCESS_KEY=(=aws.aws_secret_access_key=)
  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:

```code
$ export AWS_ACCESS_KEY_ID=(=aws.aws_access_key=)
$ export AWS_SECRET_ACCESS_KEY=(=aws.aws_secret_access_key=)
$ 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:

```code
$ tsh apps logout awsconsole-test
```

## Next steps

- Take a closer look at [role-based access controls](../controls.mdx).
- Explore other application access [guides](../guides.mdx).