Choosing a Certificate TTL for Teleport SSH Access: A Decision Guide

The decision you're actually making

Teleport replaces static SSH keys with short‑lived X.509 certificates issued by its internal certificate authority (CA). Once you adopt it, the main tuning knob is the certificate time‑to‑live (TTL): how long an issued certificate remains valid before the user must re‑authenticate. TTL is set per role and directly trades security against user friction and renewal load.

This guide assumes Teleport 13+ (the role field max_session_ttl and the default 12‑hour TTL have been stable across recent major versions). Verify against your version's role reference before applying changes to production.

Constraints to pin down first

• Compliance window: Some policies require re‑authentication at fixed intervals (for example, every 8 or 24 hours). That sets an upper bound.
• Session behavior: TTL governs the certificate's validity. Long‑running sessions may persist past expiry depending on your disconnect_expired_cert setting — decide whether expiry should kill active sessions or only block new ones.
• IdP round‑trips: If login goes through SSO (OIDC/SAML), every renewal is an IdP interaction. Very short TTLs multiply that traffic and annoy users on MFA.
• Automation: Machine identities (via Machine ID) renew automatically, so bots tolerate short TTLs far better than humans do.

Comparing the practical options

Trade‑offs worth understanding

Shorter TTLs shrink the window in which an exfiltrated certificate is useful, and they make revocation less critical — you can often just wait for expiry. The cost is renewal churn: every expiry forces a new issuance, which is recorded in the audit log and adds load to the auth service. Teleport's audit log captures issuance and usage events without extra agents, so high renewal rates also mean noisier logs to retain and search.

Longer TTLs reduce friction but weaken the core argument for certificate auth. If you set 24‑hour TTLs everywhere, you've partially recreated the static‑key problem with a shorter rotation cycle. A common pattern is tiered TTLs: 12 hours for default developer roles, 1–2 hours for privileged roles, and minutes for automated identities.

Note also that Teleport can integrate with an existing PKI for trust continuity, but the SSH user CA TTL is still governed by Teleport role configuration — external CA integration doesn't change this knob.

Concrete implementation

Set the TTL on a role. Run this on a host where you have tctl access to the auth service (typically the auth server itself, or a machine with an admin identity file), with a Teleport admin role:

# role-dev.yaml\nkind: role\nversion: v6\nmetadata:\n  name: dev\nspec:\n  options:\n    max_session_ttl: 12h\n    # Set to true if expiry should terminate active sessions\n    disconnect_expired_cert: false\n  allow:\n    logins: [ubuntu, debian]\n    node_labels:\n      env: staging

Apply it and confirm:

tctl create -f role-dev.yaml\ntctl get role/dev --format yaml | grep max_session_ttl

The risk here is real: lowering TTL on a role that automation depends on will break any workflow that can't re‑authenticate. Inventory which users and bots hold the role (tctl get users, then check role assignments) before changing it.

Validating the result

Three checks, in order of increasing rigor:

1. Check the issued certificate. As a user holding the role, run tsh login --proxy=teleport.example.com (replace with your proxy address), then tsh status. The displayed "Valid until" time should match login time plus your configured TTL. This is the fastest confirmation.
2. Confirm enforcement on the node. Connect with tsh ssh user@node and inspect the node's Teleport debug logs for certificate validation events — you should see the cert's validity period evaluated at connection start. Verification happens once at connection setup and is cached for the session, so per‑connection overhead is negligible.
3. Cross‑check the audit log. Query the audit log (tctl audit log exec or your SIEM export) for the cert.create event and compare the certificate's expiry against the role's TTL. This gives you compliance evidence that issuance matches policy.

Limitations

• TTL changes apply to newly issued certificates; already‑issued certs keep their original expiry. Wait one full old‑TTL cycle before declaring the change fully effective.
• disconnect_expired_cert: true improves enforcement but will drop long‑running sessions (including scp transfers and port forwards) at expiry — test before enabling.
• Exact field names and defaults vary slightly across Teleport major versions; confirm against the role reference for your deployed version.