AiDial Docs

#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 protected pages and actions are available.

#Which Roles Require MFA?

RoleMFA Requirement
Client Administrator (client_admin)Optional
Partner Administrator (partner_admin)Required
AiDial Administrator (aidial_admin)Required
AiDial Operator (aidial_operator)Required
Client Manager (client_manager)Optional
Client Staff (client_staff)Optional
Partner User (partner_user)Optional

For mandatory-MFA roles, the portal treats the session as compliant only after MFA is enrolled and the current sign-in has satisfied the required challenge. If a mandatory-role customer or partner session is not compliant, the portal sends the user to Settings to complete the security step.

#Supported Authentication Factors

AiDial Portal currently recognises these MFA factors from Zitadel session state:

  • totp: Time-based One-Time Password from a TOTP-compatible authenticator app.
  • recovery_code: Provider-issued recovery code used during sign-in.

The portal does not render its own authenticator QR code and does not validate TOTP or recovery-code values directly. Those steps happen in Zitadel.

#How to Enrol in MFA

  1. Sign in to the portal: Use the normal portal sign-in page. If your role requires MFA and the current session is not compliant, the portal redirects you to Settings.
  2. Open MFA setup: In Settings, use Open MFA setup when it is available. The link opens the trusted provider security page for your account.
  3. Complete setup in Zitadel: Follow the provider-hosted flow to add a TOTP authenticator app, scan the QR code shown by Zitadel, verify the current code, and save the provider-issued recovery codes.
  4. Refresh the portal status: Return to the portal and use Refresh security status. This signs in again with a callback to Settings so the portal receives fresh OIDC MFA claims.
  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, Settings 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.

#Disabling MFA

  • Roles that require MFA (partner_admin, aidial_admin, aidial_operator) cannot disable MFA while assigned to that role.
  • Optional-MFA roles can launch trusted provider MFA management from Settings only when the current lifecycle state allows it and a trusted provider management URL is available.
  • The portal does not disable the factor directly. It records the launch request and opens the provider management flow.
  • After changing MFA in the provider, refresh the portal security status so the current session reflects the new state.

#Next Steps