Define identity effects before implementing SCIM endpoints
A production SCIM requirements document defines how one customer's directory intent becomes a tenant-scoped product account change. It covers stable identity, users and groups, create and lookup rules, attribute updates, suspension, reactivation, deletion policy, permission effects, sessions, retries, reconciliation, evidence, and recovery. Endpoint compliance is necessary, but it is not the whole feature.
Start with one real enterprise connection. Name the customer tenant, identity provider, authoritative directory, user population, group strategy, product account model, offboarding promise, administrator, support owner, and launch evidence. Do not begin with a universal attribute map for customers you have not interviewed.
Keep provisioning, login, authorization, and tenancy separate
SCIM manages identity resources. It does not prove the user is currently present, establish an interactive session, or decide every product permission. The existing SaaS SSO requirements guide covers federation and session entry; the permissions checklist covers tenant-safe authorization. Write the handoffs among all three rather than making a group name silently grant broad access.
Separate customer-organization provisioning from creation of the organization itself. Domain verification, subscription setup, data residency, initial administrators, defaults, and rollout belong to the broader tenant provisioning lifecycle. The SCIM connection should attach to a verified tenant through an explicit administrative act, not infer tenancy from an email domain.
Write a lifecycle contract for every identity transition
For create, find, update, suspend, reactivate, group change, and delete, record the trigger, tenant, client identity, input identifiers, validation, product effect, returned resource, audit event, notification, retry behavior, and recovery owner. Include a periodic comparison that detects missing, extra, or divergent records without allowing reconciliation to overwrite a deliberate product-side exception.
Use separate stable keys for the SCIM resource, the provisioning client's resource, the product account, and the tenant. RFC 7643 defines externalId as an identifier issued by the provisioning client and scoped to its provisioning domain. That makes it useful for correlation, but not a global identity key. Decide how email changes, reused usernames, mergers, duplicate accounts, and a person belonging to multiple tenants are handled.
Define deprovisioning in product language. The SCIM activeattribute's precise meaning is left to the service provider; the RFC gives suspended login as a typical example. State whether suspension blocks new login, revokes active sessions and tokens, unassigns work, removes group-derived permissions, hides the user, preserves actor references, and permits safe reactivation.
Specify the protocol surface clients will actually exercise
Discovery
ServiceProviderConfig, ResourceTypes, Schemas, declared capabilities, extensions, and versioned documentation.
Resources
Users, groups where required, canonical attributes, customer extensions, mutability, returned fields, and normalization.
Queries
Required filters, empty results, exact matching, attributes, pagination, stable ordering where promised, and tenant scope.
Writes
POST, PATCH and/or PUT behavior, partial updates, group membership, uniqueness conflicts, ETags where supported, and deletion semantics.
Responses
SCIM media type, status codes, error schema, scimType, actionable detail, resource location, and safe correlation identifiers.
Capacity
Expected users, groups, memberships, request bursts, import duration, limits, backoff, timeouts, concurrency, and bulk support if promised.
RFC 7644 defines the protocol, including discovery, filtering, pagination, PATCH, errors, and resource versioning. Build against the standard and then test the target clients' supported profiles. Okta's SCIM integration guidance notes that its client performs create, read, update, and delete lifecycle operations and may use PATCH or PUT depending on the integration path. Compatibility assumptions belong in tests.
Microsoft's current App Gallery provisioning requirements require a SCIM 2.0 user endpoint, recommend groups, cover schema discovery and deletion behavior, and specify supported authentication patterns and secret rotation. Treat gallery listing as a separate delivery track with its own current rules, customer prerequisites, documentation, and support commitment.
Design authentication, observability, and recovery together
Scope credentials to one tenant and provisioning connection. Define issuance, storage, rotation, expiry, revocation, allowed network paths where appropriate, rate limits, and emergency disablement. Never place tokens or unnecessary profile values in logs. Audit connection administration and each material resource effect with tenant, actor or client, target, time, result, and a safe correlation key.
Monitor authentication failures, error rates, throttling, queue delay, repeated conflicts, drift, and unusual volume per tenant. Document who receives alerts, what customers can see, how support replays or corrects an operation, and how a broken connector is paused without preventing tenant administrators from controlling access through an approved fallback.
Use a one-tenant production-readiness worksheet
- Freeze the authority map. Record tenant, IdP, directory, SCIM client, product account, authorization, session, audit, and support owners.
- Map identity fields. Include stable keys, required and optional attributes, extensions, normalization, mutability, privacy purpose, and invalid values.
- Run the lifecycle. Create, find, update, suspend, reactivate, add and remove group membership, delete where promised, and reconcile.
- Break ordering. Repeat, delay, reorder, partially fail, and concurrently update requests; verify convergence without duplicates or lost changes.
- Cross the boundaries. Confirm permissions, active sessions, API tokens, ownership of records, notifications, exports, and retained audit evidence.
- Exercise operations. Rotate credentials, trigger limits, interrupt dependencies, inspect customer-safe diagnostics, restore service, and reconcile drift.
- Approve the promise. Publish supported resources, attributes, limitations, expected timing, troubleshooting, escalation, rollback, and named owners.
If the current account and tenant models cannot meet the contract, scope that foundation first. Leeonex's MVP and SaaS development service can help define an incremental identity feature and its testable product boundary without claiming a universal connector.
SCIM provisioning FAQ
What should a SCIM provisioning requirements document include?
Include the customer tenant and IdP, supported SCIM version and resources, stable identifiers, attribute and group mappings, create and lookup rules, updates, suspension, reactivation, deletion policy, authorization effects, session consequences, filtering, pagination, PATCH behavior, authentication, rate limits, retries, idempotency, errors, audit events, monitoring, reconciliation, support, documentation, and acceptance evidence.
Is SCIM the same as SSO?
No. SSO authenticates a person and starts a product session. SCIM manages user and group resources across their lifecycle. A product can support one without the other, but enterprise access is safer when provisioning, authentication, authorization, sessions, and offboarding have an explicit shared contract.
Should deprovisioning delete or suspend a SaaS user?
Treat the behavior as a product and records decision. Suspension is often safer when business records must retain an actor reference, while deletion may be required or requested in other contexts. Define what the SCIM active attribute and DELETE mean, what happens to sessions and tokens, how reactivation works, and which records remain, then review privacy, contractual, and retention obligations with accountable specialists.
How should a SCIM integration be tested before launch?
Use a customer-like test tenant to create, find, update, suspend, reactivate, group, ungroup, and remove users. Repeat requests, reorder them, send duplicates and stale versions, exercise pagination and filters, rotate credentials, exceed limits, interrupt dependencies, reconcile drift, and verify tenant isolation, least privilege, session behavior, logs, alerts, and support diagnostics.