#Multi-Factor Authentication (MFA)

#Overview

Multi-factor authentication adds an extra layer of security to your AiDial portal account. Sign-in, authenticator setup, MFA challenge, and recovery-code entry are handled by AiDial's identity provider, while the portal checks that your account satisfies the required MFA policy before non-remediation protected pages and actions are available.

#Which Roles Require MFA?

When MFA is required for a session, the portal treats it as compliant only after MFA is enrolled and the current sign-in has satisfied the required challenge. A non-compliant customer session goes to Account → Security, a partner session to Settings, and an internal AiDial administrator/operator session to Profile.

#Supported Authentication Factors

AiDial Portal currently recognises these MFA factors in portal MFA snapshots built from Zitadel OIDC/session state and, where available, a server-side enrolled-factor lookup:

• totp: Time-based One-Time Password from a TOTP-compatible authenticator app.
• recovery_code: Provider-issued recovery code used during sign-in.
• email_otp: Email one-time code. This is policy-allowed for client_admin and partner_admin only, unless a trusted provider policy claim explicitly allows it for another role.
• sms_otp: SMS one-time code. Policy-allowed for client_admin and partner_admin only, gated by a per-tenant override (mfa.sms_otp.enabled, default OFF). Internal staff (aidial_admin, aidial_operator) are hard-denied. AU phone numbers only at launch. See sms-otp.md for the customer-facing privacy notice and sub-processor disclosure.
• webauthn: Passkey or security key. Policy-allowed for client_admin, partner_admin, aidial_admin, and aidial_operator. The portal accepts Zitadel's pinned user AMR value as WebAuthn challenge evidence and never treats generic mfa or otp as WebAuthn.

The portal reports policy-allowed factors separately from factors enrolled by the current user. Operators must not treat allowed_factors as proof that a user has enrolled the factor; use enrolled_factors, enrolled_factors_source, and the current challenge state for that. server_lookup is authoritative. amr_inference_fallback preserves conservative AMR-derived evidence but cannot prove absence and cannot distinguish OTP-class factors from one another.

The portal does not render its own authenticator QR code and does not validate TOTP, email OTP, SMS OTP, passkey, security-key, or recovery-code values directly. Those steps happen in Zitadel.

#Where MFA Settings Live

The MFA surface you see depends on your role.

The richer Settings > Profile & Security panel (MFA setup link, SMS factor card, passkey card, declare recovery-code regeneration, disable-launch action) is code that no customer role reaches today: client_admin requests to /settings?section=profile are redirected to /account, and client_manager / client_staff get a not-found response there because their Profile section moved to the Account shell.

#How to Enrol in MFA

1. Sign in to the portal: Use the normal portal sign-in page. If the current session requires MFA and is not compliant, the portal redirects you to the role-specific surface listed above.
2. Open MFA setup: Go to the surface for your role (see Where MFA Settings Live) and use the trusted provider link when it is available — the per-method action on Account > Security for customer roles, or Re-enrol on the internal Profile page. The link opens the trusted provider security page for your account. Partner accounts do not get a setup link; partner MFA is operations-managed.
3. Complete setup: For TOTP, passkeys/security keys, and recovery codes, follow the provider-hosted Zitadel flow. SMS one-time code has no reachable enrolment card today (see SMS One-Time Code).
4. Refresh the portal status: Return to the portal and sign in again so it receives fresh OIDC MFA claims. Where shown, Refresh security status starts that flow for you.
5. Acknowledge recovery-code storage if prompted: After enrolment, re-enablement, or declared recovery-code regeneration, the portal may ask you to confirm that you stored the current recovery-code set.

#Recovery Codes

Recovery codes are managed by Zitadel, not generated or displayed by AiDial Portal. Use them from the provider sign-in flow if you lose access to your authenticator app.

The portal stores only non-secret lifecycle markers for recovery-code acknowledgements and reminders. It does not store raw recovery codes.

#Important Guidelines

• Store recovery codes securely: Save them in a password manager or print them and keep them in a secure location.
• Acknowledge storage in the portal when prompted: This records that you stored the current provider-issued set; it does not copy the codes into the portal.
• Review or regenerate codes in the provider: If a trusted provider management link is available, use it to review or regenerate recovery codes, then refresh the portal status.
• Respond to recovery-code reminders: If the portal detects a recovery-code sign-in, your security surface may remind you to review or regenerate your codes.
• Never send raw recovery codes to support: Support can guide recovery steps, but users and operators must not paste recovery-code values, authenticator seeds, one-time codes, session cookies, or bearer tokens into tickets or chat.

#Recovery & Lockout

#If You Lose Your Authenticator Device

1. Use a recovery code in Zitadel: During provider sign-in, use the recovery-code option if it is available for your account.
2. Review your recovery options: After signing in with a recovery code, the portal may show a reminder in Settings to review or regenerate recovery codes.
3. Set up a new authenticator device: Use the trusted provider management link from Settings when available, then refresh the portal status.

#If You Have Lost Both Your Authenticator and Recovery Codes

If you cannot access your authenticator app and have no remaining recovery codes:

1. Contact your organisation's administrator: They may be able to assist with account recovery through the identity provider's administrative tools.
2. Contact AiDial support: If your administrator is unable to help, contact help@aidial.com.au for further assistance.

The portal cannot bypass MFA on its own, reveal one-time codes, or reset MFA from an unauthenticated browser session. Account recovery is managed through the identity provider and authorised support processes.

#Operator Readiness Checks

The MFA flows depend on the portal's standard required runtime configuration: NEXTAUTH_SECRET, NEXTAUTH_URL, AIDIAL_API_BASE_URL, AIDIAL_API_TIMEOUT_MS, ZITADEL_ISSUER, ZITADEL_CLIENT_ID, and ZITADEL_CLIENT_SECRET. These values are required; the portal code does not define fallback defaults for them.

Before changing MFA provider policy beyond the current portal foundation, operators must complete these development-environment checks and record evidence in the release notes:

1. Keep the pinned Zitadel AMR and enrolled-factor lookup evidence current for TOTP, recovery code, email OTP, SMS OTP, and WebAuthn/passkey.
2. Confirm whether Zitadel exposes enrolled factors in OIDC claims or requires the server-side enrolled-factor lookup, and document when the portal is using AMR inference fallback.
3. Verify client_admin, partner_admin, aidial_admin, and aidial_operator can use WebAuthn only where policy allows it.
4. Verify aidial_admin and aidial_operator cannot satisfy mandatory MFA with email OTP or SMS OTP unless an explicit approved provider policy and portal implementation allow it.
5. Verify recovery-code sign-in still shows the recovery-code-first remediation path.
6. Verify APP 5 collection notice copy is presented before the SMS factor card collects a phone number. The portal has no email-OTP collection surface today; email OTP appears only as a policy or enrolled-factor label.
7. Verify audit metadata contains only safe factor identifiers and marker IDs, not OTPs, email addresses, phone numbers, tokens, cookies, or recovery codes.

Internal operators should consult the AiDial operations runbooks for the current pinned-claim table, recorded live evidence, and the safe path to enable email OTP in development without changing customer-facing Zitadel policy. This guide stays focused on portal end-user behaviour.

#Passkey / Security Key Gate

Passkeys and security keys are provider-hosted in Zitadel. The portal does not store WebAuthn credential IDs, public keys, attestation, assertions, challenges, or raw recovery codes. The passkey card on Settings > Profile & Security may show a device label and last-used timestamp when Zitadel's enrolled-factor lookup returns those safe fields; the card is hidden unless webauthn is policy-allowed for your role or already enrolled. The internal Profile factor table shows factor state and last-used only.

The portal accepts only the pinned Zitadel user AMR value as WebAuthn challenge evidence. Generic mfa or otp AMR values are not enough to identify a passkey/security-key challenge.

Recovery codes remain provider-managed. Because Zitadel maps recovery-code authentication to generic otp, the portal does not infer recovery-code use from otp; recovery-code lifecycle reminders continue to rely on the existing explicit marker paths.

#SMS OTP Gate

SMS OTP enrolment is implemented but remains deny-by-default unless both the role policy and tenant override allow it. The SMS factor card is coded only on the Settings > Profile & Security panel, and it is hidden there unless allowed_factors includes sms_otp (which folds the role and tenant-override checks together). When it renders, it shows the APP 5 notice before collecting an Australian +61 mobile number. partner_admin is policy-allowed at the enrolment route but sees the read-only operations-managed block instead, and client_admin is redirected off that panel to the Account shell, so no role has a self-service enrolment path through supported navigation.

POST /api/auth/mfa-sms-enrol enforces CSRF/session auth, permits only client_admin and partner_admin, requires the mfa.sms_otp.enabled tenant override, validates AU E.164 numbers, applies rate limits, forwards the number once to Zitadel's otp_sms factor endpoint, and discards the plaintext. Responses and audit metadata use the masked phone tail only, with forbidden fields redacted.

SMS OTP challenge evidence must not be inferred from generic mfa or otp AMR values. Current parsers keep sms_otp AMR aliases empty; enrolled SMS state comes from the server-side Zitadel enrolled-factor lookup when available. If the provider integration is unavailable, SMS enrolment fails closed with a provider-unavailable response.

#Disabling MFA

• Roles that require MFA (partner_admin, aidial_admin, aidial_operator) cannot disable MFA while assigned to that role.
• The disable-launch action is coded on the Settings > Profile & Security panel only, which customer roles are currently redirected away from, so no role reaches it through supported navigation. Where it does render, it appears only when MFA is not required for the role, the account is currently enrolled, the challenge state is known, and a trusted provider management URL is available.
• Account > Security and the internal Profile page do not offer a disable action. They link out to the trusted provider security page and record recovery-code acknowledgements. Remove the factor in the provider instead.
• The portal does not disable the factor directly. It records the launch request and opens the provider management flow in a new tab.
• After changing MFA in the provider, refresh the portal security status so the current session reflects the new state.

#Next Steps

• Understand your role and permissions
• Learn about session security
• Learn about signing in