Skip to the page
DataMosaic

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.

#Single sign-on (SAML 2.0)

Use SAML where your identity provider does not offer OpenID Connect, such as ADFS. Everything above about single sign-on applies: it signs people in and does not create accounts, On pauses it, and Only single sign-on stays shut until one sign-in has worked.

#Setting it up

Under Tenancy → Single sign-on, set Protocol to SAML 2.0.

  1. At your identity provider, add Mosaic as a SAML application with the two values the screen shows:
    • Mosaic's entity ID (also called the identifier or audience): https://<your Mosaic address>/api/auth/saml/metadata. Mosaic's own metadata is served at that address.
    • Reply URL (the assertion consumer service URL): https://<your Mosaic address>/api/auth/saml/acs.
  2. Have the provider send the person's email address, either as the name identifier in email format or as an attribute named email. Have it sign the assertion.
  3. On the screen, paste the provider's metadata address and press Read. Mosaic fills in the Sign-in address, the Provider entity ID and the Signing certificate for you to check. You can also type the three in by hand. Press Save.

When the provider rotates its certificate, paste the old and the new one together until the change is done. A new certificate is an untested provider, so Only single sign-on turns off until the next sign-in works.

#In the environment instead

MOSAIC_PUBLIC_URL=https://<your Mosaic address>
MOSAIC_SAML_ENTRY_POINT=<the provider's sign-in address>
MOSAIC_SAML_IDP_ISSUER=<the provider's entity ID>
MOSAIC_SAML_CERT=<its signing certificate, PEM or the base64 alone>
MOSAIC_SAML_NAME=ADFS

If the OpenID Connect variables are set as well, they win.

#What Mosaic checks

  • The assertion's signature, against the certificate you saved. An unsigned assertion, or one changed after it was signed, is refused.
  • That it is addressed to this installation and comes from the provider you saved.
  • That it answers a sign-in this installation started in the last ten minutes, in the same browser, and has not been used before. A sign-in started at the provider's own portal (IdP-initiated) is refused; start from Mosaic's sign-in page.
  • The email attribute, or the name identifier only when the provider says it is an email address.

#Provisioning (SCIM)

Single sign-on does not tell Mosaic when somebody leaves. With provisioning on, your identity provider creates a Mosaic account for each person you assign to the application and disables it when you take them away. A disabled account is signed out at once.

Under Tenancy → Single sign-on → Provisioning (SCIM):

  1. Choose the role new accounts get. They join the workspace you are in when you create the token; change a person's role afterwards under People.
  2. Press Create token. Copy the token straight away: it is shown once.
  3. At your provider, give the SCIM endpoint shown on the screen (https://<your Mosaic address>/api/scim/v2) as the tenant URL and the token as the secret token.

What the provider can do:

  • Create an account. It has no password, so the person signs in through single sign-on.
  • Rename an account, disable it and enable it again.
  • Read the accounts, to match its list against Mosaic's.

What it cannot do:

  • Change an account's email address. Disable the account and create one for the new address.
  • Grant a role other than the one you chose, or make an owner.
  • Disable the installation's owner, so a mistake at the provider cannot lock everybody out.
  • Delete anything. Removing a person at the provider disables their account; their checks, runs and audit trail stay. Delete an account under People if you need to.

Replace token makes a new token and stops the old one at once. Turn off stops provisioning; accounts the provider made are left as they are. Every account the provider creates, renames, disables or enables is recorded in the audit trail as done by the identity provider.

Provisioning is part of the licences that include single sign-on, and is for self-hosted installations.