SSO and SCIM

Kutrion supports enterprise identity so an organization can let its own identity provider (IdP) own who signs in and what role they get. Two single sign-on protocols are supported, plus SCIM 2.0 for automated provisioning. All of it is per-org: a provider is configured for one organization and only ever provisions into that org.

OpenID Connect (OIDC)

The OIDC client uses discovery to read the provider’s endpoints and JWKS, then runs the Authorization Code flow with PKCE. On first login from a configured provider it does JIT provisioning: a new user is created in that provider’s org and linked to their IdP identity, subject to the verified-domain rules below. The returned id_token is verified against the provider’s JWKS, and iss, aud, and exp are checked, so a misconfigured provider fails loudly rather than mid-flow.

SAML 2.0

The SAML path is SP-initiated and uses the HTTP-POST binding for the assertion. The service-provider entityID and Assertion Consumer Service (ACS) are served at the API origin. The implementation owns the security-critical validation — XML signature validation against the IdP certificate, signature-wrapping defense, and audience and clock checks — and normalizes a validated assertion onto the same identity claims the OIDC path uses, so JIT provisioning and role mapping are shared between the two protocols.

Confirming an app sign-in with your IdP

A member whose account has no password, passkey or authenticator app confirms a “Sign in with Kutrion” approval by signing in to the organization’s OIDC or SAML provider again. Kutrion asks for a fresh sign-in (OIDC prompt=login and max_age=0, SAML ForceAuthn) and then checks the time the IdP says the user authenticated: the OIDC auth_time claim, or the SAML AuthnInstant. A response that carries neither always fails closed, so that provider cannot be used for this confirmation.

• Microsoft Entra ID sends auth_time only as an optional claim. Add auth_time to the ID token under Token configuration → Add optional claim on the app registration.
• Social sign-in providers, such as Google and GitHub, are never used to confirm an approval. Those members add a passkey or an authenticator app instead.
• The organization needs the SSO feature on its plan, as for sign-in.

Verified domains

An organization’s IdP can assert any email address it likes, so it speaks only for email domains the organization has verified. An org admin adds the domain on the web app’s Organization page and publishes the DNS TXT record Kutrion shows, at _kutrion.<domain>; the domain counts once that record is checked. A domain that is only added, not verified, does not count, and neither does a subdomain of a verified one: eu.example.com needs its own verification.

With that in place, enterprise SSO (OIDC and SAML alike) follows these rules:

• New user (JIT). Created in the provider’s organization only when the asserted email is on a domain that organization verified. Otherwise sign-in is refused with email_domain_unverified.
• Existing account with the same email. Linked to the IdP identity only when the account is already in the provider’s organization, its email is on a verified domain, and Kutrion has a record of the account’s own email address being verified. That record is written when the holder enters a code Kutrion emailed to the address (at signup, when changing the address, or by verifying the current address with POST /auth/email/verify and /auth/email/verify/confirm), or when a social provider that confirms the address signs the account in. Accounts created before this rule have no record until they verify once. An account in another organization is never pulled across (email_belongs_to_other_org), and an account with no record is refused with account_email_unverified.
• Returning user. An identity keeps signing in only while its user is still a member of the provider’s organization and that organization still has the user’s own email domain verified. A user who left the organization is refused with identity_left_org; one whose domain is no longer verified is refused with email_domain_unverified.
• Removing a verified domain signs out every member of the organization whose email address is on it: their current sessions end and their devices must sign in again. Members who can only sign in through SSO get back in through account recovery started by an org admin; password reset does not apply to an account that never had a password.

Mapping IdP groups to teams and roles

Both protocols can carry the user’s IdP group membership. A provider can map those groups to Kutrion teams and roles: when a user signs in, their groups are matched against the provider’s role map and the highest-privilege matching role is applied. This works with the group claims emitted by providers such as Okta and Azure AD, so org structure in the IdP drives team membership and role in Kutrion without per-user setup.

SCIM 2.0 provisioning

For full lifecycle management, Kutrion exposes a SCIM 2.0 endpoint — an Enterprise capability. An IdP (for example Okta, Azure AD, or OneLogin) authenticates with a SCIM-scoped API token and can:

• Create and update users in the org.
• Deactivate users — the point of SCIM — so a departure in the IdP deprovisions the Kutrion account.
• Sync groups to teams, keeping team membership in step with the IdP.

A SCIM create is accepted only for a userName on one of the organization’s verified domains; any other address is refused with a SCIM 400 invalidValue error. Users provisioned before this rule are not re-checked. An address that already has an account, in this organization or any other, is refused with the same 409 uniqueness error either way.

SCIM users sign in via SSO; they are created without a usable password, and their email address is recorded as verified because the organization proved it owns the domain. See API tokens and SCIM for issuing the token and the endpoint details.

Social login is not enterprise SSO

Social login — Apple, Google, and Microsoft — is for individual free-tier signups, not for org identity. A social login makes the person an org-of-one and is never used as an organization’s IdP; only the per-org OIDC and SAML providers above provision into an org. Keep the two distinct: social login is consumer onboarding, enterprise SSO is tenant identity.

A social login creates an account, or links into an existing account with the same email, only when the provider asserts that the email address is verified. A provider that says it is unverified, or says nothing, is refused (email_unverified for a new account, email_exists_unverified for an existing one); the person can sign up with the email code instead.

Who can configure a provider

An organization’s own OIDC and SAML providers are managed by that organization’s admins. The shared social providers offered to every individual are instance-wide configuration, and only the emails listed in the SSO_ADMIN_EMAILS environment variable may manage them.

# comma-separated allowlist of instance admins permitted to configure the shared social providers
[email protected],[email protected]

See Auth configuration for the surrounding auth settings.

Where to go next

• Issue a SCIM token and review the provisioning endpoints in API tokens and SCIM.
• Configure the auth environment in Auth configuration.