
Teleport
Access AWS With Teleport Application Access
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
- OpenSource
- Team
- Cloud
- Enterprise

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 the Getting Started guide.
-
The
tctl
admin tool andtsh
client tool version >= 14.2.1.See Installation for details.
To check version information, run the tctl version
and tsh version
commands.
For example:
tctl versionTeleport v14.2.1 git:api/14.0.0-gd1e081e go1.21
tsh versionTeleport v14.2.1 go1.21
Proxy version: 14.2.1Proxy: teleport.example.com
-
A Teleport Team account. If you don't have an account, sign up to begin your free trial.
-
The Enterprise
tctl
admin tool andtsh
client tool, version >= 14.1.3.You can download these tools from the Cloud Downloads page.
To check version information, run the tctl version
and tsh version
commands.
For example:
tctl versionTeleport Enterprise v14.1.3 git:api/14.0.0-gd1e081e go1.21
tsh versionTeleport v14.1.3 go1.21
Proxy version: 14.1.3Proxy: teleport.example.com
-
A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 14.2.1.You can download these tools by visiting your Teleport account workspace.
To check version information, run the tctl version
and tsh version
commands.
For example:
tctl versionTeleport Enterprise v14.2.1 git:api/14.0.0-gd1e081e go1.21
tsh versionTeleport v14.2.1 go1.21
Proxy version: 14.2.1Proxy: teleport.example.com
-
A Teleport Enterprise Cloud account. If you don't have an account, sign up to begin a free trial of Teleport Team and upgrade to Teleport Enterprise Cloud.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 14.1.3.You can download these tools from the Cloud Downloads page.
To check version information, run the tctl version
and tsh version
commands.
For example:
tctl versionTeleport Enterprise v14.1.3 git:api/14.0.0-gd1e081e go1.21
tsh versionTeleport v14.1.3 go1.21
Proxy version: 14.1.3Proxy: teleport.example.com
- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands using your current credentials.tctl
is supported on macOS and Linux machines. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 14.2.1
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
commands on the computer that hosts the Teleport Auth Service for full permissions. - An AWS EC2 or other instance you can assign an IAM role where you will run the Teleport Application Service. The instance must be running a Linux distribution.
- IAM permissions in the AWS account you want to connect.
aws
command line interface (CLI) tool in PATH. Installing or updating the latest version of the AWS
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.
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
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": "*"
}
]
}
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 appropriate
commands for your authentication provider:
-
Retrieve your local user's configuration resource:
tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml -
Edit
out.yaml
, addingaws-console-access
to the list of existing roles:roles: - access - auditor - editor + - aws-console-access
-
Apply your changes:
tctl create -f out.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
github
authentication connector:tctl get github/github --with-secrets > github.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to thegithub.yaml
file. Because this key contains a sensitive value, you should remove the github.yaml file immediately after updating the resource. -
Edit
github.yaml
, addingaws-console-access
to theteams_to_roles
section.The team you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the team must include your user account and should be the smallest team possible within your organization.
Here is an example:
teams_to_roles: - organization: octocats team: admins roles: - access + - aws-console-access
-
Apply your changes:
tctl create -f github.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
saml
configuration resource:tctl get --with-secrets saml/mysaml > saml.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to thesaml.yaml
file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource. -
Edit
saml.yaml
, addingaws-console-access
to theattributes_to_roles
section.The attribute you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.
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 -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
oidc
configuration resource:tctl get oidc/myoidc --with-secrets > oidc.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to theoidc.yaml
file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource. -
Edit
oidc.yaml
, addingaws-console-access
to theclaims_to_roles
section.The claim you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.
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 -
Sign out of the Teleport cluster and sign in again to assume the new role.
Step 5/9. Register AWS console application in Teleport
Get a join token
Establish trust between your Teleport cluster and your new Application Service instance by creating a join token:
tctl tokens add --type=app --ttl=1h --format=textabcd123-insecure-do-not-use-this
On the host where you will install the Teleport Application Service, create a
file called /tmp/token
that consists only of your token:
echo join-token | sudo tee /tmp/token
Install the Teleport Application Service
Run the following commands on the host where you will install the Teleport Application Service:
Select an edition, then follow the instructions for that edition to install Teleport.
Teleport Edition
- Teleport Community Edition
- Teleport Team
- Teleport Enterprise
- Teleport Enterprise Cloud
curl https://goteleport.com/static/install.sh | bash -s 14.2.1
Add the Teleport repository to your repository list:
Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.ascSource variables about OS version
source /etc/os-releaseAdd the Teleport APT repository for cloud.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/nullsudo apt-get updatesudo apt-get install teleport-ent-updater
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")sudo yum install -y yum-utilssudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"sudo yum install teleport-ent-updaterTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"Install teleport
sudo dnf install teleport-ent-updaterTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
Source variables about OS version
source /etc/os-releaseAdd the Teleport Zypper repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")Use Zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")Install teleport
sudo zypper install teleport-ent-updater
OS repository channels
The following channels are available for APT, YUM, and Zypper repos. They may be used in place of
stable/v14
anywhere in the Teleport documentation.
Channel name | Description |
---|---|
stable/<major> | Receives releases for the specified major release line, i.e. v14 |
stable/cloud | Rolling channel that receives releases compatible with current Cloud version |
stable/rolling | Rolling channel that receives all published Teleport releases |
Before installing a teleport
binary with a version besides
v14, read our compatibility rules to ensure that the
binary is compatible with Teleport Cloud.
When running multiple teleport
binaries within a cluster, the following rules
apply:
- Patch and minor versions are always compatible, for example, any 8.0.1 component will work with any 8.0.3 component and any 8.1.0 component will work with any 8.3.0 component.
- Servers support clients that are 1 major version behind, but do not support
clients that are on a newer major version. For example, an 8.x.x Proxy Service
is compatible with 7.x.x resource services and 7.x.x
tsh
, but we don't guarantee that a 9.x.x resource service will work with an 8.x.x Proxy Service. This also means you must not attempt to upgrade from 6.x.x straight to 8.x.x. You must upgrade to 7.x.x first. - Proxy Services and resource services do not support Auth Services that are on
an older major version, and will fail to connect to older Auth Services by
default. This behavior can be overridden by passing
--skip-version-check
when starting Proxy Services and resource services.
Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.ascSource variables about OS version
source /etc/os-releaseAdd the Teleport APT repository for v14. You'll need to update this
file for each major release of Teleport.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v14" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/nullsudo apt-get updatesudo apt-get install teleport-ent
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo apt-get install teleport-ent-fips
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v14. You'll need to update this
file for each major release of Teleport.
First, get the major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")sudo yum install -y yum-utilssudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport.repo")"sudo yum install teleport-entTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo yum install teleport-ent-fips
Source variables about OS version
source /etc/os-releaseAdd the Teleport Zypper repository for v14. You'll need to update this
file for each major release of Teleport.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")Use zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")sudo yum install teleport-entTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo yum install teleport-ent-fips
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v14. You'll need to update this
file for each major release of Teleport.
First, get the major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport.repo")"Install teleport
sudo dnf install teleport-entTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo dnf install teleport-ent-fips
Source variables about OS version
source /etc/os-releaseAdd the Teleport Zypper repository.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")Use Zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport-zypper.repo")Install teleport
sudo zypper install teleport-ent
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo zypper install teleport-ent-fips
In the example commands below, update $SYSTEM_ARCH
with the appropriate
value (amd64
, arm64
, or arm
). All example commands using this variable
will update after one is filled out.
curl https://get.gravitational.com/teleport-ent-v14.2.1-linux-$SYSTEM_ARCH-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v14.2.1-linux-$SYSTEM_ARCH-bin.tar.gzshasum -a 256 teleport-ent-v14.2.1-linux-$SYSTEM_ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v14.2.1-linux-$SYSTEM_ARCH-bin.tar.gzcd teleport-entsudo ./install
For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:
curl https://get.gravitational.com/teleport-ent-v14.2.1-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v14.2.1-linux-$SYSTEM_ARCH-fips-bin.tar.gzshasum -a 256 teleport-ent-v14.2.1-linux-$SYSTEM_ARCH-fips-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v14.2.1-linux-$SYSTEM_ARCH-fips-bin.tar.gzcd teleport-entsudo ./install
OS repository channels
The following channels are available for APT, YUM, and Zypper repos. They may be used in place of
stable/v14
anywhere in the Teleport documentation.
Channel name | Description |
---|---|
stable/<major> | Receives releases for the specified major release line, i.e. v14 |
stable/cloud | Rolling channel that receives releases compatible with current Cloud version |
stable/rolling | Rolling channel that receives all published Teleport releases |
Add the Teleport repository to your repository list:
Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.ascSource variables about OS version
source /etc/os-releaseAdd the Teleport APT repository for cloud.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/nullsudo apt-get updatesudo apt-get install teleport-ent-updater
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")sudo yum install -y yum-utilssudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"sudo yum install teleport-ent-updaterTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"Install teleport
sudo dnf install teleport-ent-updaterTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
Source variables about OS version
source /etc/os-releaseAdd the Teleport Zypper repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")Use Zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")Install teleport
sudo zypper install teleport-ent-updater
OS repository channels
The following channels are available for APT, YUM, and Zypper repos. They may be used in place of
stable/v14
anywhere in the Teleport documentation.
Channel name | Description |
---|---|
stable/<major> | Receives releases for the specified major release line, i.e. v14 |
stable/cloud | Rolling channel that receives releases compatible with current Cloud version |
stable/rolling | Rolling channel that receives all published Teleport releases |
Before installing a teleport
binary with a version besides v14,
read our compatibility rules to ensure that the binary is compatible with
Teleport Enterprise Cloud.
When running multiple teleport
binaries within a cluster, the following rules
apply:
- Patch and minor versions are always compatible, for example, any 8.0.1 component will work with any 8.0.3 component and any 8.1.0 component will work with any 8.3.0 component.
- Servers support clients that are 1 major version behind, but do not support
clients that are on a newer major version. For example, an 8.x.x Proxy Service
is compatible with 7.x.x resource services and 7.x.x
tsh
, but we don't guarantee that a 9.x.x resource service will work with an 8.x.x Proxy Service. This also means you must not attempt to upgrade from 6.x.x straight to 8.x.x. You must upgrade to 7.x.x first. - Proxy Services and resource services do not support Auth Services that are on
an older major version, and will fail to connect to older Auth Services by
default. This behavior can be overridden by passing
--skip-version-check
when starting Proxy Services and resource services.
Configure the Teleport Application Service
On the host where you will run the Teleport Application Service, create a file
at /etc/teleport.yaml
with the following content:
version: v3
teleport:
join_params:
token_name: "/tmp/token"
method: token
proxy_server: "teleport.example.com:443"
auth_service:
enabled: off
proxy_service:
enabled: off
ssh_service:
enabled: off
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"
Edit /etc/teleport.yaml
to replace teleport.example.com:443
with the host
and port of your Teleport Proxy Service or Teleport Cloud tenant, e.g.,
mytenant.teleport.sh:443
.
The app_service
field configures the Teleport Application Service. Each item
within app_service.apps
is an application configuration.
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 teleportsudo 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.servicesudo systemctl enable teleportsudo systemctl start teleport
You can check the status of the Application Service with systemctl status teleport
and view its logs with journalctl -fu teleport
.
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.
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-testLogged 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 23456Started 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-exampleexport AWS_SECRET_ACCESS_KEY=zyxw9876-this-is-an-exampleexport AWS_CA_BUNDLE=<ca-bundle-path>export HTTPS_PROXY=http://127.0.0.1:23456terraform 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
Troubleshooting
remote error: tls: bad certificate
error during SSM sessions
You may encounter the remote error: tls: bad certificate
error when starting
System Session Manager (SSM) sessions using the tsh aws ssm start-session
or
tsh aws ecs execute-command
commands.
The issue is that tsh
cannot properly proxy WebSocket connections sent by
SSM.
Please upgrade to the latest version of tsh
where workarounds have been
implemented for tsh aws ssm start-session
and tsh aws ecs execute-command
.
For more information on the tsh
workarounds, see the pull requests that
introduced them:
- https://github.com/gravitational/teleport/pull/30510
- https://github.com/gravitational/teleport/pull/33705
If you are using tsh proxy aws
or if your tsh
version does not contain the
above fixes, add the following domain to the NO_PROXY
environment variable
before running tsh
commands to ensure the WebSocket connections bypass tsh
:
export NO_PROXY=ssmmessages.us-west-1.amazonaws.com
Replace us-west-1
with the AWS region you are accessing.
Next steps
- Take a closer look at role-based access controls.
- Explore other application access guides.