Replacing Static SSH Keys with Teleport Certificates: An Architecture Note

The problem with persistent SSH keys

Static SSH keys in authorized_keys files are difficult to revoke. When a developer leaves or a laptop is lost, every affected host must be updated, and any missed file leaves a backdoor. Teleport replaces this model by issuing short-lived X.509 certificates signed by a cluster certificate authority (CA). Users authenticate once, receive a certificate with an embedded expiry and role set, and the fleet accepts that certificate instead of a static key. The useful takeaway: you can remove authorized_keys entirely and still provide interactive SSH access, provided your auth server remains available.

Requirements for certificate-based access

The core requirement is eliminating long-lived credentials. Users authenticate through single sign-on (SSO) or local Teleport users; the auth server then issues an SSH certificate containing the user's identity, allowed principals, and a time-to-live (TTL). Nodes must run the Teleport daemon and join the cluster using a signed node token rather than a pre-shared key. The proxy handles browser and command-line ingress, so no separate bastion host is required—the proxy only relays sessions.

Smallest suitable deployment topology

A minimal production-ready design uses three components:

1. Auth server (single instance for small fleets): stores the CA keys, issues certificates, and writes the audit log.
2. Proxy: terminates TLS for browser access and relays SSH tunnels to nodes. It does not decrypt SSH traffic.
3. Nodes: run the teleport daemon with the SSH service enabled and register with the auth server.

For a Linux node joining the cluster, create a join token on the auth server, then configure the node daemon.

Run this on the auth server (requires tctl admin privileges):

tctl tokens add --type=node --labels=env=prod

Expected check: the command returns a token string. Risk: tokens are bearer credentials; store them only in your configuration management system and rotate them if exposed.

Run this on the target node (requires root or a user with write access to /etc/teleport). Create or edit /etc/teleport/teleport.yaml:

teleport:
  auth_token: "TOKEN_FROM_AUTH_SERVER"
  auth_servers: ["auth.example.com:3025"]
  data_dir: /var/lib/teleport
ssh_service:
  enabled: true

Replace auth.example.com:3025 with your auth server's reachable address and port. Start the daemon and confirm the node appears in the cluster:

systemctl enable --now teleport
tctl get nodes

Expected check: tctl get nodes lists the new hostname. Risk: if the auth server is unreachable, the node cannot renew its certificate and will eventually stop accepting new connections.

Trust and data boundaries

The auth server's CA keys are the root of trust. Proxies and nodes are semi-trusted workers: they verify certificates but cannot mint them. End-user devices hold only short-lived credentials, so a compromised laptop loses access when the certificate expires.

Session metadata and recorded events flow through the auth server's audit log. Recordings can remain on the auth server or be forwarded to external storage. Importantly, client-to-node SSH traffic remains encrypted end-to-end; the proxy relays the tunnel rather than terminating it to read commands. This means the proxy is a network choke point but not a decryption point.

Operational checks

Monitor these signals continuously:

• Certificate TTLs and renewal failures: alert when user or node certificates approach expiry without renewal.
• Node heartbeat/liveness: detect nodes that have stopped renewing their registration.
• Auth server health: for a single-node deployment, watch disk pressure and process health; for HA clusters, watch quorum.
• Proxy connectivity: ensure the proxy can reach the auth server and nodes.
• Audit log ingestion: confirm session start/stop events are being written.

A practical check is to inspect an issued certificate. After logging in with tsh login --proxy=proxy.example.com:3080, run tsh status to view the active identity and its expiry. Confirm that SSH access fails after the certificate expires.

Failure modes

• Auth server outage: new logins and certificate renewals fail. Existing sessions may continue until their certificates expire.
• Proxy loss: new ingress is blocked, but already-established sessions continue.
• CA key loss: the fleet must be re-enrolled; there is no recovery without a backup of the CA keys.

Conditions that change the design

Move beyond the single-node topology when:

• Multi-region HA is required: deploy an auth server cluster with quorum and trust across regions.
• Dynamic Kubernetes or database access is needed: this typically requires Teleport Enterprise features.
• FIPS or regulated environments apply: these impose specific cryptographic and audit requirements.
• Session-recording retention is high: separate audit storage from the auth server to avoid disk pressure.

Limitations and verification

Feature availability differs between Teleport Community and Enterprise editions; verify which capabilities (for example, SSO connectors and session recording controls) apply to your license. Certificate lifetimes, join methods, and RBAC label semantics are version-sensitive—confirm against your target release. Do not reuse static SSH keys alongside Teleport without policy; mixed trust models undermine the certificate boundary.

To validate the design before production, deploy a lab auth server and proxy, enroll one node, and confirm a user can SSH using only a Teleport-issued certificate with no authorized_keys file. Inspect the certificate to verify embedded principals, TTL, and roles, then confirm access is denied after expiry. Simulate auth server downtime and observe that new logins fail while existing sessions continue. Finally, review the auth server audit log to confirm session start/stop events and recording metadata are captured.