Jon Chery
b6dd86fdf3
- 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---
98 lines
3.3 KiB
Markdown
98 lines
3.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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**:
|
|
```bash
|
|
# 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
|
|
|
|
1. `orca init` bootstraps the cluster CA (step-ca, mTLS-only).
|
|
2. `orca auth init-idp --rp-id <cluster-domain>` deploys Dex behind
|
|
Traefik (step-ca cert) with the WebAuthn connector configured.
|
|
3. First operator authenticates via an existing session or admin
|
|
bootstrap token, then registers a passkey:
|
|
|
|
```bash
|
|
orca auth register
|
|
```
|
|
|
|
4. 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
|
|
|
|
```bash
|
|
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).
|
|
|
|
## See also
|
|
|
|
- [docs/oidc.md](oidc.md) — OIDC configuration (Dex quickstart, BYO IdP)
|
|
- [docs/security-runbook.md](security-runbook.md) — security runbook
|
|
- [docs/cli.md](cli.md#orca-auth) — `orca auth` CLI reference
|