Version: 19.x (unreleased)

AWS Console and CLI Access with Roles Anywhere

Is this page helpful?

Teleport integrates with AWS IAM Roles Anywhere to provide AWS Console and CLI access. This allows you to take advantage of Teleport role-based access controls, just-in-time Access Requests, and other Teleport Zero Trust Access and Identity Governance capabilities to manage access to your AWS infrastructure.

This guide describes the Roles Anywhere integration, which is the recommended approach when you are already using AWS IAM Roles Anywhere and want full compatibility with AWS API-based tooling such as the AWS CLI or Terraform. Because Roles Anywhere issues credentials directly to the client, AWS API traffic goes from the client to AWS without passing through a Teleport Agent or the Teleport Proxy Service at request time. Teleport still controls who can obtain credentials and enforces RBAC on every credential issuance, but it is not in the data path for subsequent AWS API calls.

If you instead want AWS CLI traffic to be proxied by Teleport so that every API call is captured in the Teleport audit log, or if Roles Anywhere is not adopted at your organization, see the guide for agent-based AWS access instead.

This guide will explain how to:

Configure AWS Console and CLI access with Teleport using Roles Anywhere
Access the AWS Management Console
Access the AWS Command Line Interface (CLI)
Access applications using AWS SDKs

How it works

Teleport uses AWS IAM Roles Anywhere to issue temporary credentials for assuming target IAM roles. Access is managed through Teleport's RBAC policies, ensuring credentials are only generated for authorized users and roles. No additional Teleport service is required: credential issuance and RBAC enforcement are handled by the Teleport control plane (the Auth Service and the Proxy Service).

For web console access, navigate to the Resources page in the Teleport Web UI and click on the AWS application named after the Roles Anywhere profile.

For CLI and SDK-based access, use tsh to obtain AWS credentials.

Prerequisites

A running Teleport cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.
The tctl and tsh clients.
Installing tctl and tsh clients
1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:
  - Mac/Linux
  - Windows - Powershell
  TELEPORT_DOMAIN=teleport.example.com:443
  TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
2. Follow the instructions for your platform to install tctl and tsh clients:
  - Mac
  - Windows - Powershell
  - Linux
  Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:
  curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
  In Finder double-click the pkg file to begin installation.
  danger
  Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

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. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and [email protected] to your Teleport username:
```
tsh login --proxy=teleport.example.com --user=[email protected]
tctl status
Cluster  teleport.example.com
Version  19.0.0-dev
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.
Permissions in AWS to:
- Create IAM Roles Anywhere trust anchors
- Create IAM Roles Anywhere profiles
- Create IAM roles
The aws CLI tool installed and in PATH. See the AWS documentation to install or update the latest version of the AWS CLI.

Step 1/4. Configure AWS IAM Roles Anywhere integration

In this section, you will configure AWS IAM resources to allow Teleport to issue AWS credentials. You can use the guided flow in the Teleport Web UI, or configure the AWS resources and Teleport integration manually. Once either path is complete, verify the integration is syncing profiles before moving on.

Use the guided flow (recommended)

Navigate to the Teleport Web UI, click Enroll New Resource on the Resources listing page, and follow the guide after clicking the AWS CLI/Console Access via AWS Roles Anywhere tile.

When the guide completes, Teleport starts syncing AWS IAM Roles Anywhere profiles as AWS applications every 5 minutes.

Manually configure the integration

If you are not using the guided flow, create the following resources in AWS, then create the Teleport integration manually:

Name	Resource	Function
`TeleportRolesAnywhereIntegrationCA`	IAM Roles Anywhere trust anchor	Allows access from Teleport into AWS.
`TeleportRolesAnywhereProfileSync`	IAM role	Allows Teleport to iterate over AWS Roles Anywhere profiles and import them as resources.
`TeleportRolesAnywhereProfileSync`	IAM Roles Anywhere profile	Allows access to the `TeleportRolesAnywhereProfileSync` IAM role.

Create an IAM Roles Anywhere Trust Anchor

First, create an IAM Roles Anywhere Trust Anchor that trusts Teleport's AWS Roles Anywhere CA. You can reference the AWS Guide Getting started with IAM Roles Anywhere.

Obtain the Teleport certificate:

tctl auth export --type awsra
-----BEGIN CERTIFICATE-----MIIDqjCCApKgAwIBAgIQMIK8/WiQ/rUOrjlmB0IHVTANBgkqhkiG9w0BAQsFADBv...-----END CERTIFICATE-----

Navigate to the Create a trust anchor page in the AWS Console.
Fill in the form:
- Trust anchor name: TeleportRolesAnywhereIntegrationCA
- Certificate bundle: select External certificate bundle, then paste the full certificate output from the previous step into the text field, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.
Click Create trust anchor.
On the trust anchor detail page, copy the Trust Anchor ARN Trust Anchor ARN.

Set up Profile Sync

Next, create the required AWS resources to enable profile sync.

Navigate to Create Role in the AWS Console.

On the Select trusted entity page, select Custom trust policy and replace the default policy with the following:

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

Trust policy placement

Paste this JSON into the Custom trust policy editor on the Select trusted entity page, not into a permissions policy and not into the Session policies field on the profile creation page. Placing it in the wrong field will cause a Bad Request error when a user tries to assume the role.

On the Add permissions page, do not attach any permissions policies yet. Click Next.
Name the role TeleportRolesAnywhereProfileSync and click Create role.
On the role detail page, copy the Role ARN Role ARN.

On the same role detail page, select the Permissions tab and click Add permissions > Create inline policy.

Switch to the JSON view and enter the following:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "RolesAnywhereProfileSync",
            "Effect": "Allow",
            "Action": [
                "rolesanywhere:ListProfiles",
                "rolesanywhere:ListTagsForResource",
                "rolesanywhere:ImportCrl",
                "iam:GetRole"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

Name the policy and click Create policy.

Navigate to Create a Profile in the AWS Console.
Fill in the form:
- Profile name: TeleportRolesAnywhereProfileSync
- Roles: add the TeleportRolesAnywhereProfileSync role you just created.
- Leave Session policies empty.
Click Create profile.
On the profile detail page, copy the Profile ARN Profile ARN.

Create a Teleport AWS IAM Roles Anywhere integration

Now that the required AWS resources are created, create the Teleport integration.

Write the following contents to a file called roles-anywhere-integration.yaml:

kind: integration
sub_kind: aws-ra
version: v1
metadata:
  name: Integration Name
spec:
  aws_ra:
    trust_anchor_arn: Trust Anchor ARN
    profile_sync_config:
      enabled: true
      profile_arn: Profile ARN
      role_arn: Role ARN

Create the integration:

tctl create -f roles-anywhere-integration.yaml

Verify the integration is syncing profiles

After either the guided flow or the manual configuration completes, Teleport begins syncing AWS IAM Roles Anywhere profiles as AWS applications. Sync runs every 5 minutes, so allow a few minutes after creation before checking.

Check the integration status from the command line:
```
tctl get integration/Integration Name
```
Look for the status.aws_ra.last_profile_sync block in the output:
```
status:
  aws_ra:
    last_profile_sync:
      status: SUCCESS
      synced_profiles: 4
      error_message: ""
```
A healthy integration shows status: SUCCESS, a non-zero synced_profiles count that matches the number of profiles in your AWS account (or the subset matching your profile_name_filters), and an empty error_message.
Confirm the synced profiles appear in the Web UI. Navigate to the Resources page. Each Roles Anywhere profile should appear as an AWS application named after the profile.

Checkpoint: The Roles Anywhere integration is syncing profiles

The integration status reports SUCCESS with a non-zero synced_profiles count, and each Roles Anywhere profile appears as an AWS application on the Resources page.

Step 2/4. Create an AWS IAM Roles Anywhere profile and assign IAM roles

Now you will create an example profile and role to test the integration.

If you are already using AWS IAM Roles Anywhere profiles, you can skip this step.

Navigate to Create role in the AWS Console.

On the Select trusted entity page, select Custom trust policy and replace the default policy with the following:

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

Trust policy placement

On the Add permissions page, search for and attach the AWS-managed ReadOnlyAccess policy.
Name the role ExampleReadOnlyAccess and click Create role.
On the role detail page, copy the Role ARN Read Only Role ARN.
Navigate to Create a Profile in the AWS Console.
Fill in the form:
- Profile name: ExampleReadOnlyAccess
- Roles: add the ExampleReadOnlyAccess role you just created.
- Leave Session policies empty, then click Create profile.
On the profile detail page, copy the Profile ARN Read Only Profile ARN.

Step 3/4. Set up access

Grant your users access to the imported AWS profiles and roles by creating a Teleport role.

Web UI
Via tctl

In the Teleport Web UI, navigate to Zero Trust Access > Roles and click Create New Role.
Set the role name to example-read-only-access.
In the Resources section, add an Application Access entry with the following values:
- Labels: teleport.dev/aws-roles-anywhere-profile-arn: Read Only Profile ARN
- AWS Role ARNs: Read Only Role ARN
Click through the remaining steps and create the role.
Verify the role was created by navigating back to Zero Trust Access > Roles. The example-read-only-access role should appear in the list with the labels and ARN values you entered.

Create a file named example-read-only-access-role.yaml with the following contents:

kind: role
version: v8
metadata:
  name: example-read-only-access
spec:
  allow:
    app_labels:
      'teleport.dev/aws-roles-anywhere-profile-arn': 'Read Only Profile ARN'
    aws_role_arns:
    - Read Only Role ARN

Create the role:

tctl create -f example-read-only-access-role.yaml

Verify the role was created and contains the expected values:
```
tctl get role/example-read-only-access
```
The output should show the role with the correct app_labels and aws_role_arns values.

Assign this role to the users you want to grant access. You can also assign it to an Access List or use it with Access Requests.

After assigning the role, re-authenticate to pick up the new permissions. example.teleport.sh:443 is your Teleport Proxy address and Username is your Teleport username:

tsh logout
tsh login --proxy=example.teleport.sh:443 --user=Username

Confirm the role appears in your session:

tsh status

The example-read-only-access role should appear in the roles list.

Checkpoint: The new role is active in your Teleport session

After logging out and back in, tsh status lists example-read-only-access among your active roles.

Step 4/4. Access AWS resources

In this step, you will access AWS under the role you granted yourself in Step 3/4. This section covers two workflows: signing into the AWS Management Console through the Teleport Web UI, and obtaining AWS credentials for the AWS CLI, SDKs, and tools like Terraform.

Access AWS Management Console

In the Teleport Web UI, click Resources. Each synced Roles Anywhere profile will appear as an AWS application.
Click Launch on the AWS Console application, then select the IAM role you want to assume.
You will be redirected to the AWS Management Console, signed in under the selected role. Your Teleport username will appear as a federated login in the top-right corner of the console.

Access AWS using the AWS CLI or AWS SDK-based tools

To use AWS CLI-based or SDK-based tools, first obtain credentials by logging into the AWS app, then point your tool at the resulting AWS profile.

Obtain the credentials

Log into the AWS app profile that was synced:

tsh apps login --aws-role arn:aws:iam::123456789012:role/ExampleReadOnlyAccess example-read-only-access
Logged into AWS app "example-read-only-access".
Your IAM role:
    arn:aws:iam::123456789012:role/ExampleReadOnlyAccess
Example AWS CLI commands:
    aws --profile example-read-only-access s3 ls    AWS_PROFILE=example-read-only-access aws s3 ls

Access AWS using the AWS CLI

Pass the --profile flag or export AWS_PROFILE with the profile name:

aws --profile example-read-only-access s3 ls
...

Access AWS from Terraform

Set the profile in the provider block:

provider "aws" {
  profile = "example-read-only-access"
  // ...
}

Setting the AWS_PROFILE environment variable is also an option.

Confirm credentials are working

Run a basic AWS CLI command to confirm the credentials are valid:

aws --profile example-read-only-access sts get-caller-identity

The output should show the ExampleReadOnlyAccess role ARN and your Teleport username as the assumed-role session name.

Confirm access is limited to read-only operations as expected:

aws --profile example-read-only-access s3 ls

Checkpoint: The AWS CLI can call AWS APIs under the assumed role

sts get-caller-identity returns the ExampleReadOnlyAccess role ARN with your Teleport username as the session name, and read-only AWS commands succeed.

Next steps

Refine your AWS IAM role mapping

The aws_role_arns field supports template variables that are populated dynamically at authentication time. For example, you can configure your identity provider to define a SAML attribute or OIDC claim called aws_role_arns, then reference it in a Teleport role:

    aws_role_arns:
    - {{external.aws_role_arns}}

See "Template expressions for access to infrastructure resources" in the Access Controls Reference for the traits (like {{internal.aws_role_arns}} and {{external.xyz}}) and functions available in the aws_role_arns field.

Create roles to grant access to specific profiles and IAM roles

You can create multiple Teleport roles to grant access to different profiles and IAM roles.

See Role Access Requests to learn how to use Access Requests to manage access to these roles.

Was this page helpful?

How it works​

Prerequisites​

Step 1/4. Configure AWS IAM Roles Anywhere integration​

Use the guided flow (recommended)​

Manually configure the integration​

Create an IAM Roles Anywhere Trust Anchor​

Set up Profile Sync​

Create a Teleport AWS IAM Roles Anywhere integration​

Verify the integration is syncing profiles​

Step 2/4. Create an AWS IAM Roles Anywhere profile and assign IAM roles​

Step 3/4. Set up access​

Step 4/4. Access AWS resources​

Access AWS Management Console​

Access AWS using the AWS CLI or AWS SDK-based tools​

Obtain the credentials​

Access AWS using the AWS CLI​

Access AWS from Terraform​

Confirm credentials are working​

Next steps​

Refine your AWS IAM role mapping​

Create roles to grant access to specific profiles and IAM roles​