teleport/docs/pages/reference/join-methods.mdx

---
title: Join Methods and Tokens
h1: Join Methods and Token Reference
description: Describes the different ways to configure a Teleport to join a cluster.
keywords: [join, joining, token]
tocDepth: 3
---

This guide explains the core concepts behind the Teleport joining process,
references all support join methods and classifies them based on their
security properties. This guide does not explain step-by-step how to
join an instance with each join method, but links to the relevant How-To
guides when possible.

<Admonition type="note" title="Prerequisite">
You must be familiar with the [Teleport Core concepts](../core-concepts.mdx)
before reading this page.
</Admonition>

## Definitions

### Joining

Joining a Teleport cluster is the act of establishing trust between a new
Teleport instance and all the existing instances already part of the Teleport
cluster. At the end of the joining process, the Auth Service signs certificates
for the joining instance. Those certificates represent the trust that was
established. With them, the newly-joined instance can interact with the
other Teleport instances.

To request its certificates, an instance must prove its identity to the Auth Service.
Teleport offers multiple ways for a joining instance to prove its authenticity, they
are called the join methods.

The joining process only happens when a Teleport service doesn't have valid
certificates. Once the token is exchanged for certificates, those
certificates are used on all subsequent attempts to connect. In most cases,
this happens during the first startup.

### Join methods

A join method is a way for the Auth Service to validate that an instance requesting to
join the Teleport cluster is legitimate. Some join methods are universal while
others rely on the joining instance context. For example cloud-provider
join-methods (such as `iam`, `gcp` or `azure`) or CI-provider (such as `github`,
`gitlab`, `circleci`) are more flexible and provide
better security guarantees but require the joining instance to run in a specific
cloud-provider.

Different join methods may provide different security guarantees. e.g. some
join methods allow the joining instance to request renewable certificates while other
will require the instance to join again to renew its certificate.

The join method and its parameters are specified in the token resource.

### Token

A Token is a Teleport resource that specifies which join method can be used in
which context. For example, a token can allow SSH services to join with the
`iam` join method if they are in the AWS account `333333333333` and can assume
the role `teleport-instance-role`:

```yaml
kind: token
version: v2
metadata:
  name: my-iam-token
spec:
  roles: [Node]
  join_method: iam
  allow:
  - aws_account: "333333333333"
    aws_arn: "arn:aws:sts::333333333333:assumed-role/teleport-instance-role/i-*"
```

<Admonition type="important">
The token name may, or may not be sensitive depending on the join method.
Secret-based join methods rely on the token name to be secret. In such
cases the token name must be protected as knowing the token name in enough
for an instance to join the cluster.
</Admonition>

## Classification of join methods

### Secret vs delegated

#### Secret-based join methods

Secret-based join methods are universal: Teleport service can use a secret-based
join method regardless of the platform/cloud provider it runs on. The joining instance
sends the secret and the Auth Service validates that it matches the one it
knows. Those joining methods are inherently prone to secret exfiltration and
the delegated join methods should be preferred when available. If you have
to use a secret-based join method, it is recommended to use short-lived tokens
(valid only 1 hour for example) to reduce the risk of the token leaking.

Secret-based join methods are:
- [ephemeral `token`](#ephemeral-tokens)
- [static `token`](#static-tokens)

<Admonition type="warning">
Teleport supports static tokens for backward compatibility, their use should be avoided.
</Admonition>

#### Delegated join methods

Delegated join methods rely on the context of the joining instance and a third party to
establish trust. The third party can be a cloud provider, a CI platform or the
container runtime. Those methods cannot be used for every instance (e.g. joining an SSH
agent from a Raspberry Pi is not possible) but should be preferred when possible.

Delegated join methods might also offer more granularity. For example, cloud-provider
based join methods can allow instances to join based on their Availability Zone,
service account, or cloud account ID.

Delegated join methods are:
- [`iam`](#aws-iam-role-iam)
- [`azure`](#azure-managed-identity-azure)
- [`gcp`](#gcp-service-account-gcp)
- [`ec2`](#aws-ec2-identity-document-ec2)
- [`github`](#github-actions-github)
- [`circleci`](#circleci-circleci)
- [`gitlab`](#gitlab-gitlab)
- [`kubernetes`](#kubernetes-kubernetes)
- [`tpm`](#trusted-platform-module-tpm)
- [`terraform_cloud`](#terraform-cloud-terraform_cloud)

### Renewable vs non-renewable

Depending on the join method used, the Auth Service might issue renewable
or non-renewable certificates.

When the certificate is about to expire, instances with renewable certificates can
request a new one without having to use a token again. Typically, secret-based join methods
provide renewable certificates because the secret token is sensitive and typically
short-lived. With a single join, the instance can stay part of the cluster indefinitely.

Renewable join-methods are:
- [ephemeral `token`](#ephemeral-tokens)
- [static `token`](#static-tokens)
- [`ec2`](#aws-ec2-identity-document-ec2)

Nodes with non-renewable certificates must join again in order to get a new
certificate before expiry. The instance will have to prove again that it is legitimate.
The non-renewable join methods guarantee that an attacker stealing the instance
certificates will not be able to maintain access to the Teleport cluster.
Those join methods can be considered more secure and more appropriate for
temporary workloads such as CI/CD pipelines or containerized environments.

Non-renewable join methods are:
- [`iam`](#aws-iam-role-iam)
- [`azure`](#azure-managed-identity-azure)
- [`gcp`](#gcp-service-account-gcp)
- [`github`](#github-actions-github)
- [`circleci`](#circleci-circleci)
- [`gitlab`](#gitlab-gitlab)
- [`kubernetes`](#kubernetes-kubernetes)
- [`tpm`](#trusted-platform-module-tpm)

## Token resource reference

The token resource has the following common fields for all join methods:

```yaml
# token.yaml
kind: token
version: v2
metadata:
  name: my-token-name
spec:
  # System roles describe what services the joining Teleport instance can run.
  # Those roles are written on the instance certificate. If you want to change
  # them (e.g. add Application access to an SSH Node), you need to:
  # - edit the token to update the roles (e.g. add "App")
  # - un-register the Teleport instance
  # - modify its configuration to enable the new service (here "app_service.enabled")
  # - have the instance join again
  #
  # You should use the minimal set of system roles required.
  # Common roles are:
  # - "Node" for SSH Service
  # - "Proxy" for Proxy Service
  # - "Kube" for Kubernetes Service
  # - "App" for Application Service
  # - "Db" for Database Service
  # - "WindowsDesktop" for Windows Desktop Service
  # - "Discovery" for Discovery Service
  # - "Bot" for MachineID (when set, "spec.bot_name" must be set in the token)
  roles:
    - Node
    - App
  join_method: gcp
  # Only set bot name when the token is used for MachineID.
  # When set, the token must have the "Bot" role as well.
  bot_name: my-bot
  # SuggestedLabels is a set of labels that resources should set when using this
  # token to enroll themselves in the cluster.
  # Currently, only node-join scripts create a configuration according to the suggestion.
  suggested_labels:
    teams: ["sales-eng", "eng", "qa"]
    application: ["demo-product"]
  # SuggestedAgentMatcherLabels is a set of labels to be used by discovery agents to match on resources.
  # When an agent uses this token, the agent should monitor resources that match those labels.
  # For databases, this means adding the labels to `db_service.resources.labels`.
  # Currently, only node-join scripts create a configuration according to the suggestion.
  suggested_agent_matcher_labels:
    teams: ["sales-eng"]
```

## Join methods

### Static tokens

<Admonition type="danger">
This join method is inherently less secure because long-lived tokens can be stolen and reused.
Relying on it significantly reduces the security benefits of using Teleport. Its usage is strongly discouraged.
You should use [ephemeral tokens](#ephemeral-tokens) instead.
</Admonition>

Static tokens are tokens defined in the Auth Service configuration (`teleport.yaml`).
The token name must be kept secret as knowing it allows to join instances to
the Teleport cluster.

```yaml
auth_service:
    enabled: yes
    # Pre-defined tokens for adding new instances to a cluster. Each token specifies
    # the role a new node will be allowed to assume. The more secure way to
    # add instances is to use `tctl nodes add --ttl` command to generate auto-expiring
    # tokens.
    #
    # We recommend to use tools like `pwgen` to generate sufficiently random
    # tokens of 32+ byte length.
    tokens:
        - "proxy,node:xxxxx"
        - "auth:yyyy"
        - "discovery,app,db:zzzzz"
```

### Ephemeral tokens

Ephemeral tokens are secret tokens created dynamically via the CLI or Teleport API.
They are time-bound and are typically created just before joining an instance to
the Teleport cluster.

They can be created by the CLI (a strong random value is picked when not specified, default TTL is 30 minutes):
```code
$ tctl tokens add --type discovery,app --ttl 15m
```

Or as Teleport resources:

(!docs/pages/includes/provision-token/ephemeral-spec.mdx!)

When a MachineID bot uses an ephemeral join token, the token is deleted.

<Admonition type="note" title="See Also">
- How to [Join Services with a Secure Token](../enroll-resources/agents/join-services-to-your-cluster/join-token.mdx).
- [Deploying Machine ID on Linux](../enroll-resources/machine-id/deployment/linux.mdx)
</Admonition>

### AWS IAM role: `iam`

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.

This is the recommended method to join workload running on AWS.

(!docs/pages/includes/provision-token/iam-spec.mdx!)

<Admonition type="note" title="See Also">
- [Joining Services via AWS IAM Role](../enroll-resources/agents/join-services-to-your-cluster/aws-iam.mdx).
- [Deploying Machine ID on AWS](../enroll-resources/machine-id/deployment/aws.mdx)
</Admonition>

### AWS EC2 identity document: `ec2`

The EC2 join method is available to any Teleport process running on an EC2
instance. Only one Teleport process 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 Teleport processes
joining the cluster.

<Admonition type="warning">

The EC2 join method is not available in Teleport Enterprise Cloud and Teleport
Team. Teleport Enterprise Cloud and Team customers can use the [IAM join
method](#aws-iam-role-iam) or [ephemeral secret tokens](#ephemeral-tokens).

</Admonition>

(!docs/pages/includes/provision-token/ec2-spec.mdx!)

<Admonition type="note" title="See Also">
[Joining Services via AWS EC2 Identity Document](../enroll-resources/agents/join-services-to-your-cluster/aws-ec2.mdx).
</Admonition>

### Azure managed identity: `azure`

The Azure join method is available to any Teleport process running in an
Azure Virtual Machine. Support for joining a cluster with the Proxy Service
behind a layer 7 load balancer or reverse proxy is available in Teleport 13.0+.

(!docs/pages/includes/provision-token/azure-spec.mdx!)

<Admonition type="note" title="See Also">
- [Joining Services via Azure Managed Identity](../enroll-resources/agents/join-services-to-your-cluster/azure.mdx).
- [Deploying Machine ID on Azure](../enroll-resources/machine-id/deployment/azure.mdx)
</Admonition>

### GCP service account: `gcp`

The GCP join method is available to any Teleport process running on a GCP VM.
The VM must have a
[service account](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances)
assigned to it (the default service account is fine). No IAM roles are required
on the Teleport process joining the cluster.

(!docs/pages/includes/provision-token/gcp-spec.mdx!)

<Admonition type="note" title="See Also">
- How to [Join Services with GCP](../enroll-resources/agents/join-services-to-your-cluster/gcp.mdx).
- [Deploying Machine ID on GCP](../enroll-resources/machine-id/deployment/gcp.mdx)
</Admonition>

### GitHub Actions: `github`

Teleport supports secure joining on both GitHub-hosted and self-hosted GitHub
Actions runners as well as GitHub Enterprise Server. This join method is
typically used with [Machine ID](../enroll-resources/machine-id/introduction.mdx) to access
Teleport-protected resources in GitHub Actions pipelines.

(!docs/pages/includes/provision-token/github-spec.mdx!)

<Admonition type="note" title="See Also">
- [Deploying Machine ID on GitHub Actions](../enroll-resources/machine-id/deployment/github-actions.mdx)
</Admonition>

### CircleCI: `circleci`

This join method is typically used with [Machine ID](../enroll-resources/machine-id/introduction.mdx)
to access Teleport-protected resources in Circle CI pipelines.

(!docs/pages/includes/provision-token/circleci-spec.mdx!)

<Admonition type="note" title="See Also">
- [Deploying Machine ID on Circle CI](../enroll-resources/machine-id/deployment/circleci.mdx)
</Admonition>

### GitLab: `gitlab`

Teleport supports secure joining on both cloud-hosted and self-hosted GitLab
instances. **The minimum supported GitLab version is 15.7**.

This join method is typically used with [MachineID](../enroll-resources/machine-id/introduction.mdx)
to access Teleport-protected resources in Gitlab CI pipelines.

(!docs/pages/includes/provision-token/gitlab-spec.mdx!)

<Admonition type="note" title="See Also">
- [Deploying Machine ID on GitLab CI](../enroll-resources/machine-id/deployment/gitlab.mdx)
</Admonition>

### Kubernetes: `kubernetes`

The Kubernetes join methods exists in two variants:
- [in-cluster](#kubernetes-in-cluster)
- [JWKS](#kubernetes-jwks)

#### Kubernetes In-cluster

Kubernetes in-cluster joining is available for any Teleport process running
in the same Kubernetes cluster than the Auth Service. It uses the Kubernetes
ServiceAccount tokens to validate the pod identity. The method relies on the
[Kubernetes TokenReview API](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-review-v1/)
which is typically only reachable from within the Kubernetes cluster. Because of
this limitation, this join method is only available for self-hosted Teleport
clusters in Kubernetes.

This method should be preferred when available as tokens are revoked as soon as
the pod enters the `Terminated` state.

(!docs/pages/includes/provision-token/kubernetes-in-cluster-spec.mdx!)

<Admonition type="note" title="See Also">
- [Joining Services via Kubernetes ServiceAccount Token](../enroll-resources/agents/join-services-to-your-cluster/kubernetes.mdx)
</Admonition>

#### Kubernetes JWKS

Kubernetes JWKS joining is available for any Teleport process running in
Kubernetes. The Auth Service does not have to run in Kubernetes so this method
can be used with any Teleport cluster, including Teleport Cloud.
This join method works by exporting the public Kubernetes signing keys and using
them to validate Kubernetes SA token signatures. The signature validation can be
performed by an Auth Service without access to the Kubernetes.

The Kubernetes JWKS join method is available in Teleport 14+.

(!docs/pages/includes/provision-token/kubernetes-jwks-spec.mdx!)

<Admonition type="warning">
After rotating the Kubernetes CA, you must update the Kubernetes JWKS tokens
to contain the new Kubernetes signing keys (update the
`spec.kubernetes.static_jwks.jwks` field).
</Admonition>

<Admonition type="note" title="See Also">
- [Deploying Machine ID on Kubernetes](../enroll-resources/machine-id/deployment/kubernetes.mdx)
</Admonition>

### Trusted Platform Module: `tpm`

(!docs/pages/includes/tpm-joining-background.mdx!)

(!docs/pages/includes/provision-token/tpm-spec.mdx!)

<Admonition type="note" title="See Also">
- [Deploying Machine ID on Linux: TPM](../enroll-resources/machine-id/deployment/linux-tpm.mdx)
</Admonition>

### Terraform Cloud: `terraform_cloud`

This join method is used to authenticate using Terraform Cloud Workload
Identity. It is typically used by the Teleport Terraform provider on either
HCP Terraform or self-hosted Terraform Enterprise. It can not be used to join
Terraform runs on other platforms and dedicated join methods should be used
instead.

<Admonition type="warning" title="Enterprise">
Support for self-hosted Terraform Enterprise requires Teleport Enterprise.
</Admonition>

(!docs/pages/includes/provision-token/terraform-spec.mdx!)

<Admonition type="note" title="See Also">
- [Run the Teleport Terraform Provider on Terraform Cloud](../admin-guides/infrastructure-as-code/terraform-provider/terraform-cloud.mdx)
</Admonition>

### Spacelift: `spacelift`

This join method is used to authenticate using Spacelift. It is typically used
by the Teleport Terraform provider on Spacelift (including self-hosted
deployments).

(!docs/pages/includes/provision-token/spacelift-spec.mdx!)

<Admonition type="note" title="See Also">
    - [Run the Teleport Terraform Provider on Spacelift](../admin-guides/infrastructure-as-code/terraform-provider/spacelift.mdx)
</Admonition>

### Bitbucket Pipelines: `bitbucket`

This join method is used to authenticate using Bitbucket's support for OpenID
Connect, and is typically used to allow either Machine ID's `tbot` or the
Teleport Terraform provider to authenticate to Teleport without use of shared
secrets.

(!docs/pages/includes/provision-token/bitbucket-spec.mdx!)

<Admonition type="note" title="See Also">
- [Deploying Machine ID on Bitbucket Pipelines](../enroll-resources/machine-id/deployment/bitbucket.mdx)
</Admonition>

### Oracle Cloud: `oracle`

The Oracle join method is available to any Teleport process running on an Oracle
Cloud Compute instance.

(!docs/pages/includes/provision-token/oracle-spec.mdx!)

<Admonition type="note" title="See Also">
- How to [Join Services with Oracle Cloud](../enroll-resources/agents/join-services-to-your-cluster/oracle.mdx).
</Admonition>