SCIM 2.0 Configuration

SCIM 2.0 (System for Cross-domain Identity Management) enables enterprise identity providers like Okta, Azure AD, and OneLogin to automatically provision and deprovision users in define.wtf. This removes manual user management overhead and keeps your team roster in sync across platforms.

What is SCIM?

SCIM is an industry standard protocol for user identity management. When configured:

• Auto-create users — New team members added to your IdP automatically appear in define.wtf
• Update profile data — Changes to user information (name, email) sync automatically
• Deprovisioning — When users are removed from your IdP, their accounts are deactivated in define.wtf
• No password sharing — IdP credentials are never shared; SCIM uses an API token

Supported Identity Providers

SCIM 2.0 provisioning is compatible with:

• Okta — Full support including group-to-role mapping
• Azure AD — Native SCIM support, automated provisioning
• OneLogin — Full SCIM 2.0 compliance
• Ping Identity — Supported via SCIM endpoint
• JumpCloud — SCIM 2.0 connector available
• Any SCIM 2.0 client — Generic SCIM-compliant providers

Enabling SCIM Provisioning

Step 1: Generate SCIM Token

1. Navigate to Settings → SCIM Provisioning tab
2. Click Generate Token (or Regenerate Token if one exists)
3. A new token will be displayed once (you cannot view it again)
4. Copy and save this token securely — store it in your password manager or secure vault
5. Click away or proceed to the next step

Step 2: Note Your SCIM Endpoint

Your SCIM endpoint URL is displayed in the settings:

https://{slug}.define.wtf/api/scim

This endpoint is unique to your tenant (identified via the slug in the URL).

Step 3: Configure Your Identity Provider

Follow your IdP's documentation to set up SCIM provisioning:

• Endpoint URL: https://{slug}.define.wtf/api/scim
• Authentication: Bearer token authentication
• Token: Paste the API token you generated in Step 1
• User attribute mappings: Map your IdP user attributes to define.wtf fields

Okta Setup Example

In Okta:

1. Go to Applications → Applications → Create new SCIM app
2. Select SCIM 2.0 provisioning with authentication protocol
3. On the API integration page, enter:
   • SCIM Base URL: https://{slug}.define.wtf/api/scim
   • Authorization Method: Bearer token
   • Token: Paste your define.wtf SCIM token
4. Click Test API Credentials — should return success
5. Go to Provisioning → To App and select which Okta groups to sync

Azure AD Setup Example

In Azure AD:

1. Go to Enterprise Applications → New Application → Create your own application
2. Name it "define.wtf" and select "Integrate any other application you don't find in the gallery"
3. In Provisioning, set Provisioning Mode to Automatic
4. In Admin Credentials, enter:
   • Tenant URL: https://{slug}.define.wtf/api/scim
   • Secret Token: Paste your define.wtf SCIM token
5. Click Test Connection — should return success

User Attribute Mapping

When configuring your IdP, map these attributes:

What Gets Provisioned

When a user is provisioned via SCIM:

• Email address (used as unique identifier)
• Full name (if provided by IdP)
• Active/inactive status
• These attributes sync to the user's define.wtf profile

What does NOT get provisioned:

• Define.wtf API keys
• Roles and permissions (managed manually by admins or via SCIM groups)
• Activity history

User Deprovisioning

When a user is removed from your IdP or marked as inactive:

1. The deprovisioning request is sent to define.wtf via SCIM
2. The user's account is deactivated (soft delete — data is retained)
3. The user can no longer log in
4. Their edit history and contributions remain visible for audit purposes

Managing SCIM Tokens

Rotate a Token

If you suspect a token has been compromised:

1. Go to Settings → SCIM Provisioning
2. Click Regenerate Token
3. Confirm the action
4. Immediately generate a new token and update your IdP configuration
5. Provisioning will use the new token for all subsequent requests

Token Security

• Tokens are 64 random alphanumeric characters
• Treat them like passwords — never share via email or chat
• Store in a password manager or secure vault
• Rotate every 90 days as a best practice

Testing SCIM Integration

Before deploying to production, test your SCIM setup:

Test 1: Connection

• Most IdPs offer a "Test Connection" button
• This verifies the endpoint URL and token are correct
• You should see a success message

Test 2: Pilot Provisioning

• Provision a test user via your IdP
• Verify the user appears in define.wtf within 2-5 minutes
• Check that email and name were synced correctly

Test 3: Update

• Modify the test user's information in your IdP
• Verify the changes sync to define.wtf within 2-5 minutes

Test 4: Deprovision

• Remove the test user from your IdP
• Verify the user is deactivated in define.wtf within 2-5 minutes

Common Issues

Users not appearing after 5 minutes:

• Verify the SCIM token hasn't expired
• Check your IdP logs for provisioning failures
• Verify the endpoint URL matches exactly

"Invalid token" error:

• The SCIM token may have been revoked
• Generate a new token and update your IdP configuration
• Test the connection again

Updates not syncing:

• Verify that attribute mappings are configured correctly in your IdP
• Ensure the user attribute that triggers updates is mapped to define.wtf
• Some IdPs require re-saving the provisioning rule to take effect

Best Practices

• Test first — Always test SCIM provisioning with a pilot group before rolling out org-wide
• Monitor regularly — Check your audit trail weekly to catch any provisioning issues
• Rotate tokens — Refresh your SCIM token every 90 days
• Document mappings — Keep records of which IdP groups map to which define.wtf groups/roles
• Redundancy — Have a manual user management process as a backup if SCIM provisioning fails

Disabling SCIM

To stop using SCIM provisioning:

1. Remove the SCIM integration from your IdP (stops sending requests)
2. Revoke your SCIM token in Settings → SCIM Provisioning (optional)
3. Existing users remain in define.wtf and can still log in via SSO or manual authentication
4. New users added to your IdP won't automatically appear in define.wtf

SCIM 2.0 Compliance

Define.wtf implements SCIM 2.0 as defined by RFC 7644. Supported features:

• Core User schema (id, userName, name, active)
• User attribute mapping and filtering
• Pagination and bulk operations support