Files

T

Jon Chery b6dd86fdf3 docs(P11): doc drift round 2 — README, cli.md, CHANGELOG, verify-reqs (REQ-160)

- README: status banner v0.12+v0.13, latest tag v0.12.10, subcommand
  table expanded (auth/nft/peer-setup/secrets rotate-master), "mTLS by
  default" corrected to "SSH-push canonical", docs table updated
- docs/cli.md: complete rewrite (521->1465 lines), all ~40 subcommands
- CHANGELOG: regenerated from git log (v0.11.29..HEAD)
- help text: job run HCL->markdown, job stop daemon->SSH-push
- docs/security-runbook.md: expanded to match P05 reality (seal/unseal,
  doctor audit/modes/oidc, incident response)
- docs/webauthn.md: added auth register (P06)
- docs/namespace.md: added inherit + set-constraint
- internal/proxmox/bootstrap.go: comments password->key auth
- internal/cli/status.go: deprecation warning
- scripts/verify-docs.sh + make verify-docs: cli.md <-> orca --help
- cmd/verify-reqs/main.go: fix bold-format regex (was bypassing v0.12)
  + case-insensitive status matching
- .ciagent/REQUIREMENTS.md: v0.12 REQs marked complete
- .ciagent/ROADMAP.md: v0.12 bolded COMPLETE

---ci---
project: orca
phase: 11
milestone: v0.13
status: complete
requirements:
  covered: [160]
---/ci---

2026-08-10 14:18:27 +00:00

3.3 KiB

Raw Blame History

WebAuthn / Passkeys (v0.13)

Overview

The bundled Dex uses a custom WebAuthn connector (orca-webauthn-connector, REQ-148) for password-free authentication. Passkeys are public-key credentials — the private key never leaves the authenticator (TPM / security key / phone Secure Enclave). This directly satisfies R-021 (no Orca-issued credentials): the authenticator proves possession of the private key without ever exposing it.

The WebAuthn connector ships as part of the v0.12 milestone (P05) and is operationally wired in v0.13 (P04: registration requires auth; P06: real Dex deployment).

Registration

orca auth register [--no-browser]

Opens the browser to the Dex WebAuthn registration page at https://<cluster>/orca/webauthn/register. The operator authenticates via an existing session or admin bootstrap token, then performs the WebAuthn ceremony (biometric or security key). After the ceremony, Dex maps the credential ID to an OIDC sub.

--no-browser: print the registration URL instead of opening a browser (useful for headless operators or remote SSH sessions — copy the URL into a local browser).

Credentials are stored at ClusterDir()/webauthn-credentials.db (mode 0600, public keys only — private keys never leave the authenticator and are never stored by orca).

Example:

# Interactive (opens browser)
orca auth register

# Headless / remote SSH (print URL)
orca auth register --no-browser
# → https://orca.local/orca/webauthn/register

RP ID

The relying-party ID is the cluster's Traefik-served domain, set via --rp-id on orca auth init-idp (C-38). The RP ID must match the cluster's Traefik domain — WebAuthn enforces that the RP ID is a registrable domain suffix of the current origin.

HTTPS secure context is provided by Traefik (step-ca cert, R-017). WebAuthn requires a secure context (HTTPS or localhost); the step-ca cert behind Traefik satisfies this.

Bootstrap Sequence

orca init bootstraps the cluster CA (step-ca, mTLS-only).
orca auth init-idp --rp-id <cluster-domain> deploys Dex behind Traefik (step-ca cert) with the WebAuthn connector configured.
First operator authenticates via an existing session or admin bootstrap token, then registers a passkey:
```
orca auth register
```
Subsequent operators use WebAuthn login (orca auth login opens the browser to the Dex login page; the WebAuthn ceremony is one of the available upstreams).

Health Check

orca doctor oidc

Verifies the bundled Dex OIDC provider is running and the /.well-known/openid-configuration endpoint responds. Run after orca auth init-idp or after a Dex config change.

Security properties

No passwords: WebAuthn is password-free. No password is ever sent to or stored by orca (R-021).
Phishing-resistant: the WebAuthn protocol cryptographically binds the ceremony to the RP ID, defeating credential phishing.
Private key never leaves the authenticator: orca stores only public keys.
Secure context required: HTTPS via step-ca / Traefik (C-38).

3.3 KiB Raw Blame History