Fork me on GitHub

Teleport

Joining Nodes via AWS IAM Role

Improve

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 in Teleport 8.3+. It is available to any Teleport Node or Proxy 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 7.3+. It is available to any Teleport Node or Proxy Service instance running on an EC2 instance. Only one Teleport Node or Proxy 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 and tsh client tool version >= 10.3.1.

    tctl version

    Teleport v10.3.1 go1.18

    tsh version

    Teleport v10.3.1 go1.18

    See Installation for details.

  • A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.

  • The tctl admin tool and tsh client tool version >= 10.3.1, which you can download by visiting the customer portal.

    tctl version

    Teleport v10.3.1 go1.18

    tsh version

    Teleport v10.3.1 go1.18

  • A Teleport Cloud account. If you do not have one, visit the sign up page to begin your free trial.

  • The tctl admin tool and tsh client tool version >= 10.2.2. To download these tools, visit the Downloads page.

    tctl version

    Teleport v10.2.2 go1.18

    tsh version

    Teleport v10.2.2 go1.18

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

Cluster teleport.example.com

Version 10.3.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 status

Cluster myinstance.teleport.sh

Version 10.2.2

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.

You can also provide the IAM credentials to Teleport through a shared configuration file or environment variables. For details, see the following guide:

Specifying Credentials

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 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 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
teleport:
  join_params:
    token_name: iam-token
    method: iam
  auth_servers:
  - https://teleport.example.com:443
ssh_service:
  enabled: yes
auth_service:
  enabled: no
proxy_service:
  enabled: no

Step 4/4. Launch your Teleport Node

Start Teleport on the Node and confirm that it is able to connect to and join your cluster. You're all set!