ADR-0005: SCIM Provisioning Semantics

• Status: Accepted
• Date: 2026-01-28
• Author: @digiwedge/engineering

Context

IDP is implementing SCIM 2.0 provisioning for enterprise tenants to automate user lifecycle management (create, update, deactivate, delete). Before implementation, we need to decide:

1. Attribute mapping: Fixed schema vs tenant-configurable mappings
2. Delete semantics: Hard delete vs soft delete (deactivate)
3. Group mapping: Phase 1 or deferred
4. Required attributes: Minimum data for user creation

These decisions affect implementation complexity, admin UI requirements, and enterprise customer expectations.

Decisions

1. Attribute Mapping: Fixed Schema (Phase 1)

Use a fixed attribute mapping for SCIM → IDP user fields:

SCIM Attribute	IDP Field	Required
userName	email	Yes
externalId	scimExternalId	Yes
name.givenName	profile.firstName	No
name.familyName	profile.lastName	No
active	status (ACTIVE/INACTIVE)	No (default: true)
emails[primary].value	email (fallback)	No

Rationale: Fixed mappings cover 90%+ of enterprise IdP configurations (Okta, Azure AD, OneLogin). Tenant-configurable mappings add significant admin UI complexity and can be added in a future phase if customer demand warrants.

2. Delete Semantics: Soft Delete (Deactivate)

SCIM DELETE /Users/:id performs a soft delete:

1. Set user status to INACTIVE
2. Revoke all active sessions and refresh tokens
3. Mark UserTenant association as INACTIVE
4. Retain user record and audit trail

Rationale:

• Enterprise customers require audit trails for compliance (SOC 2, ISO 27001)
• Accidental deletions can be recovered without data loss
• Matches behavior of major IdPs (Okta, Azure AD treat SCIM delete as deactivate)
• Hard delete can be offered as a tenant-level opt-in in future if needed

3. Group Mapping: Deferred to Phase 2

Group-based role mapping is out of scope for Phase 1.

Phase 1 focuses on user lifecycle (create, update, deactivate). Group sync and role assignment will be addressed in Phase 2 after user sync is proven in production with pilot tenants.

Rationale:

• User sync is the critical path for enterprise onboarding
• Group → role mapping requires additional schema design and admin UI
• Pilot tenants can use manual role assignment until group sync is ready

4. Required Attributes: Email + ExternalId

Minimum required attributes for SCIM user creation:

Attribute	Why Required
userName or emails[primary].value	Primary identifier for login
externalId	Idempotency key for retries and reconciliation

Optional but recommended: name.givenName, name.familyName for display.

Rationale:

• Email is the primary identifier in IDP's authentication model
• ExternalId ensures idempotent creates (prevents duplicates on retry)
• Names enhance UX but are not required for authentication

Consequences

Positive

• Simpler Phase 1 implementation with predictable behavior
• Lower admin UI burden (no custom mapping configuration)
• Audit-friendly soft delete with recovery capability
• Clear idempotency model reduces sync failures

Negative

• Fixed mapping may not fit all IdP configurations (rare edge cases)
• No group sync in Phase 1 limits role automation
• Soft delete may accumulate inactive users over time (needs cleanup policy)

Alternatives Considered

Alternative	Pros	Cons	Why not chosen
Tenant-configurable mappings	Flexibility	Complex admin UI; more support tickets	Overkill for Phase 1
Hard delete	Cleaner data	No audit trail; no recovery	Compliance risk
Group sync in Phase 1	Full automation	Scope creep; delays user sync	Deferred to Phase 2
Email-only (no externalId)	Simpler	Duplicate risk on retries	Idempotency is critical

Follow-ups

• Implement TenantScimConfig and ScimUserMapping models
• Add SCIM Users endpoints (Phase 2 of SCIM plan)
• Document SCIM integration guide for enterprise customers
• Plan inactive user cleanup policy (retention cron)
• Design group sync schema for Phase 2