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

Joining Services via AWS IAM Role

This guide explains how to use the IAM join method to configure Teleport processes to join your Teleport cluster without sharing any secrets when they are running in AWS.

There are two other AWS join methods available depending on your use case:

  1. The EC2 join method, which is only available for self-hosted Teleport deployments (see documentation). A Teleport process running on an EC2 instance requests a signed EC2 instance identity document and presents it to the Teleport Auth Service, which queries the EC2 API to verify that the instance is genuine. This method requires a self-hosted Teleport cluster and IAM credentials for the Teleport Auth Service.
  2. Tokens not signed by AWS: You can configure Teleport processes running on AWS to join a cluster via Teleport join tokens or, for Teleport processes running on Kubernetes, signed ServiceAccount tokens. These approaches allow you to join a Teleport process to a cluster when you don't want to rely on AWS-specific APIs, e.g., when adopting a cloud-agnostic approach.

How it works​

The IAM join method is available to any Teleport process 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.

Teleport processes prove that they are running in your AWS account by sending a pre-signed sts:GetCallerIdentity request to the Teleport Auth Service. The service's identity must match an allow rule configured in your AWS service joining token.

Support for joining a cluster with the Proxy Service behind a layer 7 load balancer or reverse proxy is available in Teleport 13.0+.

Prerequisites​

  • A running Teleport cluster version 17.0.0-dev or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl admin tool and tsh client tool.

    Visit Installation for instructions on downloading tctl and tsh.

  • An AWS EC2 instance to host a Teleport service, with the Teleport binary installed.

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:

$ tsh login --proxy=teleport.example.com --user=email@example.com
$ tctl status
# Cluster  teleport.example.com
# Version  17.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.

Step 1/5. Set up AWS IAM credentials​

Every Teleport process 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 Teleport 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 empty role with no attached policies.

Step 2/5. Create the AWS joining token​

Create the following token.yaml with an allow rule specifying your AWS account and the ARN that the Teleport process'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
spec:
  # use the minimal set of roles required (e.g. Node, App, Kube, DB, WindowsDesktop)
  roles: [Node]
  
  # set the join method allowed for this token
  join_method: iam
  
  allow:
    # specify the AWS account which Teleport processes 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
    # Teleport processes
    - 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

Run the following command to create the token:

$ tctl create -f token.yaml

Step 3/5 Install Teleport​

Install Teleport on your AWS EC2 instance.

Install Teleport on your Linux server:

  1. Assign edition to one of the following, depending on your Teleport edition:

    EditionValue
    Teleport Enterprise Cloudcloud
    Teleport Enterprise (Self-Hosted)enterprise
    Teleport Community Editionoss

  2. Get the version of Teleport to install. If you have automatic agent updates enabled in your cluster, query the latest Teleport version that is compatible with the updater:

    $ TELEPORT_DOMAIN=example.teleport.com
    $ TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

    Otherwise, get the version of your Teleport cluster:

    $ TELEPORT_DOMAIN=example.teleport.com
    $ TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/ping | jq -r '.server_version')"

  3. Install Teleport on your Linux server:

    $ curl https://cdn.teleport.dev/install-v15.4.11.sh | bash -s ${TELEPORT_VERSION} edition

    The installation script detects the package manager on your Linux server and uses it to install Teleport binaries. To customize your installation, learn about the Teleport package repositories in the installation guide.

Step 4/5. Configure your services​

The IAM join method can be used for Teleport processes running the SSH, Proxy, Kubernetes, Application, or Database Service.

Configure your Teleport service 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: teleport.example.com:443
ssh_service:
  enabled: yes
auth_service:
  enabled: no
proxy_service:
  enabled: no

In the teleport.proxy_server field, replace the value with the host and web port of your Teleport Proxy Service or Teleport Enterprise Cloud tenant, e.g., mytenant.teleport.sh:443.

Step 5/5. Launch your Teleport process​

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 may use the EC2 Instance Metadata Service method
  • If you are running your Teleport instance in Kubernetes, you can use IAM Roles for Service Accounts (IRSA)
  • 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.

Have multiple sources of AWS credentials?

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, enable and start Teleport:

$ sudo systemctl enable teleport
$ sudo systemctl start teleport

You can check the status of your Teleport instance with systemctl status teleport and view its logs with journalctl -fu teleport.

Once you have started Teleport, confirm that your service is able to connect to and join your cluster.