> ## Documentation Index
> Fetch the complete documentation index at: https://docs.curator.interworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Multifactor Authentication (MFA)

> A guide to setting up multifactor authentication (MFA) for Curator users.

If your Curator system is using a Curator-based authentication form, multifactor authentication is available utilizing
Google Authenticator (or another authenticator app of your choice -- see
[Customizing the Suggested Authenticator App](#customizing-the-suggested-authenticator-app) below).

After enabling multifactor authentication, users will be prompted to setup the Authenticator application using a QR
code. For more information on the frontend user interface, see our
[feature demo video](https://curator.interworks.com/page/curator-new-feature-spotlight-multi-factor-authentication).

## Curator Setup

Only a superuser can turn Multi-factor Authentication on or off.

1. To enabled MFA, go to **Settings** > **Security** > **Authentication**.
2. On the **Security & Access** tab, toggle "ON" the Multi-factor Authentication switch.
3. Save these settings
4. Now, all users will be prompted to setup and use multifactor authentication after their next login.

## What Users See Before MFA Is Complete

Until a user enters a valid code, Curator hides the menus and navigation and shows only the MFA page, with a
**Log out** link for users who signed in to the wrong account or cannot finish MFA. Every other page, including
`/preview`, the unsubscribe pages, and pages whitelisted for anonymous access, redirects to the MFA page. Completing MFA
applies only to the user who completed it, so a different user who signs in later in the same browser is asked for
their own code.

Each code works only once. A user who signs in again within the same 30-second window waits for their app to show the
next code.

## Incorrect Codes and Lockout

Curator locks code entry after too many incorrect codes. The limit and the lock length come from the
**User Throttle Limit** and **Activity Suspension Time** settings described in
[User Throttling](https://docs.curator.interworks.com/users_groups/user_security/user_throttling.md); by default, 5 incorrect codes lock code entry for 15
minutes. While the lock lasts, the MFA page shows "Too many incorrect codes. Try again in 15 minutes." and refuses
every code, including a correct one. Password sign-in is not affected.

The lock applies in two places: to the user's account, and to the browser session where the incorrect codes were
entered. To lift the account lock early, an administrator deletes the user's record under **Settings** >
**Security** > **Suspensions**. The user can then complete MFA from a new browser session, such as a private window.
The browser session that ran out of attempts stays locked until its own lock expires.

## Customizing the Suggested Authenticator App

The Curator-based MFA setup screen suggests a single authenticator app and provides per-platform download links.
The defaults are Google Authenticator, but any RFC 6238 TOTP authenticator app works with Curator's QR code -- if your
organization standardizes on a different app (for example, Microsoft Authenticator), you can change the suggestion in
**Settings** > **Security** > **Authentication** using the three fields shown when *Multi-factor Authentication* is
enabled:

* **MFA Authenticator App Name** -- The name shown in the download step (e.g. `Microsoft Authenticator`). Leave blank
  to use the default (`Google Authenticator`).
* **MFA Authenticator App Store URL (iOS)** -- The link followed when a user clicks the bold app name on the iOS tab.
  Must start with `https://`. Leave blank to use the default Google Authenticator App Store link.
* **MFA Authenticator App Store URL (Android)** -- The link followed when a user clicks the bold app name on the
  Android tab. Must start with `https://`. Leave blank to use the default Google Authenticator Play Store link.

Each field is independent -- you can change only the name, only the URLs, or any combination, and Curator falls back
to the Google Authenticator default for any field left blank.

## Backend Administrator MFA

Backend administrator accounts (the users who sign in at `/backend`) do not have a dedicated MFA toggle of their own.
Instead, MFA is applied to backend administrators by routing their sign-in through the frontend authentication form:

1. In **Settings** > **Curator** > **Portal Settings**, on the **General** tab, enable
   *Force Backend Users to Login Via Frontend Authentication Forms*.
2. Make sure every backend administrator has a frontend user with a matching username. Only backend usernames matching
   frontend users will be able to access Curator's administrative interface. See the
   [Backend Administrators](https://docs.curator.interworks.com/site_administration/backend_administrators/overview.md) documentation for the full setup.
3. Enable MFA as described in [Curator Setup](#curator-setup) above.

With both settings enabled, a backend administrator visiting `/backend` is redirected to the frontend login form,
completes the standard frontend MFA challenge via their authenticator app, and is then re-routed back to the backend.
A backend session that exists without a verified MFA challenge will be redirected to `/user/mfa` before any backend
page is served.

> [!NOTE]
>
> If your Curator instance authenticates users through SAML, MFA is handled by your identity provider rather than by
> Curator. Configure MFA policies (and any backend-administrator-specific MFA enforcement) at the IdP, and Curator will
> honor whatever assertions the IdP returns.

## Emergency Access (Break-Glass)

Curator does not ship a dedicated break-glass authentication feature -- there is no separate emergency login flow that
bypasses MFA, SAML, or *Force Backend Users to Login Via Frontend Authentication Forms*. If the frontend authentication
path is unavailable (for example, the SAML identity provider is down, or the MFA secret for an administrator is lost),
recovery is a two-step process: disable *Force Backend Users to Login Via Frontend Authentication Forms* through one of
the supported channels below, then sign in directly at `/backend` with a backend administrator's username and password.

Curator exposes two supported ways to toggle that setting without a working admin session:

### Option 1: Artisan CLI command (On-Prem only)

On On-Prem deployments where you have SSH access to the Curator server, run the
`portal:forcefrontendloginforbackend` artisan command from the application root:

```bash theme={null}
php artisan portal:forcefrontendloginforbackend 0 --force
```

The first argument accepts `0` (disable) or `1` (enable); `--force` skips the confirmation prompt. After the command
reports success, the administrator can sign in directly at `/backend` with their backend-account credentials. Once
access is restored, re-enable forced frontend login by running the same command with `1`:

```bash theme={null}
php artisan portal:forcefrontendloginforbackend 1 --force
```

### Option 2: API endpoint

If you have a Curator API key with access to the `portal.setForceFrontendLoginForBackend` permission, send a `POST`
request to `/api/v1/portal/setForceFrontendLoginForBackend` with `force_frontend_login_for_backend=0`:

```bash theme={null}
curl -X POST "https://your-curator-domain/api/v1/portal/setForceFrontendLoginForBackend" \
    -d "apikey=YOUR_API_KEY" \
    -d "force_frontend_login_for_backend=0"
```

The response confirms the new value. After signing in at `/backend`, re-enable forced frontend login by sending the
same request with `force_frontend_login_for_backend=1`.

> [!NOTE]
>
> Audit `storage/logs/system-YYYY-MM-DD.log` for the sign-in event whenever break-glass access is used, and re-enable
> *Force Backend Users to Login Via Frontend Authentication Forms* as soon as the underlying issue is resolved so that
> backend administrators continue to authenticate through the frontend MFA/SAML flow.

## Troubleshooting

When a user reports that their authenticator codes are rejected, the cause is almost always one of three things: they
are reading a code from a stale entry in their app, their device clock has drifted, or the portal's own clock has
drifted. Work through the steps below in order.

### The user has more than one Curator entry in their authenticator app

This is the most common cause, and the easiest to miss. Curator labels the QR code with the user's username and the
portal name, and neither changes when an administrator clears a user's MFA. The secret behind the entry does change,
so **every reset adds another entry to the authenticator app with a name identical to the previous one**. Nothing in
the app distinguishes the live entry from the dead ones, and a user reading a code from an old entry sees it rejected
every time.

Have the user delete **every** Curator entry from their authenticator app before re-enrolling, not just the one they
believe is current. After they scan the new QR code there should be exactly one Curator entry left, and the code they
read from it is the only one that will be accepted.

### The user's device clock has drifted

TOTP codes are derived from the current time, so a device whose clock is wrong generates codes that are correct for the
wrong moment. Ask the user to set their phone's date and time to update automatically, then try again.

> [!NOTE]
>
> Some authenticator apps used to expose a setting that corrected their internal clock independently of the device
> clock. Do not rely on finding one -- these options have been removed from several apps, including Google
> Authenticator. Setting the device itself to automatic time is the step that matters, and it works regardless of which
> authenticator app the user has.

### The portal's clock has drifted

Curator accepts a code from the current 30-second window and from one window on either side, so a code is valid for
roughly **30 seconds before and after** the moment it was generated. That tolerance is not configurable. It is
generous enough to absorb a user typing slowly, but not much more -- if the portal host's clock is off by more than
about half a minute, codes generated by perfectly accurate phones are rejected.

Suspect this when the symptoms do not fit a per-user problem:

* several users fail at once, rather than one;
* the failures survive repeated MFA resets, so the stored secret is clearly not the issue;
* and a user occasionally starts working again with nothing having been changed, which is what a clock sitting near
  the edge of the tolerance window looks like as it drifts back and forth across the boundary.

On an On-Prem deployment, check that the Curator server's time is synchronized against a reliable time source and
correct it if it has drifted. On InterWorks-hosted deployments, raise this with InterWorks support and quote the
pattern above, since host time synchronization is managed for you.

### What to collect before escalating

If the steps above do not resolve it, gather the following before contacting support. Each one rules out a cause that
would otherwise have to be guessed at:

* confirmation that only **one** Curator entry remains in the user's authenticator app;
* the exact time and time zone shown on the user's device at the moment they submit a code that is rejected;
* whether the failure affects one user or several, and whether it has ever cleared on its own;
* the username affected and the approximate time of the most recent failed attempt, so the attempt can be matched
  against `storage/logs/system-YYYY-MM-DD.log`.

> [!NOTE]
>
> An administrator clears a user's saved MFA at **Settings** > **Users** > **Frontend Users**, by opening the user and
> clicking **Remove Saved MFA**. The button appears only while *Multi-factor Authentication* is enabled in
> **Settings** > **Security** > **Authentication**, and requires the *Manage frontend users* permission. Clearing the
> secret prompts the user to enroll again with a fresh QR code at their next sign-in.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.