coulomb/net-kingdom
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
net-kingdom/docs/tutorials/ssh-certificates-and-tunnels.md
tegwick 0d460e3c02
Some checks are pending
CI Smoke / host-smoke (push) Waiting to run
Details
CI Smoke / container-smoke (push) Waiting to run
Details
Activate NK-WP-0009/0011; add tutorials slice and proposed ADR-0009 
- docs/tutorials: template, OpenBao and SSH tutorials (unexercised)
- tools/tutorial-verify + make tutorials-verify (NK-WP-0009-T06)
- ADR-0009 proposed: expanded-mode Keycloak trigger and topology

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Assistant: claude-code
Assistant-Model: sonnet
Assistant-Process: 295952@bnt-lap001
Assistant-Session: e93f64ad-516c-46eb-9666-aad8d300c477
2026-09-28 23:31:48 +02:00

2.3 KiB
Raw Blame History

Short-lived SSH credentials for admins, agents and automations

Exercise status: unexercised Workplan task: NK-WP-0009-T04 Pattern(s): credential routing; ops-warden AccessManagementDirective

Outcome

An actor obtains a short-lived CA-signed SSH certificate and uses it through an ops-bridge tunnel, with no static key doing the work.

Prerequisites

  • [owner: ops-warden] warden CLI installed; actor registered in the principals inventory.
  • [owner: ops-bridge] bridge CLI and a tunnel definition.
  • [owner: railiance-infra] Target hosts trust the SSH CA and carry the actor's principal.

Architecture context

ops-warden issues SSH certificates only (warden sign). ops-bridge runs the tunnel and calls the cert_command before each connect. Max TTLs: adm 48 h, agt 24 h, atm 8 h; the caller refreshes about 5 minutes before expiry. See ops-warden/wiki/CertCommandInterface.md.

Steps

  1. [owner: ops-warden] Sign a public key for the actor: warden sign <actor> --pubkey ~/.ssh/<actor>_ed25519.pub.
  2. [owner: ops-bridge] Set cert_command to that command in the tunnel definition. Leave static-key mode unused.
  3. [owner: ops-bridge] bridge up <tunnel> then bridge status.
  4. [owner: ops-warden] Inspect the cert: warden status; audit history via warden log.

Verification

Done when:

  • ssh-keygen -L -f ~/.local/state/warden/<actor>-cert.pub shows the expected principal and a Valid before within the actor-type TTL.
  • warden status exits 0 (it exits 1 if any cert is expired).
  • After expiry, the tunnel reconnects only after cert_command succeeds.

Rollback

  • bridge down <tunnel>; warden cleanup removes stale certificates.
  • Certificates expire on their own; there is no long-lived credential to revoke. Remove the actor from the inventory to stop future signing.

Threat checks

  • Cert files must be mode 600; never reuse a cert across reconnects.
  • A non-zero cert_command exit is a failure and must trigger backoff.
  • ops-warden never vends API keys or passwords; route them with warden route find.

Ownership notes

Concern Owner
Certificate issuance and TTL policy ops-warden
Tunnel lifecycle and refresh ops-bridge
Host CA trust and principals railiance-infra