Single sign-on (OIDC)

Teams with central identity management can sign in through their own identity provider. Monsys speaks standard OpenID Connect (authorization code flow) and therefore works with Keycloak, Authentik, Microsoft Entra ID, Google Workspace, Okta and others. Configuration is per tenant: every organisation connects its own provider.

Password + TOTP always keeps working. SSO is additive, not a replacement: a broken IdP configuration can never lock you out.

Configuring (admin)

1. Settings → Team → Single sign-on (OIDC), click set up
2. First register a confidential client in your IdP with this redirect URL:

https://api.monsys.ai/api/v1/auth/sso/callback

3. Then fill in on the monsys side:
   • Issuer URL: your provider’s base URL, always https. Monsys validates it immediately through /.well-known/openid-configuration; an unreachable issuer is rejected on save.
   • Client ID and Client secret: from your IdP registration. The secret is stored but never shown again; leaving it empty on a later edit means “keep the existing secret”.
   • Allowed domains: the email domains (for example example.com) this provider covers, at most 20. Enabling requires at least one domain.
   • Just-in-time provisioning (optional): unknown users with an allowed domain are created automatically on their first SSO login, with the chosen default role (viewer, auditor or editor). With JIT off, only previously invited users can enter through SSO.
   • Button label (optional): your own text on the login button, for example “Sign in with Acme AD”.

How the login flows

1. The user enters their email address on the login page and clicks Sign in with SSO.
2. Monsys looks up the tenant configuration by email domain and redirects the browser to the IdP.
3. After successful authentication at the IdP, the user returns to monsys, which verifies the id_token against the provider’s keys.
4. Existing user: the session starts immediately. Unknown user: an account is only created with JIT enabled and an allowed domain.

The session is the same cookie session as password login (8 hours, HMAC-signed). If anything fails, the user lands back on the login page with a clear message and can always still sign in with password + TOTP.

Security

• State parameter: HMAC-signed by the hub, valid for 10 minutes. Forged or expired callbacks are rejected.
• Nonce: bound to the session request and checked in the id_token (replay protection).
• id_token verification: signature, audience and issuer are checked against the provider’s discovery metadata.
• JIT boundaries: automatic creation only happens for explicitly allowed domains, never wider.
• Sovereignty: the whole flow runs between your browser, your IdP and the monsys hub in the EU. No third party sits in between.

Frequently asked questions

Can I disable password login for my tenant? Not yet. Deliberately so: as long as an IdP outage could lock out your whole team, we keep password + TOTP as the safety net.

Which role does a JIT user get? The default role chosen in the configuration. An admin can raise that role per user afterwards under Settings → Team.

Multiple email domains? Add them all to the allowed domains, up to 20 per tenant.