Authentication Tokens Management

Relevant source files

The following files were used as context for generating this wiki page:

• tasks/security/auth.yml
• defaults/main.yml
• tasks/security/ca_pin.yml
• tasks/security/parse_legacy_config.yml
• tasks/config/main.yml
• README.md

Introduction

Authentication Tokens Management in this Ansible role facilitates the secure joining of nodes to a Teleport cluster. It encompasses the handling of join tokens (static, dynamic, or cloud-native), CA pins for verifying the identity of the Auth Server, and the migration of these credentials from existing legacy configurations to ensure continuity during upgrades. Sources: README.md:38-44, tasks/security/auth.yml:1-15

The system is designed to be idempotent and resilient, allowing users to update configuration elements such as labels and commands without needing to re-provide sensitive tokens once they are established in the local configuration. Sources: README.md:144-150

Token Types and Retrieval

The role supports multiple authentication and join methods depending on the infrastructure environment and security requirements.

Join Tokens

Teleport nodes require a token to authenticate with the Auth Server during the initial handshake. This role supports:

• Static/Dynamic Tokens: Standard tokens generated via tctl. Sources: README.md:41-42
• EC2 Join Tokens: Specialized tokens for AWS environments that leverage the EC2 Instance Identity Document. Sources: defaults/main.yml:25, README.md:162-167

CA Pin Retrieval

To prevent Man-in-the-Middle (MitM) attacks, the role can automatically retrieve the cluster's CA pin from the proxy's public endpoint. This pin is used to validate the certificate presented by the Auth Server. Sources: tasks/security/ca_pin.yml:2-8, README.md:126-128

The following sequence diagram illustrates the automated CA pin retrieval process:

Configuration Migration Logic

When an existing Teleport configuration is detected, the role attempts to parse the legacy file to preserve existing security credentials. This prevents service disruption during configuration updates or role upgrades.

Migration Flow

1. Detection: Checks if teleport.yaml exists.
2. Parsing: Slurps and decodes the YAML content (version v3).
3. Extraction: Pulls auth_token and ca_pin from the teleport block.
4. Application: If new variables are not provided, the legacy values are assigned to teleport_auth_token and teleport_ca_pin.

Security Credentials Change Detection

The role tracks if security credentials have changed to determine if ephemeral data needs to be flushed. This is critical because Teleport nodes cache certain state information linked to the identity provided by the token.

If legacy_auth_token differs from teleport_auth_token or the CA pin changes, the variable security_credentials_changed is set to true. This triggers the removal of ephemeral data located at /var/lib/teleport/proc/. Sources: tasks/config/main.yml:68-100

Configuration Reference

Variable	Type	Default	Description
teleport_auth_token	String	""	The secret token used to join the cluster. Sources: defaults/main.yml:45
teleport_ca_pin	String	""	The SHA256 pin of the Auth Server CA. Sources: defaults/main.yml:43
teleport_ec2_join_token	String	ec2-teleport-join-token	Token for AWS EC2 joining method. Sources: defaults/main.yml:25
teleport_fetch_ca_pin	Boolean	true	Whether to attempt auto-retrieval of CA pin. Sources: defaults/main.yml:42
teleport_join_token_ttl	String	1h	Time-to-live for generated join tokens. Sources: defaults/main.yml:48

Summary

Authentication Tokens Management ensures that nodes can securely join the Teleport cluster with minimal manual intervention. By supporting automated CA pin retrieval and legacy configuration migration, the role maintains high security standards while providing a seamless upgrade path for node configurations. Sources: tasks/security/auth.yml, tasks/security/ca_pin.yml, tasks/config/main.yml