SCIM directory sync

This guide follows the common setup path first. A developer enables SCIM once, creates one connection for the customer organization, and gives the customer's IT administrator two values to paste into their identity provider.

The five-minute setup#

1. Enable SCIM#

SCIM is off by default. A provider must be able to call an absolute public HTTPS URL, so configure the externally reachable origin at the same time:

var publicOrigin = builder.Configuration["SqlOS:PublicOrigin"]
    ?? throw new InvalidOperationException("SqlOS:PublicOrigin is required for SCIM.");
 
builder.AddSqlOS<AppDbContext>(options =>
{
    options.AuthServer.PublicOrigin = publicOrigin;
    options.AuthServer.Issuer = $"{publicOrigin.TrimEnd('/')}/sqlos/auth";
    options.AuthServer.EnableScim = true;
});

PublicOrigin must be an absolute HTTPS origin only, such as https://identity.example.com, with no path, query, or fragment. The default service-provider path is /sqlos/scim/v2, so the resulting Base URL is https://identity.example.com/sqlos/scim/v2. Set ScimBasePath only when the host application needs a different public path.

If PublicOrigin is omitted, SqlOS can return only a relative path. That is useful for same-origin local curl requests but cannot be pasted into Entra or Okta.

Local Entra or Okta testing with Aspire Dev Tunnels#

Aspire Dev Tunnels can give a local SqlOS host a temporary TLS-terminated public endpoint. On a current Aspire AppHost, add the integration:

aspire add devtunnels

Then expose the SqlOS-enabled project from the AppHost:

var app = builder.AddProject<Projects.App>("app");
 
builder.AddDevTunnel("sqlos-scim")
    .WithReference(app)
    .WithAnonymousAccess();

Run the AppHost and copy the tunnel's public https://...devtunnels.ms endpoint from the Aspire dashboard. Configure that exact origin as SqlOS:PublicOrigin, keep Issuer at {PublicOrigin}/sqlos/auth, and restart the host before creating the connection. Use the resulting {PublicOrigin}/sqlos/scim/v2 value as the provider's Base or Tenant URL.

2. Create the organization's connection#

Open /sqlos/admin/auth/, select the organization, and open SCIM. Create an enabled connection. If you plan to map directory groups to roles, set its grant boundary to the organization's root FGA resource ID; mapped grants can only target that resource or its descendants. You can also set the boundary later.

The create action returns:

• the SCIM Base URL
• the Users and Groups URLs
• a new bearer token, shown in plaintext only once

Copy the token before leaving the result. SqlOS stores its hash, not the plaintext value, so it cannot show the token again.

The Base URL does not need an organization ID. The bearer token identifies both the connection and its organization, which keeps provider setup simple and prevents a client from choosing another tenant in its request.

3. Paste the values into the identity provider#

For Okta, enable API integration, paste the Base URL and token, test the credentials, then enable Create Users, Update User Attributes, Deactivate Users, and group push as needed.

For Microsoft Entra, paste the Base URL into Tenant URL, paste the bearer token into Secret Token, test the connection, and start with a small assigned user or group before enabling the full provisioning scope.

Continue with the provider-specific setup after the connection test:

• Set up SCIM with Microsoft Entra ID — attribute mappings, assigned scope, on-demand provisioning, groups, and the recurring job
• Set up SCIM with Okta — app integration, outbound lifecycle switches, assignments, and Group Push

4. Provision one user, then one group#

Start with a single test user. Confirm that the IdP can query, create, update, deactivate, and reactivate that user. Then push one small group and verify member add and remove before assigning the whole directory.

SqlOS supports the provider behaviors needed for this flow:

Other filter operators such as co, sw, pr, and, and or are not accepted. Unsupported filters return a SCIM invalidFilter error instead of being silently ignored.

SqlOS bounds one PATCH document to 100 operations and one Group resource to 10,000 distinct members. An oversized request fails atomically with 413 and scimType: "tooMany"; partition a larger directory group into smaller application-specific groups rather than retrying the same payload.

5. Verify the result#

Check these surfaces after the first sync:

1. Auth Server > Organizations > Users shows the user and active organization membership.
2. Fine-Grained Auth > User Groups shows the mirrored group and its members.
3. The organization's SCIM tab shows applied sync events, mapping reconciliation failures, and the token's last-used time.
4. Audit Logs contains SCIM user, group, membership, and managed-grant changes. Administrative mapping changes appear as AuthServer admin events.
5. The access tester explains any access inherited through a mapped directory group.

You can also validate discovery and lookup without changing data:

export SCIM_BASE_URL="https://app.example.com/sqlos/scim/v2"
export SCIM_TOKEN="paste-the-token-shown-by-sqlos"
 
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Accept: application/scim+json" \
  "$SCIM_BASE_URL/ServiceProviderConfig"
 
curl --fail-with-body --silent --show-error --get \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Accept: application/scim+json" \
  --data-urlencode 'filter=userName eq "ada@example.com"' \
  "$SCIM_BASE_URL/Users"

Pair SCIM provisioning with SAML sign-in#

For a production rollout, follow the complete SCIM plus SAML access-lifecycle guide. The short version is that SCIM decides who belongs to the organization, SAML authenticates those already-provisioned people, and SAML JIT provisioning stays off.

The most predictable enterprise setup gives each protocol one job: SCIM decides who has organization access, while SAML authenticates those already-provisioned people. Use one stable work-email source in the IdP for every identity field that SqlOS links:

Use user.mail instead only when that tenant guarantees it is populated and stable. The important rule is that the SCIM primary email and SAML email claim normalize to the same address.

Create the SAML connection with linking enabled and JIT provisioning disabled:

var draft = await adminService.CreateSsoConnectionDraftAsync(
    new SqlOSCreateSsoConnectionDraftRequest(
        OrganizationId: organizationId,
        DisplayName: "Acme Entra SSO",
        PrimaryDomain: "acme.com",
        AutoProvisionUsers: false,
        AutoLinkByEmail: true));

In the dashboard or delegated SSO portal, the equivalent policy is Require SSO for existing members = on and Allow JIT provisioning = off. Provision the test user through SCIM before attempting the first SAML sign-in. SqlOS can then bind the IdP subject to that existing member when the organization owns the asserted email domain; it does not treat SCIM or membership as proof of global identity.

That setting gives the smoothest email-first routing for a trusted organization domain. For a narrower routing policy, leave AutoLinkByEmail / Require SSO for existing members off and have the application start the organization's SAML connection explicitly. First subject link still requires domain ownership.

What SqlOS creates#

SqlOS is the SCIM service provider and the IdP is the SCIM client. The IdP sends provisioning requests to SqlOS; SqlOS does not poll the IdP through these endpoints.

Directory groups mirror even when no authorization mapping exists. Add mapping rules only for groups that should grant a product role on a known FGA resource. Mapped grants must stay inside the connection's grant boundary, the organization's root resource, so a tenant's IdP cannot grant roles on another tenant's resources by choosing group names. See SCIM group mapping.

Email and lifecycle ownership#

SqlOS users are host-global, so a directory only controls the parts of a person that belong to its organization:

• Emails need a verified domain. A SCIM create, replace, or PATCH may create a SqlOSUserEmail, or set or move the verified primary email, only when the address is at an active, unrevoked verified domain of the connection's organization (see Verify domain ownership). An unverified PrimaryDomain does not count. Otherwise SqlOS answers 400 with scimType: invalidValue, writes nothing, and records a failed scim.user.rejected sync event with reason untrusted_email_domain. Re-sending the address a user already has, for example with active: false, writes no email and is always allowed.
• Existing people are linked, not owned. When the email matches a person who already has a verified SqlOS account, the connection adds a membership in its organization only and never changes that person's emails, name, or global active state. SqlOS never links a directory user onto an account whose email is still unverified; that request fails with 409 uniqueness and a scim.user.rejected event with reason unverified_email_match until the owner verifies the address.
• Ownership ends with an independent anchor. A connection owns a person's lifecycle only when it created them and only while they have no anchor of their own: an active membership in another organization, a password, an enrolled authenticator, a verified phone number, a social or OIDC identity, or a SAML identity from another organization's connection. SqlOS checks this on every SCIM write. When an anchor exists, the link's ownership ends permanently and a scim.user.lifecycle_released audit and sync event record which anchors applied. From then on the connection's email, name, and active changes affect only its own membership, FGA subject, and link fields.
• Only the owning link changes global state. A connection that does not own a person can never deactivate or reactivate them globally, even if another connection's owning link deprovisioned them.

Upgrading does not rewrite existing data. Ownership is re-evaluated on the next write for each user, and users that SCIM created earlier with an email outside the organization's verified domains keep that email. To find them, use the SCIM sync events view or query (SQL Server syntax; on PostgreSQL quote the identifiers, use TRUE, and concatenate with ||):

SELECT link.ConnectionId, link.EntityId AS UserId, email.Email
FROM SqlOSScimExternalIds AS link
JOIN SqlOSScimConnections AS connection ON connection.Id = link.ConnectionId
JOIN SqlOSUserEmails AS email ON email.UserId = link.EntityId AND email.IsPrimary = 1
WHERE link.ResourceType = 'User'
  AND link.OwnsUserLifecycle = 1
  AND NOT EXISTS (
      SELECT 1 FROM SqlOSOrganizationDomains AS domain
      WHERE domain.OrganizationId = connection.OrganizationId
        AND domain.Status = 'active'
        AND domain.RevokedAt IS NULL
        AND email.NormalizedEmail LIKE '%@' + UPPER(domain.Domain));

Soft deprovisioning and shared users#

Okta commonly deactivates a user with PATCH or PUT and active: false; Entra and other clients may send DELETE. SqlOS treats both as soft deprovisioning for that organization:

• the organization's membership becomes inactive
• sessions for that organization are revoked
• SCIM-managed group memberships are removed
• access inherited from those groups disappears
• the user row, external link, and audit history remain available for safe reactivation and investigation

A SqlOS user can belong to more than one organization. Deprovisioning from Acme must not deactivate the same person's membership or sessions in Contoso. The bearer token, resource lookup, membership updates, group changes, and session revocation all stay within the token's organization.

Manual grants, non-SCIM groups, and memberships in other organizations are not deleted by SCIM. Review those separate access paths if a person still has access after directory deprovisioning.

Rotate a compromised or lost token#

Open the connection and choose Rotate token. Copy the replacement immediately and update the IdP before its next provisioning run.

Rotation invalidates the previous token. There is no recovery path for a lost plaintext token; rotate it again. A disabled connection also rejects its token until the connection is re-enabled.

Disabling a connection immediately revokes the FGA grants managed by that connection. It does not delete mirrored groups, directory membership history, manual grants, or unrelated FGA state. Re-enabling accepts the token again, but managed grants return only after the IdP pushes or resynchronizes the affected groups.

Advanced: code-seeded setup#

Use code-first seeding for platform-owned tenants and repeatable authorization mappings. Keep token material in a secret store:

builder.AddSqlOS<AppDbContext>(options =>
{
    options.AuthServer.SeedScimConnection("acme", scim =>
    {
        scim.OrganizationSlug = "acme";
        scim.DisplayName = "Acme directory sync";
        scim.TokenSecretName = "ACME_SCIM_BEARER_TOKEN";
        // Mapped grants must target this resource or one of its descendants.
        scim.GrantBoundaryResourceId = "org::acme";
 
        scim.MapGroup("Acme-Admins", mapping =>
        {
            mapping.RoleKey = "org_admin";
            mapping.ResourceId = "org::acme";
        });
    });
});

TokenSecretName is the name of a process environment variable; SqlOS reads its value during startup reconciliation. Populate ACME_SCIM_BEARER_TOKEN from your deployment secret system. Token values must contain at least 32 characters and cannot contain whitespace. Generate a high-entropy value, store it as a secret, and never commit it to source control.

GrantBoundaryResourceId is the organization's root resource in your FGA tree. Every mapped grant, including one whose resource ID comes from a pattern template, must target that resource or one of its descendants. The resource must exist when startup reconciles the seed, so declare it with Fga.Seed or create it first. A seed without a boundary still starts and syncs users and groups, but its mappings create no grants. See SCIM group mapping.

Startup configuration is authoritative for seeded connections and seeded mapping rules. Each restart reapplies the configured display name, enabled state, grant boundary, token secret, and mappings. Changing or removing the seeded boundary revokes managed grants that are no longer inside it. Rotate a seeded credential by replacing the deployment secret and restarting SqlOS, then update the IdP with that same value. The dashboard intentionally makes seeded lifecycle, token, and mapping controls read-only so a later restart cannot silently restore an older credential.

To stage a connection before its secret is available, set scim.Enabled = false. Before connecting the IdP, generate and store the secret, keep TokenSecretName pointed at it, change scim.Enabled = true, and restart. Do not rotate or enable a seeded connection from the dashboard; those values belong in startup configuration.

Removing or renaming a seed disables the orphaned persisted connection, clears its bearer credential, and revokes its SCIM-managed grants during reconciliation. The dashboard remains the support surface for status, token metadata, read-only seeded state, optional dashboard-owned mappings, and persisted sync activity.

Troubleshooting#

The sync log records operations that reached persistence, application-level reconciliation failures, and user writes refused by the email-ownership rules (scim.user.rejected). Request parsing, authentication, filter, and PATCH validation errors are returned directly to the IdP and may not create a sync event. Audit Logs record resulting security changes. Use the IdP provisioning log, SCIM response, SqlOS sync activity, and Audit Logs together when debugging a rollout.

Repository validation#

Run the provider-shaped HTTP suite, service tests, real-SQL protocol tests, and docs gate:

dotnet test tests/SqlOS.Tests/SqlOS.Tests.csproj \
  --filter 'FullyQualifiedName~SqlOSScim'
dotnet test tests/SqlOS.IntegrationTests/SqlOS.IntegrationTests.csproj \
  --filter 'FullyQualifiedName~ScimProtocolIntegrationTests'
./scripts/docs-check.sh

Next steps#

• Set up SCIM with Microsoft Entra ID
• Set up SCIM with Okta
• Pair SCIM provisioning with SAML sign-in
• SCIM Directory Sync reference
• SCIM group mapping
• SAML SSO
• Application Access
• Audit Logs Reference