Multi-Factor Authentication

Nauthera supports time-based one-time passwords (TOTP, RFC 6238) as a second factor for user logins. Users can enrol any TOTP-compatible authenticator app (Google Authenticator, Authy, 1Password, Bitwarden, etc.) and generate single-use backup codes for account recovery.

MFA is available on all tiers. It is enforced per AuthPolicy.

#How TOTP Works in Nauthera

1. A user enrols by scanning a QR code in the login UI.
2. Nauthera generates a 20-byte cryptographically random secret (stored encrypted at rest).
3. Every login after enrolment requires the current 6-digit TOTP code, with ±30-second clock tolerance.
4. Constant-time code comparison prevents timing side-channel attacks.

#Enforcing MFA via AuthPolicy

API stability: auth.nauthera.io/v1alpha1 is an alpha API. Fields and behaviour may change between releases. Pin your Helm chart version in production.

Add requireMfa: true to a ClusterAuthPolicy or AuthPolicy to require second-factor authentication for all token issuance governed by that policy:

apiVersion: auth.nauthera.io/v1alpha1
kind: ClusterAuthPolicy
metadata:
  name: mfa-required
spec:
  requireMfa: true
  allowedScopes:
    - openid
    - profile
    - email
  tokenSettings:
    accessTokenTTL: 1h
    refreshTokenTTL: 24h
    idTokenTTL: 1h

Users who have not enrolled MFA will be prompted to enrol during their next login when requireMfa: true.

#User Enrolment

Users enrol MFA from the login UI after authenticating with their password. The flow:

1. User logs in with username and password.
2. If MFA is required and not yet enrolled, the user is redirected to the MFA setup screen.
3. The user scans the QR code with an authenticator app.
4. The user enters a one-time code to confirm enrolment.
5. 10 backup codes are displayed. The user must save these now — they are shown once and never stored in plaintext. Recommend downloading or copying them to a password manager before closing the screen.

#Admin: Reset a User's MFA

If a user loses their authenticator device, an admin can reset their MFA credential via the admin API:

# Returns: 204 No Content on success
curl -X POST https://auth.example.com/api/admin/users/{username}/reset-mfa \
  -H "Authorization: Bearer $ADMIN_TOKEN"

This removes the enrolled TOTP credential and any remaining backup codes. The user will be prompted to re-enrol on their next login.

Or via kubectl:

kubectl exec -n nauthera-system deploy/nauthera-operator -- \
  nauthera-admin user reset-mfa --username alice@example.com

#Backup Codes

At enrolment time, Nauthera generates 10 single-use backup codes. Each code is:

• 8 uppercase characters from a Base-32 alphabet (ambiguous characters I, L, O, S excluded)
• Stored as a bcrypt hash — the plaintext is shown once and never stored
• Consumed on use — each code can only be used once
• Displayed in XXXX-XXXX format (hyphen is cosmetic, not validated)

If the enrolment screen is closed before the user saves their codes, the codes are unrecoverable. An admin must regenerate them (see below).

Users cannot self-rotate backup codes. Regeneration requires admin action.

If a user has exhausted or lost their backup codes, an admin can regenerate them:

# Returns: 200 OK with new codes (shown once — save immediately)
# Response: {"backup_codes": ["ABCD-EFGH", ...]}
curl -X POST https://auth.example.com/api/admin/users/{username}/regenerate-backup-codes \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Important: Regenerating backup codes immediately invalidates all previously issued codes. The new plaintext codes are returned in the API response — copy them immediately and deliver them securely to the user.

#Security Properties

A note on HMAC-SHA1: RFC 6238 specifies HMAC-SHA1 as the standard TOTP algorithm, and it remains the algorithm supported by virtually all authenticator apps. The use of SHA-1 here is for HMAC keying in a short-lived OTP context — not for collision-resistant hashing — and is not subject to the SHA-1 collision vulnerabilities that affect certificate signing. RFC 6238 also defines SHA-256 and SHA-512 variants; these are on the roadmap.

#Related

• AuthPolicy reference — enforce MFA per namespace
• User Management — manage user accounts
• Login Experience — customise the MFA enrolment UI