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.

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 marks the SCIM primary email verified; the SAML callback can then link the IdP subject to that existing user without creating a new user or membership.

That setting gives the smoothest email-first routing for a trusted organization domain. For a narrower policy, leave AutoLinkByEmail / Require SSO for existing members off and have the application start the organization's SAML connection explicitly. SqlOS can still complete the first subject link when the signed assertion email exactly matches an active, same-organization SCIM record; it does not treat this as general email auto-linking.

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.

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";
 
        scim.MapGroup("Acme-Admins", mapping =>
        {
            mapping.RoleKey = "org_admin";
            mapping.ResourceId = "organization::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.

Startup configuration is authoritative for seeded connections and seeded mapping rules. Each restart reapplies the configured display name, enabled state, token secret, and mappings. 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 and application-level reconciliation failures. 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