Certificate Handling
Relevant source files
The following files were used as context for generating this wiki page:
The Certificate Handling system in this Ansible role manages the lifecycle of TLS credentials required for Teleport's secure communications. This includes the generation of private keys, creation of Certificate Signing Requests (CSRs), issuance of self-signed certificates for internal proxy services, and the automated retrieval of Let's Encrypt certificates via ACME.
This module ensures that the Teleport Proxy and Auth services have the necessary cryptographic identity to establish trust within the cluster and with external clients. It also facilitates the discovery and validation of the Cluster CA PIN, which is critical for secure node joining.
Sources: tasks/main.yml:45-53, tasks/security/certificate.yml:1-68
Cluster Identity and CA PIN Retrieval
Before certificates are generated, the role can automatically discover the cluster's identity by fetching the CA PIN from the Teleport Proxy. This CA PIN is a SHA256 hash of the cluster's Certificate Authority, used by nodes to verify they are connecting to the correct Auth server.
The logic uses the ansible.builtin.uri module to query the proxy's export endpoint and applies a regex to extract the specific SHA256 string.
Sources: tasks/security/ca_pin.yml:2-37, defaults/main.yml:46-49
Automated Certificate Lifecycle
The role implements a structured flow for generating TLS credentials when teleport_proxy_enabled is true. This process involves creating the directory structure, generating a high-entropy RSA private key, and producing a CSR with configurable Subject Alternative Names (SANs).
Directory and Key Management
The system ensures specific directories exist with restricted permissions (0700) for storing sensitive material like private keys. Private keys are generated using 4096-bit RSA encryption.
| Path Variable | Default Value | Purpose |
|---|---|---|
teleport_config_dir | /etc/teleport | Root configuration directory |
teleport_proxy_tls_dir | /etc/teleport/tls | Storage for certificates and keys |
teleport_proxy_tls_key | /etc/teleport/tls/teleport.key | Private key file |
Sources: tasks/security/certificate.yml:4-38, defaults/main.yml:41, 151-155
Self-Signed Certificate Generation
For internal or initial deployments, the role generates a self-signed X.509 certificate. The CSR includes the proxy server address and defaults to standard geographic metadata.
External Certificate Integration (ACME/Let's Encrypt)
When teleport_proxy_acme_enabled is toggled, the system shifts from self-signed certificates to automated issuance via Certbot.
- Dependency Management: Installs
certbotandpython3-certbotpackages. - Request Execution: Uses the
standaloneauthenticator to request a certificate from Let's Encrypt. - Persistence: Utilizes
--keep-until-expiringto avoid unnecessary renewals during configuration runs.
Sources: tasks/config/proxy.yml:62-83, defaults/main.yml:156
Configuration Parameters
The following variables control the behavior of the certificate handling logic:
| Variable | Type | Default | Description |
|---|---|---|---|
teleport_tls_country | String | BR | Country for CSR |
teleport_tls_organization | String | Datacosmos | Organization name for CSR |
teleport_tls_valid_days | Integer | 365 | Expiry for self-signed certs |
teleport_tls_sans | List | [] | Additional Subject Alternative Names |
teleport_validate_certs | Boolean | true | Whether to validate API certs |
Sources: defaults/main.yml:54-66, tasks/security/certificate.yml:48-52
Summary
Certificate handling in this role provides a dual-path approach for securing Teleport. It automates the extraction of cluster trust (CA PIN) and manages TLS assets through either local generation (OpenSSL-based CSR and self-signing) or external integration (ACME/Certbot). This ensures that the Teleport Proxy is equipped with valid identity credentials immediately upon deployment.