Two-factor authentication

Citadel two-factor authentication adds a six-digit authenticator-app code to local password sign-in.

Citadel TOTP applies only when you sign in with a Citadel username or email and password. If you sign in with OIDC or SSO, multi-factor authentication is controlled by your identity provider.

Under Profile → Security → Two-factor authentication, select Manage two-factor authentication to open the authenticator and recovery-code controls.

Supported authenticator apps include:

• Microsoft Authenticator
• Google Authenticator
• Bitwarden
• 1Password
• Authy

Before You StartCopy Anchor Link

You need:

• a Citadel account that can sign in with a local password
• your current Citadel password
• an authenticator app installed on your phone or password manager

When setup is complete, Citadel shows recovery codes once. Save them somewhere secure before closing the dialog.

Enable Two-Factor AuthenticationCopy Anchor Link

Open:

Profile -> Security -> Two-factor authentication

Select Enable.

Citadel asks for your current password before creating the authenticator setup.

After your password is accepted:

1. Open your authenticator app.
2. Add a new account.
3. Scan the QR code shown by Citadel.
4. If you cannot scan the QR code, enter the manual secret shown below it.
5. Enter the six-digit code from your authenticator app.
6. Select Confirm.

Citadel then enables two-factor authentication and shows recovery codes.

Completing optional two-factor setup replaces the current browser session and signs out other sessions. The replacement keeps the original session expiry, so enabling MFA does not extend the sign-in period. Previously copied access and refresh tokens from that session no longer authenticate.

Save Recovery CodesCopy Anchor Link

Recovery codes let you sign in if you lose access to your authenticator app.

Citadel shows recovery codes only once. Use Copy or Download, then confirm that you saved them.

Each recovery code can be used one time. After a code is used, it cannot be used again.

Store recovery codes somewhere separate from your authenticator device, such as a password manager or another secure location.

Sign In With Two-Factor AuthenticationCopy Anchor Link

After two-factor authentication is enabled, local sign-in uses two steps:

1. Enter your username or email and password.
2. Enter the six-digit code from your authenticator app.

Citadel does not issue an access token or refresh session until the second step succeeds.

If you cannot access your authenticator app, select the recovery-code option on the verification screen and enter one unused recovery code.

Mandatory Setup During LoginCopy Anchor Link

MFA is optional by default and can be enabled later from Profile → Security. An administrator can choose an installation-wide policy during first-run setup or in Administration → Instance: Optional, Required for administrators, or Required for everyone. Changes apply to subsequent local-password sign-ins; existing browser sessions are not revoked by changing the policy.

CITADEL_MFA_POLICY sets the minimum policy allowed by server configuration. The UI cannot select a weaker policy.

When policy requires setup, Citadel prompts you after you enter a valid username or email and password. Complete the QR-code setup and save recovery codes before entering the application.

The same policy applies immediately after the first administrator is created. See First-run setup for initial installation instructions.

If the setup session expires, return to the login page and sign in again to start a new setup session.

Regenerate Recovery CodesCopy Anchor Link

Regenerate recovery codes when:

• you lost your saved recovery codes
• you think someone else may have seen them
• most of your recovery codes have already been used

Open:

Profile -> Security -> Two-factor authentication

Select Recovery Codes.

Citadel asks for your current password and a current authenticator code. After confirmation, Citadel creates a new set of recovery codes and invalidates the previous set immediately.

Disable Two-Factor AuthenticationCopy Anchor Link

Open:

Profile -> Security -> Two-factor authentication

Select Disable.

Citadel asks for:

• your current password
• either an authenticator code or one unused recovery code

Two-factor authentication cannot be disabled when the active Citadel policy requires it for your account.

If You Lose AccessCopy Anchor Link

If the lost device also had a signed-in browser, review and revoke that session under Profile → Security.

If you lose access to both your authenticator app and recovery codes, contact a Citadel administrator.

An administrator can reset your two-factor authentication. This removes your existing TOTP setup, invalidates existing recovery codes, clears outstanding MFA challenges, and signs out existing sessions.

If policy still requires two-factor authentication, your next local password login will require mandatory setup again.

TroubleshootingCopy Anchor Link

If a valid-looking code is rejected:

• Make sure you are using the current Citadel account entry in your authenticator app.
• Wait for the next six-digit code and try again.
• Check that your device clock is set automatically.
• Use an unused recovery code if you cannot generate a working authenticator code.

If recovery-code verification fails:

• Enter the code exactly as saved.
• Hyphens and spaces are optional.
• Codes are case-insensitive.
• Make sure the code was not already used.

If the setup page expires, sign in again and restart setup.