Security Operations Overview

Relevant source files

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

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

Introduction

The Security Operations Overview describes the mechanisms implemented within the ansible-teleport role to ensure the secure deployment and maintenance of Teleport node services. The scope includes identity verification through CA pins, automated certificate management, and secure handling of authentication tokens during installation and upgrades.

This system ensures that Teleport nodes can securely join a cluster by validating the authenticity of the Auth Server and maintaining encrypted communication via TLS. It also facilitates the migration of security credentials from legacy configurations to prevent service disruption during version updates.
Sources: README.md, tasks/main.yml:45-56

Cluster Authentication and Identity

Teleport nodes utilize an authentication token and a Certificate Authority (CA) pin to establish a secure connection with the cluster. The CA pin is a SHA256 hash used to verify the identity of the Auth Server, preventing man-in-the-middle attacks during the initial join process.

CA Pin Retrieval and Validation

The role can automatically retrieve the cluster's CA pin by querying the proxy server's web API. This process involves a GET request to the /webapi/auth/export endpoint. The retrieved content is parsed using a regular expression to extract the SHA256 hash.

The extraction logic specifically looks for the pattern ^sha256:[a-f0-9]{64}$. If the pin is manually provided via teleport_ca_pin, the retrieval step is skipped, but the validation assertion is still performed.
Sources: tasks/security/ca_pin.yml:2-34, defaults/main.yml:47-49

Certificate Management

For deployments where the Teleport Proxy service is enabled, the role manages the lifecycle of TLS certificates. This includes directory creation with restricted permissions, private key generation, and CSR (Certificate Signing Request) creation.

TLS Infrastructure Components

Component	Default Path	Permissions	Description
Config Directory	/etc/teleport	0700	Root directory for security assets.
TLS Directory	/etc/teleport/tls	0700	Stores keys and certificates.
Private Key	/etc/teleport/tls/teleport.key	0600	4096-bit RSA private key.
CSR	/etc/teleport/tls/teleport.csr	N/A	Request for certificate signing.

Sources: tasks/security/certificate.yml:5-40, defaults/main.yml:148-151

Certificate Generation Flow

The role supports both self-signed certificates and automated ACME (Let's Encrypt) certificate issuance via certbot.

Security Credential Migration

During upgrades, the role implements a safety mechanism to preserve existing security credentials. It parses the current /etc/teleport.yaml file to extract the auth_token and ca_pin.

Migration Logic

1. Detection: The role checks for an existing configuration at teleport_config_path.
2. Parsing: If present, the YAML is decoded. The role validates that the configuration version is v3.
3. Extraction: legacy_auth_token and legacy_ca_pin are mapped from the teleport section of the YAML.
4. Conditional Migration: If the user has not provided new tokens in the playbook, the legacy values are automatically applied to the new deployment.

This ensures that a node can be updated (binaries, labels, or commands) without requiring the administrator to re-provide sensitive join tokens.
Sources: tasks/security/parse_legacy_config.yml:4-29, tasks/security/auth.yml:5-20

Ephemeral Data and Credential Changes

If the role detects that security credentials (auth_token or ca_pin) have changed compared to the legacy configuration, it performs a cleanup of ephemeral data to ensure a clean state for the new identity.

The flushing of /var/lib/teleport/proc/ is critical when a node re-joins under a different identity or token to prevent conflicts with previous session data.
Sources: tasks/config/main.yml:76-112

Summary

The security operations in this project prioritize identity integrity and automated lifecycle management. By combining strict file system permissions (0600/0700), automated CA pin verification, and robust migration logic for existing clusters, the role provides a secure path for both greenfield deployments and existing node maintenance.
Sources: tasks/main.yml, README.md