Two-factor authentication

Protect CrossWatch accounts with six-digit TOTP authenticator codes.

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.

2FA belongs to a CrossWatch account. It does not change its User Profile or Access Mode.

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.

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 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.

Treat the setup secret like a password. Anyone with it can generate valid codes.

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.