Skip to main content
Version: 19.x (unreleased)

AWS Console and CLI Access with Roles Anywhere

Report an Issue

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.

In this guide, you will:

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

      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:

      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.

  • Check that you can connect to your Teleport cluster and verify that you can run tctl and tsh commands using your current credentials.

    1. Assign teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and [email protected] to your Teleport username.

    2. Authenticate to your Teleport cluster. This depends on whether your shell is interactive or not.

      In an interactive shell: Run the following command. By default, this triggers a multi-factor authentication prompt:

      tsh login --proxy=teleport.example.com --user=[email protected]
      tctl status
      Cluster  teleport.example.com
      Version  19.0.0-dev
      CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

      On non-interactive environments: If you are running tsh and tctl as an AI agent, in a CI/CD environment, or similar, make sure the TELEPORT_IDENTITY_FILE environment variable is assigned to a valid file path with credentials for your cluster. tsh and tctl read the file path from the environment variable and do not require a separate authentication step. If there is no identity file available, we recommend that you set up Machine ID to provision one automatically.

      When executing tctl commands with an identity file, you must pass the --auth-server flag to provide the Teleport Auth Service address, which is not included in the identity file. If you provide the Proxy Service address, tctl connects to the Proxy Service, which forwards traffic to and from the Teleport Auth Service. Update 443 to 3025 if you are contacting the Auth Service directly with tctl:

      tctl status --auth-server=teleport.example.com:443

      For tsh commands that read an identity file, you must pass the --proxy flag, which points tsh to the address of the Teleport Proxy Service:

      tsh status --proxy=teleport.example.com

      Ensure client commands can access your identity file. Replace path/to/identity/file with the path to your identity file:

      export TELEPORT_IDENTITY_FILE="${TELEPORT_IDENTITY_FILE:-path/to/identity/file}"

      Add the --auth-server or --proxy flags to all subsequent tctl and tsh commands.

    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.

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:

NameResourceFunction
TeleportRolesAnywhereIntegrationCAIAM Roles Anywhere trust anchorAllows access from Teleport into AWS.
TeleportRolesAnywhereProfileSyncIAM roleAllows Teleport to iterate over AWS Roles Anywhere profiles and import them as resources.
TeleportRolesAnywhereProfileSyncIAM Roles Anywhere profileAllows 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.

  1. Obtain the Teleport certificate:

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

  2. Navigate to the Create a trust anchor page in the AWS Console.

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

  4. Click Create trust anchor.

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

  1. Navigate to Create Role in the AWS Console.

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

  3. On the Add permissions page, do not attach any permissions policies yet. Click Next.

  4. Name the role TeleportRolesAnywhereProfileSync and click Create role.

  5. On the role detail page, copy the Role ARN Role ARN.

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

  7. Navigate to Create a Profile in the AWS Console.

  8. Fill in the form:

    • Profile name: TeleportRolesAnywhereProfileSync
    • Roles: add the TeleportRolesAnywhereProfileSync role you just created.
    • Leave Session policies empty.

    Click Create profile.

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

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

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

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

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

If the integration is not syncing, try the following:

  • If synced_profiles is 0 or profiles are missing from the Web UI, confirm that profile_name_filters is set to * to import all profiles, or that your filter matches the profile names in AWS:

    profile_sync_config:
  enabled: true
  profile_name_filters:
  - '*'

  • If error_message is non-empty, check that the TeleportRolesAnywhereProfileSync IAM role has the inline policy attached and that the trust anchor ARN and profile ARN in the integration match what was created in AWS.

  • If you see a Bad Request error when trying to assume a role via the app in Teleport, the most likely cause is that the Roles Anywhere trust policy JSON was pasted into the Session policies field on the profile creation page instead of into the Custom trust policy editor on the Select trusted entity page when creating the IAM role. Delete the misconfigured resource, return to Create role, select Custom trust policy on the first page, and paste the JSON there. Leave Session policies empty when creating the profile.

You can reach out to our Slack community or customer support for help.

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.

  1. Navigate to Create role in the AWS Console.

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

  3. On the Add permissions page, search for and attach the AWS-managed ReadOnlyAccess policy.

  4. Name the role ExampleReadOnlyAccess and click Create role.

  5. On the role detail page, copy the Role ARN Read Only Role ARN.

  6. Navigate to Create a Profile in the AWS Console.

  7. Fill in the form:

    • Profile name: ExampleReadOnlyAccess
    • Roles: add the ExampleReadOnlyAccess role you just created.
    • Leave Session policies empty, then click Create profile.

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

  1. In the Teleport Web UI, navigate to Zero Trust Access > Roles and click Create New Role.

  2. Set the role name to example-read-only-access.

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

  4. Click through the remaining steps and create the role.

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

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.

If the new role is not active, try the following:

  • If the role is not listed in tsh status, confirm it was assigned to your user or Access List and that you have logged out and back in since the assignment.
  • If the AWS profile does not appear in the next step when running tsh apps login, the most common cause is needing to log in again. Run tsh logout and tsh login again before continuing.

You can reach out to our Slack community or customer support for help.

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​

  1. In the Teleport Web UI, click Resources. Each synced Roles Anywhere profile will appear as an AWS application.
  2. Click Launch on the AWS Console application, then select the IAM role you want to assume.
  3. 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

To list the AWS roles that you can provide to the --aws-role flag, run the following command: tsh apps logins [--format=text|json|yaml] <app>.

tsh apps logins aws-console
Available AWS roles:Role Name             Role ARN--------------------- ----------------------------------------------------ExampleAdminAccess    arn:aws:iam::123456789012:role/ExampleReadOnlyAccessExampleReadOnlyAccess arn:aws:iam::123456789012:role/ExampleAdminAccess

Alternatively, if the --aws-role is not provided, the aws role will be prompted interactively.

tsh apps login aws-console
Available AWS roles:
> ExampleReadOnlyAccess [arn:aws:iam::000000000000:role/ExampleReadOnlyAccess]  ExampleAdminAccess [arn:aws:iam::000000000001:role/ExampleAdminAccess]
(Use arrows or hjkl to navigate, enter to select, q to quit)

You can turn interactive prompt off using --no-interactive flag. This will make the command return an error when no role is provided.

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.

If AWS CLI commands fail, try the following:

  • If tsh apps login does not list the expected profile, run tsh logout and tsh login to refresh your session, then try again.
  • If sts get-caller-identity returns an error, confirm that the profile ARN in your Teleport role's app_labels exactly matches the ARN of the profile created in Step 2/4.
  • If you see an AccessDenied error from the AWS CLI, verify that the IAM role has the ReadOnlyAccess policy attached and that the Roles Anywhere profile includes that role.

You can reach out to our Slack community or customer support for help.

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.