CA Pinning
Relevant source files
The following files were used as context for generating this wiki page:
CA Pinning is a security mechanism within the Ansible Teleport role used to verify the identity of the Teleport Auth Server during the initial handshake. By providing a SHA256 hash of the cluster's Certificate Authority (CA) certificate, the Teleport node ensures it is connecting to a trusted infrastructure, preventing man-in-the-middle attacks when joining a cluster via untrusted networks.
Sources: README.md:89-91, tasks/security/ca_pin.yml:25-29
CA Pin Acquisition and Validation
The role supports three primary methods for handling the CA PIN: manual provision, automatic retrieval from the proxy server, or migration from an existing configuration file.
Automatic Retrieval Logic
If teleport_fetch_ca_pin is enabled and no PIN is provided, the role attempts to fetch the PIN directly from the Teleport Proxy's Web API. The response is parsed using a regular expression to extract the specific sha256 format.
The diagram shows the conditional logic used to decide whether to fetch a PIN or use an existing one.
Sources: tasks/security/ca_pin.yml:1-30
Format Verification
To ensure system stability, the role enforces a strict format for the CA PIN. The PIN must match the pattern ^sha256:[a-f0-9]{64}$. Failure to meet this requirement results in an assertion error during the playbook execution.
Sources: tasks/security/ca_pin.yml:25-30
Migration and Persistence
During upgrades or re-configurations, the role prioritizes maintaining the existing security context.
Legacy Configuration Parsing
If a Teleport configuration already exists at teleport_config_path, the role slurps the file and parses the YAML content. It specifically looks for the teleport.ca_pin value to ensure continuity without requiring the user to re-supply the secret.
Sources: tasks/security/parse_legacy_config.yml:1-20, tasks/security/auth.yml:11-17
Change Detection
The system monitors changes in the CA PIN by comparing the legacy value against the currently defined value. If a change is detected, it flags security_credentials_changed, which can trigger the flushing of ephemeral data in /var/lib/teleport/proc/.
This diagram illustrates the flow from reading the old configuration to determining if security credentials have been updated.
Sources: tasks/config/main.yml:68-80, tasks/security/auth.yml:1-17
Configuration Parameters
The following variables control the behavior of CA Pinning within the role:
| Variable | Default | Description |
|---|---|---|
teleport_ca_pin | "" | The SHA256 hash of the CA. Manually provided or auto-filled. |
teleport_fetch_ca_pin | true | Enables automatic retrieval from the proxy API. |
teleport_validate_certs | true | Determines if the HTTPS certificate of the proxy is validated during PIN retrieval. |
teleport_proxy_server | "" | The address used to construct the API URL for PIN export. |
Sources: defaults/main.yml:45-55, tasks/security/ca_pin.yml:1-7
Implementation in Deployment
The CA PIN is integrated into the final /etc/teleport.yaml configuration file. This allows nodes to perform authenticated joins to the cluster.
# Example configuration snippet derived from README
teleport:
auth_token: "super secret auth token"
ca_pin: "sha256:7db...ca9"
auth_server: auth.example.com:3025
Sources: README.md:188-193, tasks/main.yml:42-45
Summary
CA Pinning in the ansible-teleport role provides a critical layer of trust for node registration. It automates the lifecycle of the CA PIN—from initial discovery via the Proxy API to migration from legacy configuration files—while ensuring the integrity of the value through strict regex validation and change detection.
Sources: tasks/security/ca_pin.yml:1-30, tasks/config/main.yml:68-80