Enforce MFA

Multi-factor authentication is optional by default in AKKO v2026.04 so the seed demo users (alice / bob / carol / dave / eve) remain usable in dev clusters without a TOTP app. For production — and to satisfy NIS2 Art. 21(2)(h) (cryptography + access control) — flip the MFA overlay.

Overlay

helm upgrade akko oci://harbor.akko-ai.com/akko-charts/akko \
  --version 2026.04 \
  -f values-harbor.yaml \
  -f values-domain.yaml \
  -f values-dev-secrets.yaml \
  -f values-mfa-enforce.yaml

What the overlay does

1. Flips the Keycloak required action CONFIGURE_TOTP to defaultAction=true — every new user is prompted to enrol TOTP on first login.
2. Marks existing akko-admins + akko-engineers group members with the same required action so they must enrol at the next login.
3. Adds webauthn-register (hardware key) required action on akko-admins for defence-in-depth.
4. Raises the realm password policy to 12 chars + upperCase + digit + special + not-username + history(5).

What the overlay does NOT do

• Does not force MFA on akko-analyst, akko-steward, akko-viewer — those roles can keep password-only access when the cluster sits behind a VPN. Override roleRequiredActions if you want to extend.
• Does not replace Keycloak sessions already open. Users with a live session keep using it until expiry; then the next login triggers TOTP enrolment.

Roll-out plan

Step	Who	Action
1	Admins	Enable on a staging realm first; verify the login flow
2	Comms	Email the user base 7 d ahead with a link to the "How to enrol TOTP" doc
3	Ops	Apply the overlay in prod during a maintenance window
4	Support	Monitor the lockout queue (#akko-support Slack) for 48 h
5	Compliance	Archive the change as evidence of NIS2 Art. 21(2)(h) control

Disable

If you need to roll back for an incident, omit the overlay and helm upgrade again. The required actions are idempotent and Keycloak will let users log in without TOTP until their enrolment is revoked manually.

User-facing instructions (localise + distribute)

1. Go to https://cockpit.<domain>/account.
2. Click Account Security → Two-Factor Authentication.
3. Scan the QR code with Google Authenticator, Microsoft Authenticator, 1Password, Bitwarden or any RFC 6238 TOTP app.
4. Enter the 6-digit code.
5. Save the recovery codes in a password manager.

Observability

• akko_keycloak_login_total{grant="password_and_totp"} — TOTP-enforced logins
• akko_keycloak_login_total{grant="password_and_webauthn"} — admins with hardware key
• akko_keycloak_login_failures_total — bumps when MFA fails

Troubleshooting

Symptom	Cause	Fix
User stuck on "Configure TOTP" with a blank QR code	Keycloak pod time drift	kubectl exec ... -- date against NTP
"Invalid code" on every try	Authenticator clock skew	Resync phone NTP, or widen Keycloak window (Admin → Authentication → OTP → Window)
Bulk user lockout after apply	Emergency overlay skipped the comms step	Admin can reset CONFIGURE_TOTP per-user via Admin → Users → Required Actions