{"token_count": 5407} # AWS Console and CLI Access with Roles Anywhere 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](https://goteleport.com/docs/enroll-resources/application-access/cloud-apis/aws-console.md) 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](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md). - 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** ``` $ TELEPORT_DOMAIN=teleport.example.com:443 $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')" ``` **Windows - Powershell** ``` $ $TELEPORT_DOMAIN = "teleport.example.com:443" $ $TELEPORT_VERSION = (Invoke-RestMethod -Uri "https://${TELEPORT_DOMAIN}/v1/webapi/find").server_version ``` 2. Follow the instructions for your platform to install `tctl` and `tsh` clients: **Mac** 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. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v$TELEPORT_VERSION-windows-amd64-bin.zip Unzip the archive and move the `tctl` and `tsh` clients to your %PATH% NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP. Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation/single-machine.md). ``` $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ cd teleport $ sudo ./install Teleport binaries have been copied to /usr/local/bin ``` * 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\@example.com to your Teleport username: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ 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. Running `tctl` on a Teleport beam In some environments, for example on a Teleport beam, Teleport authentication must take place through a local identity file. On a Teleport beam, the identity file is available automatically, and `tctl` reads the file path from the `TELEPORT_IDENTITY_FILE` environment variable. 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. On a beam, you must use the Proxy Service address, as the Auth Service is not exposed to the public internet. You can do so by using the `TELEPORT_PROXY` environment variable: ``` $ tctl status --auth-server=${TELEPORT_PROXY} ``` * 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](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html). ## 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](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/getting-started.html). 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](https://console.aws.amazon.com/rolesanywhere/home/trust-anchors/create) 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](https://console.aws.amazon.com/iam/home?#/roles/create) 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](https://console.aws.amazon.com/rolesanywhere/home/profiles/create) 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. ## 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](https://console.aws.amazon.com/iam/home?#/roles/create) 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](https://console.aws.amazon.com/rolesanywhere/home/profiles/create) 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. **Web UI** 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. **Via tctl** 1. 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 ``` 1) Create the role: ``` $ tctl create -f example-read-only-access-role.yaml ``` 2) 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](https://goteleport.com/docs/identity-governance/access-lists/guide.md) or use it with [Access Requests](https://goteleport.com/docs/identity-governance/access-requests.md). 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. ## 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] `. ``` $ tsh apps logins aws-console Available AWS roles: Role Name Role ARN --------------------- ---------------------------------------------------- ExampleAdminAccess arn:aws:iam::123456789012:role/ExampleReadOnlyAccess ExampleReadOnlyAccess 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 ``` ## 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](https://goteleport.com/docs/reference/access-controls/roles.md) 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](https://goteleport.com/docs/identity-governance/access-requests/role-requests.md) to learn how to use Access Requests to manage access to these roles.