Pair SCIM provisioning with SAML sign-in
Make SCIM authoritative for organization access while SAML authenticates only active, already-provisioned members.
The directory assignment is the source of organization access:
This avoids two competing provisioning paths. SAML JIT does not create a membership that the SCIM assignment never authorized.
Map one IdP-owned value consistently:
| IdP value | Destination |
|---|---|
| Stable work email | SCIM userName |
| The same work email | SCIM emails[type eq "work"].value |
| The same work email | The signed SAML attribute configured as the connection's email field |
| Stable provider object ID | SCIM externalId |
For Microsoft Entra, userPrincipalName is the simplest default when it is the tenant's stable routable work address. Use mail only when it is guaranteed to be populated, unique, and stable. For Okta, use the app username/work-email value that the enterprise controls.
SqlOS normalizes the email for matching, but it keeps externalId case-exact. Do not let a display alias, personal email, browser login hint, or mutable nickname become the join key.
Create or update the SAML connection with automatic provisioning disabled:
var draft = await adminService.CreateSsoConnectionDraftAsync(
new SqlOSCreateSsoConnectionDraftRequest(
OrganizationId: organizationId,
DisplayName: "Acme enterprise SSO",
PrimaryDomain: "acme.com",
AutoProvisionUsers: false,
AutoLinkByEmail: true));AutoProvisionUsers: false is the non-negotiable setting for a SCIM-authoritative population. It prevents SAML from creating a new user or organization membership merely because the assertion is valid.
AutoLinkByEmail controls home realm discovery, not proof of global identity. Choose deliberately:
| Policy | Experience | Boundary |
|---|---|---|
true / Require SSO for existing members | Email-first home realm discovery routes an existing member to the organization's SAML connection | First subject link still requires the organization to own the asserted email domain |
false | Your app starts the organization's SAML connection explicitly; email-first discovery does not force SSO | Membership or SCIM assignment can authorize org access, but they cannot substitute for domain ownership on first link |
The first row is the most seamless common enterprise setup when the IdP controls a verified organization email domain. The second row is the narrower routing policy when your application already knows which organization/connection to start.
In the delegated setup portal, Allow JIT provisioning from SSO maps to AutoProvisionUsers; keep it off. Require SSO for existing members maps to AutoLinkByEmail.
SqlOS users are host-global. A SAML connection may authenticate an already-bound subject, and it may first-link an existing user only when the connection's organization owns that exact email domain through an active verified domain or operator-managed PrimaryDomain. An unsigned login_hint, SCIM record, or organization membership cannot authorize takeover of an unbound global user. SCIM and SAML JIT can create or re-point a verified email only inside the organization's active verified domains, a directory stops owning a person once they have an independent login or another organization's membership, and only the owning link can change a person's global active state. See Email and lifecycle ownership.
For the test user:
On first successful sign-in, SqlOS binds the signed SAML issuer and subject to the already-provisioned user. It does not create a second user or a second membership.
On later sign-ins, issuer and subject are the stable identity key. Email remains useful for profile display and controlled migration but is not repeatedly used to choose a different account.
Check all four layers:
| Layer | Expected result |
|---|---|
| Identity provider | SCIM user succeeded; SAML assertion contains the intended subject and email |
| AuthServer user | One user and one active membership in the organization |
| External identities | One SCIM link and one SAML issuer/subject link point to that user |
| OAuth result | The application receives a normal code/token for the intended user and organization |
Also confirm that a second SAML sign-in reuses the same external identity and does not perform another email-based account selection.
Before rollout, run this matrix with test identities:
| Scenario | Expected result |
|---|---|
| SAML sign-in before SCIM provisioning, JIT off | Denied; no user or membership is created |
| Signed SAML email is an existing global user, but the organization does not own that domain | Denied; no membership, subject binding, or authorization artifact is created |
| Only the browser login hint matches | Denied |
| SCIM record exists only in another organization | Denied |
| SCIM connection or membership is inactive | Denied when no active linked identity can sign in |
| Organization owns the asserted domain, the user is already an active member, and JIT is off | First SAML subject link succeeds |
These checks are especially important when two customers can have people with the same normalized email or when a consultant belongs to several organizations.
Unassign or deactivate the test user through the IdP's provisioning control. SqlOS soft-deprovisions the organization boundary:
scim_deprovisioned; reactivation does not restore them. A person with another active membership, a password, an authenticator, a phone number, or a social or other organization's SAML identity stays globally activeAttempt SAML sign-in again. The IdP may still authenticate the person, but SqlOS must not issue access for the deprovisioned organization.
Then reassign or reactivate the user through SCIM. Confirm the existing membership and SCIM link reactivate without duplication, followed by a successful SAML sign-in.
When the canonical work email changes:
If the SAML subject is unchanged and already linked, SqlOS resolves that subject first. If this is the first sign-in, the connection's organization must own the asserted email domain. A SCIM record or stale email alias is not enough.
Use this production checklist:
| Symptom | Cause to check first | Resolution |
|---|---|---|
| First SAML sign-in says no user can be resolved | User was not provisioned, is inactive, or the signed email differs | Provision first and compare the current SCIM primary email with the signed SAML attribute |
| Email-first sign-in does not redirect to SSO | AutoLinkByEmail / Require SSO for existing members is off | Start the organization SAML connection explicitly or enable the broader trusted-domain policy |
| SAML sign-in creates an unexpected membership | JIT provisioning is on | Disable AutoProvisionUsers / Allow JIT provisioning from SSO and remove unintended access deliberately |
| Deactivated user still has some access | The access comes from another organization, manual grant, non-SCIM group, or another auth path | Inspect memberships and the FGA explanation; SCIM removes only state it owns for this organization |
| Email change breaks first sign-in | SAML changed before SCIM, or the two mappings use different source fields | Reconcile the directory mappings and push SCIM before retrying the first link |