> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/settings/ui-settings/security/two-factor-authentication.md).

# Two-factor authentication

Two-factor authentication (2FA) adds a verification step to a CrossWatch account.

After authentication, the user enters a six-digit code from an authenticator app.

{% hint style="info" %}
2FA belongs to a CrossWatch account. It does not change its User Profile or Access Mode.
{% endhint %}

### How it works

CrossWatch uses standard time-based one-time passwords (TOTP).

```
Username and password
        ↓
Six-digit authenticator code
        ↓
CrossWatch session
```

2FA verifies the person signing in.

It does not change what that account can access.

```
User Account = who signs in
2FA = additional identity verification
User Profile = delegated resource scope
Access Mode = Read Only or Full Access
```

Most standard TOTP apps work, including 2FAS, Aegis, Google Authenticator, Microsoft Authenticator, Bitwarden, 1Password, and Authy.

Authenticator entries use `CrossWatch:<username>`.

Codes have six digits and change every 30 seconds.

### Who manages 2FA

The CrossWatch administrator manages 2FA for the administrator and managed-user accounts.

Managed users do not configure global authentication settings themselves.

For managed-user delegation, see [Managed users](/crosswatch/settings/connections/managed-users.md).

### Enable 2FA

#### Administrator account

1. Sign in as the administrator.
2. Open **Settings → UI Settings → Security**.
3. Open **Two-factor authentication**.
4. Click **Set up 2FA**.
5. Add the generated secret to an authenticator app.
6. Enter its current six-digit code.

CrossWatch enables 2FA only after it verifies the code.

#### Managed-user account

1. Sign in as the administrator.
2. Open **Settings → UI Settings → Security → User Manager**.
3. Select the managed user.
4. Click **Set up 2FA**.
5. Add the generated secret to that user's authenticator app.
6. Enter the current six-digit code to confirm setup.

The user's profile and access mode stay unchanged.

### Sign in with 2FA

For local sign-in, enter the username and password first.

CrossWatch then requests a code when the account has 2FA enabled.

```
Username and password
        ↓
2FA enabled?
        ↓
Current six-digit code
        ↓
CrossWatch session
```

Invalid codes reject the sign-in. Repeated failed attempts can temporarily pause new login attempts.

### OIDC and 2FA

CrossWatch can enforce 2FA after a successful OIDC sign-in.

```
Sign in with OIDC
        ↓
Identity provider authentication
        ↓
Linked CrossWatch account
        ↓
CrossWatch 2FA, when enabled
        ↓
CrossWatch session
```

Your identity provider and CrossWatch can each require their own MFA step.

See [OIDC sign-in](/crosswatch/settings/ui-settings/security/oidc-sign-in.md) for account linking and provider configuration.

### Disable 2FA

The administrator can disable 2FA for an account.

Use **Disable 2FA** for the administrator account. For managed users, open the account in **User Manager**.

Disabling 2FA removes only the TOTP requirement.

It does not remove the account, User Profile, Access Mode, OIDC link, provider instances, or synchronization resources.

Security changes can invalidate existing sessions for the affected account.

### Troubleshooting

* **Code rejected during setup** — use the correct secret and current six-digit code.
* **A previously valid code fails** — wait for a new code and check the authenticator device time.
* **User signed out after a 2FA change** — session invalidation is expected after security changes.
* **OIDC asks for a code** — CrossWatch 2FA is enabled for the linked account.
* **Authenticator device lost** — an administrator must disable and reconfigure 2FA for that account.

{% hint style="warning" %}
Treat the setup secret like a password. Anyone with it can generate valid codes.
{% endhint %}

### Security details

CrossWatch uses these standard TOTP settings:

* **Issuer:** `CrossWatch`
* **Digits:** `6`
* **Period:** `30 seconds`
* **Algorithm:** `SHA1`

CrossWatch accepts a small amount of clock drift. Keep automatic time synchronization enabled on authenticator devices.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://wiki.crosswatch.app/crosswatch/settings/ui-settings/security/two-factor-authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.