--- title: 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. You must be familiar with the [Teleport Core concepts](../core-concepts.mdx) before reading this page. ## 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-*" ``` 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. ## 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) Teleport supports static tokens for backward compatibility, their use should be avoided. #### 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) ### 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 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. 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): ```shell $ 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. - How to [Join Services with a Secure Token](../agents/join-services-to-your-cluster/join-token.mdx). - [Deploying Machine ID on Linux](../machine-id/deployment/linux.mdx) ### 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. Support for joining a cluster with the Proxy Service behind a layer 7 load balancer or reverse proxy is available in Teleport 13.0+. This is the recommended method to join workload running on AWS. (!docs/pages/includes/provision-token/iam-spec.mdx!) - [Joining Services via AWS IAM Role](../agents/join-services-to-your-cluster/aws-iam.mdx). - [Deploying Machine ID on AWS](../machine-id/deployment/aws.mdx) ### 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. 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). (!docs/pages/includes/provision-token/ec2-spec.mdx!) [Joining Services via AWS EC2 Identity Document](../agents/join-services-to-your-cluster/aws-ec2.mdx). ### Azure managed identity: `azure` The Azure join method is available in Teleport 12.1+. It 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!) - [Joining Services via Azure Managed Identity](../agents/join-services-to-your-cluster/azure.mdx). - [Deploying Machine ID on Azure](../machine-id/deployment/azure.mdx) ### 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!) - How to [Join Services with GCP](../agents/join-services-to-your-cluster/gcp.mdx). - [Deploying Machine ID on GCP](../machine-id/deployment/gcp.mdx) ### 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](../machine-id/introduction.mdx) to access Teleport-protected resources in GitHub Actions pipelines. (!docs/pages/includes/provision-token/github-spec.mdx!) - [Deploying Machine ID on GitHub Actions](../machine-id/deployment/github-actions.mdx) ### CircleCI: `circleci` This join method is typically used with [Machine ID](../machine-id/introduction.mdx) to access Teleport-protected resources in Circle CI pipelines. (!docs/pages/includes/provision-token/circleci-spec.mdx!) - [Deploying Machine ID on Circle CI](../machine-id/deployment/circleci.mdx) ### 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](../machine-id/introduction.mdx) to access Teleport-protected resources in Gitlab CI pipelines. (!docs/pages/includes/provision-token/gitlab-spec.mdx!) - [Deploying Machine ID on GitLab CI](../machine-id/deployment/gitlab.mdx) ### 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. The Kubernetes in-cluster join method is available in self-hosted versions of Teleport 12+. (!docs/pages/includes/provision-token/kubernetes-in-cluster-spec.mdx!) - [Joining Services via Kubernetes ServiceAccount Token](../agents/join-services-to-your-cluster/kubernetes.mdx) #### 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!) After rotating the Kubernetes CA, you must update the Kubernetes JWKS tokens to contain the new Kubernetes singing keys (update the `spec.kubernetes.static_jwks.jwks` field). - [Deploying Machine ID on Kubernetes](../machine-id/deployment/kubernetes.mdx) ### Trusted Platform Module: `tpm` (!docs/pages/includes/tpm-joining-background.mdx!) (!docs/pages/includes/provision-token/tpm-spec.mdx!) - [Deploying Machine ID on Linux: TPM](../machine-id/deployment/linux-tpm.mdx)