How do I set up SSO/OIDC for a tenant?

Requires Pro

Short answer

Under Administration → SSO, create a provider configuration for your tenant: display name, the IdP’s discovery URL, client ID, and client secret — then enable it. In the IdP, register Notory as an OIDC client with the redirect URI https://<your-instance>/api/v1/auth/sso/callback. Optionally, Notory can automatically onboard new users via JIT provisioning and derive their role from IdP groups. SSO providers always apply per tenant.

Requirements

From the IdP, you’ll need: the discovery URL (e.g. https://login.microsoftonline.com/<tenant>/v2.0/.well-known/openid-configuration), client ID, and client secret. The IdP must mark email addresses as verified (email_verified).

Open the SSO section. Administration → SSO. The description reminds you: “Configure identity providers per tenant. Full login requires a reachable IdP.” Click Create provider.

Screenshot pending admin-sso-01 SSO management with the list of the tenant's identity providers

SSO management: identity providers are configured per tenant.
Configure the provider. Fill in:
- Display name — later appears on the login button (“Sign in with …”).
- Protocol — oidc (default; the full login flow is implemented for OIDC, SAML fields are prepared).
- Discovery URL, Client ID, Client Secret — from your IdP.
- Scopes — leave empty for the default openid email profile.
- Default role — role for automatically created users (default: Viewer).
- JIT provisioning — when enabled, Notory automatically creates unknown users in the tenant at their first SSO login.
- Group claim (default groups) and group-to-role mapping — e.g. it-admins → admin, helpdesk → technician; optionally sync role on every login.
Screenshot pending admin-sso-02 Form for an OIDC provider with discovery URL, client ID, client secret, JIT and group mapping

The OIDC configuration: discovery URL, client credentials, JIT provisioning and group mapping.
Register the redirect URI in the IdP. In your IdP, register the callback address https://<your-instance>/api/v1/auth/sso/callback as an allowed redirect URI for the OIDC client.
Enable and test. Set the provider to enabled. Open the login screen in a private window and enter the email of an account in this tenant — the “Sign in with …” button appears automatically (e-mail discovery).

Provider configurations are regular CRUD resources under /api/v1/sso/configs (tenant-bound):

curl -X POST https://demo.notory.io/api/v1/sso/configs \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_name": "Firmen-Login (Entra ID)",
    "protocol": "oidc",
    "enabled": true,
    "discovery_url": "https://login.microsoftonline.com/<tenant>/v2.0/.well-known/openid-configuration",
    "client_id": "0f7e1c2d-…",
    "client_secret": "geheim",
    "scopes": "openid email profile",
    "default_role": "viewer",
    "allow_jit": true,
    "group_claim": "groups",
    "group_role_map": { "it-admins": "admin", "helpdesk": "technician" },
    "sync_role_on_login": false
  }'

The response (201 Created) contains the configuration — without the client_secret (it’s never returned). Further endpoints: GET /api/v1/sso/configs (list), PUT /api/v1/sso/configs/{id} (update), DELETE /api/v1/sso/configs/{id} (delete, administrator only), and GET /api/v1/sso/providers (the tenant’s enabled providers).

Possible errors: 403 (the sso feature isn’t licensed — “The Single sign-on (SSO) module is not included in the ’…’ plan”), 501 (login start, when discovery_url or client_id are missing), 502 (the discovery document couldn’t be retrieved).

What happens behind the scenes?

The login flow (OIDC Authorization Code + PKCE). Clicking “Sign in with …” redirects Notory to the IdP — with PKCE (S256), state, and nonce; the state is kept as a signed, 10-minute cookie (it_sso). After returning at the callback, Notory exchanges the code for tokens and cryptographically validates the id_token against the IdP’s JWKS (signature, iss, aud, expiry, nonce).
Only verified e-mails. Only an email with email_verified: true is accepted — otherwise the login aborts.
Account matching by e-mail. If an account with this email exists, it’s signed in — but only if it belongs to the provider’s tenant (tenant isolation). If none exists: with JIT, Notory creates the user in the provider’s tenant (default role or group mapping, random unusable password — the account is SSO-only); without JIT, “No account exists for this e-mail. Ask an administrator to invite you.” is shown.
Roles from groups. From the group claim, the highest-ranking matching role is determined via the mapping table. With “sync role on every login”, Notory pulls in role changes from the IdP on every sign-in.
Deactivated accounts. An inactive account is only reactivated automatically during SSO login if JIT provisioning is enabled; otherwise it stays locked.
2FA. During SSO login, Notory asks for no local authenticator code — multi-factor is handled by the IdP. However, enforced 2FA setup (instance/tenant) still applies: without a set-up device, the app remains locked until setup is complete.
Secret handling. The client_secret is stored, but never returned in any API response.