SCIM 2.0 Enterprise Provisioning

SCIM (System for Cross-domain Identity Management) 2.0 is an industry-standard protocol for automating user provisioning and management. When integrated, your identity provider (Okta, Azure AD, OneLogin, etc.) can automatically create, update, and deactivate users in define.wtf without manual intervention.

From an Integration Perspective

This guide focuses on using SCIM to integrate define.wtf with your identity provider. For setup and configuration details, see the Admin Guide: SCIM Configuration.

What SCIM Does

SCIM provides one-way synchronization from your identity provider to define.wtf:

SCIM + SSO: The Complete Picture

SCIM and SSO work together for seamless enterprise identity:

Typical flow:

1. Day 1: Admin sets up SSO in define.wtf
2. Day 2: Admin sets up SCIM provisioning
3. Day 3: New team member is added to company directory
4. Day 4: SCIM creates the user in define.wtf, SSO allows them to log in with company credentials

Together, they eliminate manual user management entirely.

Supported Identity Providers

Okta

Features:

• Full SCIM 2.0 support
• Group-to-role mapping
• Real-time provisioning
• Automatic deprovisioning

Setup: See Admin Guide: SCIM Configuration

Azure Active Directory (Azure AD)

Features:

• Native SCIM support
• Enterprise user schema support
• Group membership sync
• Automatic deprovisioning

Setup: See Admin Guide: SCIM Configuration

OneLogin

Features:

• Full SCIM 2.0 compliance
• Provisioning workflows
• Custom attribute mapping

Ping Identity, JumpCloud, Others

Any SCIM 2.0-compliant provider is supported. Configuration steps vary by provider.

How Provisioning Works

New User Flow

1. Admin adds user to IdP — In Okta, Azure AD, etc., they add a new team member
2. IdP triggers SCIM sync — The provider sends a POST /Users request to define.wtf
3. User created in define.wtf — User account is created with email, name, active status
4. Default role assigned — New users typically get the "Viewer" role (adjustable)
5. User can log in via SSO — First time they log in, they're authenticated via their company credentials

Update Flow

1. Admin updates user info in IdP — They change the user's name, department, etc.
2. IdP triggers SCIM sync — The provider sends a PATCH /Users/{id} request
3. Update applied in define.wtf — User's profile is updated
4. User sees changes immediately — On next login, updated info is reflected

Deprovisioning Flow

1. Admin removes user from IdP — Employee leaves company; admin removes them from directory
2. IdP triggers SCIM sync — The provider sends a DELETE /Users/{id} request
3. User deactivated in define.wtf — Account marked as inactive
4. User cannot log in — SSO attempts fail because user is inactive
5. Contribution history retained — User's edit history remains visible for audit purposes

Attributes Synchronized

When SCIM provisions a user, these attributes are synced:

Default Role Assignment

When a user is provisioned via SCIM:

• New users are assigned the default role: Viewer
• Role changes can be made manually by admins after provisioning
• No automatic group mapping — Role assignment is not automatic based on identity provider groups

To change a user's role after they're provisioned:

1. Go to Admin → Members
2. Find the user in the list
3. Click Actions → Change Role
4. Select the new role
5. Confirm

Use Cases

Enterprise Onboarding

• New hire is added to your company directory
• SCIM automatically creates their define.wtf account
• SSO allows them to log in immediately
• They appear in team member lists
• Their name/email are correct from the start

Offboarding

• Employee leaves the company
• Admin removes them from your IdP
• SCIM deactivates their define.wtf account
• They can no longer log in
• Their contributions remain for audit purposes

Department Transfers

• Employee moves to a new department in IdP
• SCIM updates their basic profile info (name, email)
• Admin can manually update their role if needed
• Changes take effect immediately in define.wtf

Compliance & Audit

• All provisioning events are logged
• Audit trail shows which users were created/modified/deactivated and when
• Supports compliance requirements (SOC 2, HIPAA, ISO 27001)

Technical Details

SCIM Endpoint

All define.wtf customers share the same SCIM endpoint:

https://app.define.wtf/api/scim/v2

Tenant identification happens via the SCIM API token, not the URL.

Authentication

SCIM requests use Bearer token authentication:

Authorization: Bearer <SCIM_API_TOKEN>

The token is generated and managed by your define.wtf workspace admin. See Admin Guide: Generate SCIM Token.

Supported Schemas

define.wtf implements:

• Core User schema — id, userName, name, active, emails
• Enterprise User schema — employeeNumber, department, manager (optional)
• Group schema — id, displayName, members

RFC 7644 Compliance

define.wtf implements SCIM 2.0 per RFC 7644 with:

• Filtering, sorting, and pagination support
• Proper HTTP status codes (201 Created, 204 No Content, 404 Not Found, etc.)
• Standard error response formats
• Bulk operations support

Monitoring Provisioning

Activity Log

All SCIM events appear in your define.wtf audit trail:

1. Go to Admin → Activity
2. Filter by Event Type = "SCIM Provisioning"
3. View:
   • What action occurred (create, update, deactivate)
   • Which user was affected
   • When it happened
   • Success or error status

Common Events

Troubleshooting

Users not appearing after 5 minutes:

1. Check your IdP logs for provisioning errors
2. Verify the SCIM token hasn't expired
3. Test the SCIM connection from your IdP settings (button usually says "Test Connection")
4. Check the audit log for scim:error events

Updates not syncing:

1. Verify your IdP is configured to sync this attribute
2. Check field mapping in your IdP's SCIM configuration
3. Some IdPs only sync on save; re-save the user to trigger sync

Users deactivated unexpectedly:

1. Check if the user was removed from your IdP
2. Review the audit log for who triggered the deprovisioning
3. Contact your IdP admin if this was unintended

Best Practices

• Test with a pilot group — Before enabling org-wide provisioning, test with a small department or team
• Monitor the first week — Check audit logs to ensure provisioning is working smoothly
• Document your mapping — Keep notes of which IdP groups map to which define.wtf roles
• Rotate SCIM tokens annually — Refresh your SCIM token every 12 months
• Use unique identifiers — Ensure your IdP uses unique, stable user IDs (not email addresses) for user identification

Limitations

• One-way sync — Changes in define.wtf are not sent back to your IdP
• No group-based role assignment — SCIM does not automatically map IdP groups to define.wtf roles
• No cascading deactivation — When a group is deleted in your IdP, users remain active in define.wtf
• Manual role management — Admins must manually assign or change roles in define.wtf

Integration with Other Features

Webhooks

When a user is provisioned via SCIM, webhooks are triggered:

{
  "event": "user.created",
  "userId": "user-123",
  "email": "jane.doe@acme.com",
  "source": "scim"
}

Use webhooks to:

• Trigger notifications to other systems
• Update external databases
• Log to a SIEM system

See: Webhooks & Automations

Audit Trail

All SCIM events are logged with full context:

• User ID and email
• Action performed (create, update, delete)
• Old and new values (for updates)
• Timestamp
• SCIM token used

This supports compliance requirements for user access reviews and change tracking.

Support

For SCIM issues:

1. Check your IdP logs for provisioning errors
2. Verify the SCIM token and endpoint URL are correct
3. Test the connection from your IdP
4. Review the audit trail for errors
5. Contact support@define.wtf with:
   • Your IdP name (Okta, Azure AD, etc.)
   • Error message if visible
   • Steps you've taken to troubleshoot

See Also

• Admin Guide: SCIM Configuration — Setup instructions
• Admin Guide: SSO Configuration — Pair with SSO for complete identity management
• REST API: SCIM Reference — Technical SCIM endpoint documentation