Skip to the page
Get started

Docs · Administration

Two-factor authentication and single sign-on

A code from an authenticator app on top of a password, making it compulsory, and signing in through your own identity provider.

#Two-factor authentication

Everybody can turn it on for their own account under Settings → Account → Two-factor authentication. Once it is on, Mosaic asks for a six-digit code from an authenticator app after the password. Somebody who learns the password still cannot sign in.

Any authenticator app works: 1Password, Google Authenticator, Microsoft Authenticator, Authy and the rest all speak the same standard (TOTP, RFC 6238).

#Setting it up

  1. Press Set up.
  2. Scan the QR code with the app, or type the key in by hand.
  3. Type the code the app shows and press Turn on.
  4. Save the ten recovery codes. Each one signs you in once without your phone. They are shown only this once, so copy or download them and keep them somewhere other than the computer you sign in from.

Turning it on signs you out everywhere else, because those sessions were opened without the second factor.

#Signing in

After the password, Mosaic asks for the code. A recovery code works in the same box, once. A sign-in link from an email asks for the code too: the link proves the mailbox, not the phone.

Each code can be used once. A code somebody watched you type cannot be reused within its 30 seconds.

#Turning it off

Turn off asks for a current code or a recovery code. A stolen session on its own cannot turn it off.

#Lost phone and lost recovery codes

An admin or owner of a workspace you belong to can reset it from People, with the shield icon beside your name. The same rules apply as for a password reset: nobody can do it for themselves there, and nobody can do it for somebody with a higher role. Your sessions end everywhere, and you set it up again on your next sign-in.

#Making it compulsory

On a self-hosted installation, start Mosaic with:

MOSAIC_REQUIRE_MFA=1

Anybody without two-factor authentication is then shown the setup screen after signing in, and nothing else works until they finish it. The API refuses every other request from their session. Turning it off is refused while the setting is on.

Leave this off if everybody signs in through single sign-on, and require multi-factor authentication at your identity provider instead (see below).

#Single sign-on (OpenID Connect)

Mosaic can sign people in through your own identity provider: Microsoft Entra ID, Okta, Google Workspace, Keycloak, or anything else that publishes an OpenID Connect discovery document. It is part of the licences that include single sign-on.

Single sign-on signs people in. It does not create accounts. Whether an address has an account here is still decided in Mosaic: add people in People as usual. Somebody your provider knows but Mosaic does not is told to ask an administrator to invite them.

#Setting it up

Owners set it up under Tenancy → Single sign-on. Where the licence names the installation's owner, only that person can.

  1. At your identity provider, register a web application:
    • Redirect URI: the one shown on the screen, which is https://<your Mosaic address>/api/auth/sso/callback. Mosaic takes the address from MOSAIC_PUBLIC_URL, so set that first; the screen warns you when it is missing.
    • Scopes: openid email profile
    • Make sure the ID token carries an email claim. In Entra ID, add email as an optional claim on the app registration.
  2. On the screen, fill in the Issuer URL, Client ID and Client secret, and a Button label such as Microsoft. Press Save.

The issuer is the URL that /.well-known/openid-configuration hangs off. For Entra ID it is https://login.microsoftonline.com/<tenant id>/v2.0. For Okta it is https://<your domain>.okta.com, or your custom authorization server's URL. Mosaic reads that document when you save, and refuses an issuer it cannot read.

The sign-in page shows Continue with Microsoft above the password fields straight away. Sign out and use it once: the screen then shows who tested it and when.

Saving asks for your password if you signed in more than ten minutes ago, or asks you to sign in again if you use two-factor authentication. Whoever controls the provider can vouch for any address, so a change here is treated like deleting an account. The client secret is stored encrypted and never shown again; leave the field blank to keep it.

#Turning it off for a while

The On switch at the top of Identity provider pauses single sign-on without forgetting it. While it is off, the sign-in page offers passwords only, and password sign-in works even if Only single sign-on was on. Turn it back on and the provider returns with the same settings, and passwords stay allowed until you refuse them again. Use it when the provider is down or while you change its app registration.

#Only single sign-on

Turn on Refuse password sign-in under Only single sign-on. The password form disappears and password sign-in is refused.

The switch stays off until somebody has signed in through the provider with the saved settings, so a mistake in the issuer cannot lock everybody out. Changing the issuer or the client ID turns it off again until the next successful sign-in. If the licence no longer includes single sign-on, the settings are ignored and passwords work again.

#Setting it up in the environment instead

If you manage Mosaic's configuration in a deployment tool or a vault, start it with these instead. They take precedence, and the screen then shows the provider read-only.

MOSAIC_PUBLIC_URL=https://<your Mosaic address>
MOSAIC_OIDC_ISSUER=<issuer URL>
MOSAIC_OIDC_CLIENT_ID=<client id>
MOSAIC_OIDC_CLIENT_SECRET=<client secret>
MOSAIC_OIDC_NAME=Microsoft
MOSAIC_SSO_ONLY=1

MOSAIC_SSO_ONLY=1 is optional and refuses password sign-in. Keep at least one owner who can sign in through the provider before you set it.

#What Mosaic checks

  • The authorization code flow with PKCE. The state is tied to the browser that started the sign-in, and a nonce is checked in the ID token.
  • The ID token's signature against your provider's published keys (RS256/384/512, ES256/384), its issuer, its audience and its expiry.
  • The email claim, and only that claim. An address the provider marks as unverified is refused.

When somebody signs in through the provider, Mosaic does not also ask for its own two-factor code. Your provider's policy covers that sign-in, including its multi-factor authentication and conditional access, so enforce MFA there.

#In the audit trail

Saving or removing the provider is recorded, with the issuer and client ID. Every single sign-on is recorded as a sign-in with Single sign-on through ‹name›. Every refusal is recorded as a failed sign-in with the reason, including sign-ins by people who have no account. Turning two-factor authentication on or off, using a recovery code and an admin's reset are recorded too.