Guides
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 the sign-in experience and trust breadth. 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 | Any existing member with an exact verified email controlled by this trusted connection can be linked |
false | Your app starts the organization's SAML connection explicitly; email-first discovery does not force SSO | First link is allowed only for an active SCIM record whose current primary email exactly matches the signed assertion in the same organization |
The first row is the most seamless common enterprise setup when the IdP controls the organization's verified email domain. The second row is the narrower linking 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 links from the signed SAML email attribute. An unsigned login_hint, stale alias, SCIM record in another organization, disabled SCIM connection, inactive membership, or deactivated/deleted SCIM link cannot authorize the narrow SCIM-provenance link.
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 differs from current SCIM primary email | Denied when no existing SAML subject link exists |
| 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 |
| SCIM user is active and same-org email matches | 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:
Attempt 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 signed email must match the current active SCIM record. A stale email retained elsewhere on the user does not satisfy the narrow provenance rule.
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 |