
This guide will explain how to use the IAM join method to configure Teleport Nodes and Proxy Service instances to join your Teleport cluster without sharing any secrets when they are running in AWS.
The IAM join method is available to any Teleport service running anywhere with access to IAM credentials, such as an EC2 instance with an attached IAM role. No specific permissions or IAM policy is required: an IAM role with no attached policies is sufficient. No IAM credentials are required on the Teleport Auth Service.
There are two additional methods you can use to join your Nodes to a Teleport cluster.
The EC2 join method is available in self-hosted versions of Teleport. It is available to any Teleport service instance running on an EC2 instance. Only one Teleport service instance per EC2 instance may use the EC2 join method.
IAM credentials with ec2:DescribeInstances
permissions are required on
your Teleport Auth Service. No IAM credentials are required on the Nodes or
Proxies.
You can also configure Nodes running in AWS to join a cluster via secret tokens, which is useful when you don't want to rely on AWS-specific APIs. Read more in the following guide: Adding Nodes to the cluster
You can also configure Nodes running in AWS to join a cluster via secret tokens, which is useful when you don't want to rely on AWS-specific APIs. Read more in the following guide: Adding Nodes to the cluster
The IAM join method will not work if TLS is terminated at a load balancer in front of your Teleport Proxy Service unless the Node using this method is connecting directly to the Auth Service.
Prerequisites
-
A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.
-
The
tctl
admin tool andtsh
client tool version >= 12.1.1.tctl versionTeleport v12.1.1 go1.19
tsh versionTeleport v12.1.1 go1.19
See Installation for details.
-
A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 12.1.1, which you can download by visiting the customer portal.tctl versionTeleport Enterprise v12.1.1 go1.19
tsh versionTeleport v12.1.1 go1.19
Please use the latest version of Teleport Enterprise documentation.
- An AWS EC2 instance to act as a Teleport Node, with the Teleport binary installed.
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=teleport.example.com [email protected]tctl statusCluster teleport.example.com
Version 12.1.1
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
You can run subsequent tctl
commands in this guide on your local machine.
For full privileges, you can also run tctl
commands on your Auth Service host.
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=myinstance.teleport.sh [email protected]tctl statusCluster myinstance.teleport.sh
Version 12.1.1
CA pin sha256:sha-hash-here
You must run subsequent tctl
commands in this guide on your local machine.
Step 1/4. Set up AWS IAM credentials
Every Node or Proxy using the IAM method to join your Teleport cluster needs AWS
IAM credentials in order to call the sts:GetCallerIdentity
API. No specific
IAM policy or permissions are needed. Any IAM user or role can call this API.
If running your Node on an EC2 instance, it is sufficient to attach any IAM
role to the instance. To attach an IAM role from the EC2 dashboard, select
Actions > Security > Modify IAM role
.
It is not necessary for the role to have any attached IAM policies at all.
If your instance does not otherwise need AWS credentials, it is preferred to
create and attach an emtpy role with no attached policies.
You can also provide the IAM credentials to Teleport through a shared configuration file or environment variables. For details, see the following guide:
Step 2/4. Create the AWS Node joining token
Under the hood, Nodes will prove that they are running in your AWS account by
sending a pre-signed sts:GetCallerIdentity
request to the Teleport Auth Server. The
Node's identity must match an allow rule configured in your AWS Node joining
token.
Create the following token.yaml
with an allow
rule specifying your AWS
account and the ARN that your Node's identity must match.
# token.yaml
kind: token
version: v2
metadata:
# the token name is not a secret because instances must prove that they are
# running in your AWS account to use this token
name: iam-token
# set a long expiry time, the default for tokens is only 30 minutes
expires: "3000-01-01T00:00:00Z"
spec:
# use the minimal set of roles required
roles: [Node]
# set the join method allowed for this token
join_method: iam
allow:
# specify the AWS account which Nodes may join from
- aws_account: "111111111111"
# multiple allow rules are supported
- aws_account: "222222222222"
# aws_arn is optional and allows you to restrict the IAM role of joining Nodes
- aws_account: "333333333333"
aws_arn: "arn:aws:sts::333333333333:assumed-role/teleport-node-role/i-*"
The token name iam-token
is just an example and can be any value you want to
use, as long as you use the same value for join_params.token_name
in Step 3.
The optional aws_arn
field in the allow rules supports wildcard characters:
*
to match any combination of characters?
to match any single character
See the IAM docs for more details on the ARN format.
You can check what your AWS identity looks like by running
aws sts get-caller-identity
on the
AWS CLI.
Run tctl create -f token.yaml
to create the token.
Step 3/4. Configure your Nodes
The IAM join method can be used for Teleport services running the SSH, Proxy, Kubernetes, Application, or Database Service.
Configure your Teleport Node with a custom teleport.yaml
file. Use the
join_params
section with token_name
matching your token created in Step 2
and method: iam
as shown in the following example config:
# /etc/teleport.yaml
version: v3
teleport:
join_params:
token_name: iam-token
method: iam
proxy_server: https://teleport.example.com:443
ssh_service:
enabled: yes
auth_service:
enabled: no
proxy_service:
enabled: no
Step 4/4. Launch your Teleport Node
Grant your Teleport instance access to credentials that it can use to authenticate to AWS. If you are running your Teleport instance 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.
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 your Teleport instance, 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 your Teleport instance 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 your Teleport instance to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed your Teleport instance.
On the host where you will run your Teleport instance, start Teleport:
sudo systemctl start teleport
On the host where you will run your Teleport instance, 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
Once you have started Teleport, confirm that your Node is able to connect to and join your cluster.