> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wolfia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SCIM User Provisioning Setup for Wolfia

> Configure SCIM Directory Sync between Okta, Azure AD, or Google Workspace and Wolfia: automatic user provisioning, deprovisioning, and group-to-role mapping.

## Overview

SCIM (System for Cross-domain Identity Management) enables automatic user and group synchronization between your identity provider and Wolfia. This provides:

* **Automatic user provisioning:** New users in your IdP automatically get Wolfia access
* **Real-time updates:** Changes to users in your IdP sync immediately to Wolfia
* **Automatic deprovisioning:** Removing users from your IdP removes their Wolfia access
* **Role assignment:** Map your IdP groups to Wolfia roles for automatic permission management
* **Reduced admin overhead:** No manual user management required

## How SCIM works

SCIM creates a continuous sync between your identity provider and Wolfia:

1. **Create:** When you assign a user to Wolfia in your IdP, they're automatically created in Wolfia
2. **Update:** Changes to user details (name, email, group membership) sync automatically
3. **Delete:** Removing a user from Wolfia in your IdP deactivates their account
4. **Groups:** Your IdP groups sync to Wolfia and control user roles

<Note>
  SCIM requires SSO to be configured first. If you haven't set up SSO yet, see our [SSO Setup Guide](/how-to/sso-setup).
</Note>

## Supported identity providers

Wolfia supports SCIM with these providers:

* **Okta** (SCIM 2.0)
* **Azure Active Directory / Microsoft Entra ID** (SCIM 2.0)
* **Google Workspace** (Google Directory API)
* **OneLogin** (SCIM 2.0)
* **JumpCloud** (SCIM 2.0)
* **Authentik** (SCIM 2.0)
* **Any SCIM 2.0 compatible provider**

## Prerequisites

Before setting up SCIM:

* [x] **SSO must be configured** - Complete [SSO setup](/how-to/sso-setup) first
* [x] **Admin access to your IdP** - You need permissions to configure SCIM
* [x] **Admin access to Wolfia** - Must be an Administrator role
* [x] **Groups configured** in your IdP (if using role assignment)

## Setup process

<Steps>
  <Step title="Request SCIM setup">
    Contact your Wolfia account representative or email [support@wolfia.com](mailto:support@wolfia.com) to:

    * Enable SCIM/Directory Sync for your organization
    * Receive your unique SCIM configuration portal link
    * Ensure SSO is properly configured

    You'll receive a secure setup link via email that provides step-by-step configuration guidance.
  </Step>

  <Step title="Access the configuration portal">
    Click the Directory Sync setup link provided by Wolfia. You'll be directed to a guided configuration portal that walks you through each step specific to your identity provider.
  </Step>

  <Step title="Select your identity provider">
    In the configuration portal:

    1. Choose your identity provider from the list
    2. The portal displays provider-specific instructions
    3. Note the SCIM connection details you'll need

    **Common providers:**

    * **Okta:** SCIM 2.0 endpoint and bearer token
    * **Azure AD:** Automatic provisioning setup
    * **Google Workspace:** Directory API configuration
    * **Authentik:** SCIM endpoint and token configuration
  </Step>

  <Step title="Configure SCIM in your identity provider">
    The configuration portal provides specific setup details for your IdP:

    ### For Okta:

    1. In Okta Admin Console, go to Applications → Your Wolfia App
    2. Click the "Provisioning" tab
    3. Click "Configure API Integration"
    4. Enter the SCIM Base URL and API Token from the portal
    5. Test the connection
    6. Enable provisioning features: "Create Users", "Update User Attributes", "Deactivate Users"
    7. Configure attribute mappings (email, firstName, lastName)

    ### For Azure AD (Entra ID):

    1. In Azure Portal, go to Enterprise Applications → Wolfia
    2. Click "Provisioning" in the left menu
    3. Set Provisioning Mode to "Automatic"
    4. Enter the Tenant URL and Secret Token from the portal
    5. Test the connection
    6. Configure attribute mappings
    7. Set Provisioning Status to "On"

    ### For Google Workspace:

    1. The configuration portal will guide you through OAuth authorization
    2. Grant Wolfia access to your Google Workspace directory
    3. Select which organizational units to sync
    4. Configure user and group sync settings

    ### For Authentik:

    1. In Authentik Admin Interface, create a new Provider
    2. Choose "SCIM Provider" as the type
    3. Enter the SCIM endpoint URL from the portal
    4. Configure the bearer token
    5. Set up property mappings for user attributes
    6. Create an Application and bind the provider

    ### For JumpCloud:

    1. In JumpCloud Admin Portal, go to Applications
    2. Click "+ Add Application" and select "Custom Application"
    3. Choose "SAML with SCIM User Provisioning"
    4. Enter the SCIM Base URL and API Token from the portal
    5. Test the connection to verify connectivity
    6. Configure attribute mappings:
       * **Email**: Required - Maps to user's email address
       * **First Name**: Maps to givenName
       * **Last Name**: Maps to surname
       * **Role**: Critical for automatic role assignment (see below)
    7. Configure the role attribute:
       * In Attribute Mapping section, add a custom attribute named "role"
       * Set the source to a JumpCloud user attribute or group membership
       * Value must be one of: "ADMIN", "EXPERT", or "USER"
       * Example: Map `customAttributes.wolfiaRole` to "role" in SCIM payload
    8. Enable provisioning features:
       * Create Users: Automatically create users when assigned
       * Update User Attributes: Sync attribute changes
       * Deactivate Users: Remove access when unassigned
       * Push Groups: Sync group memberships (required for role assignment)
    9. Assign users or groups to the Wolfia application

    **JumpCloud Role Mapping Context:**
    JumpCloud sends user attributes via SCIM, including the "role" attribute if configured. To enable automatic role assignment:

    * **Option 1 - User Attribute**: Set a custom user attribute (e.g., `wolfiaRole`) in JumpCloud user profiles with values "ADMIN", "EXPERT", or "USER"
    * **Option 2 - Group-Based**: Use JumpCloud's group membership to determine roles, then map those groups to the role attribute in the SCIM configuration
    * The role value flows through the SCIM payload and Wolfia automatically assigns permissions based on this value
    * Users without a role attribute default to "Standard User" role
  </Step>

  <Step title="Configure role assignment (Optional but Recommended)">
    Map your IdP groups to Wolfia roles for automatic permission management:

    **Available Wolfia roles:**

    * **Administrator:** Full access to all features, settings, and user management
    * **Expert:** Advanced access to create content, manage integrations, and handle questionnaires
    * **Standard User:** View and interact with shared content, participate in questionnaires

    **In the configuration portal:**

    1. After connecting your directory, you'll see a "Role Assignment" section
    2. For each group you want to map:
       * Select a group from your identity provider
       * Choose the corresponding Wolfia role
    3. Review your role mappings

    **Example mappings:**

    ```
    IT Administrators    → Administrator
    Security Team        → Expert
    Compliance Team      → Expert
    Engineering Team     → Standard User
    Sales Team           → Standard User
    ```

    <Info>
      Users not in any mapped group automatically receive the **Standard User** role. You only need to map groups that require elevated permissions.
    </Info>
  </Step>

  <Step title="Configure sync settings">
    In your identity provider, configure what to sync:

    **User sync:**

    * [x] Create users automatically when assigned to Wolfia
    * [x] Update user attributes (name, email) when changed
    * [x] Deactivate users when unassigned from Wolfia

    **Group sync (for role assignment):**

    * [x] Sync group memberships to Wolfia
    * [x] Update group assignments in real-time
    * [x] Map groups to Wolfia roles (configured in the portal)

    <Warning>
      Be careful with "Delete users" if your IdP supports it. We recommend using "Deactivate" instead to preserve user history and data.
    </Warning>
  </Step>

  <Step title="Assign users and groups">
    In your identity provider:

    1. Assign users to the Wolfia application
    2. Assign groups to the Wolfia application (if using role assignment)
    3. Users will be automatically created in Wolfia within minutes

    **For Okta:**

    * Go to Applications → Wolfia → Assignments
    * Click "Assign" and choose "Assign to People" or "Assign to Groups"

    **For Azure AD:**

    * Go to Enterprise Applications → Wolfia → Users and groups
    * Click "+ Add user/group" and select users or groups

    **For Google Workspace:**

    * Users are automatically synced based on organizational unit selection

    **For Authentik:**

    * Assign users or groups to the Wolfia application
    * Ensure users have the necessary permissions
  </Step>

  <Step title="Complete setup and test">
    1. Click "Finish Setup" in the configuration portal
    2. The system validates the SCIM connection
    3. Initial user sync begins automatically

    **To test:**

    1. Assign a test user to Wolfia in your IdP
    2. Wait 2-5 minutes for sync to complete
    3. Check the Wolfia Admin Panel → Users section
    4. Verify the user appears with correct role
    5. Test login with the user's SSO credentials
  </Step>
</Steps>

## User experience with SCIM

### For new users

When a user is assigned to Wolfia in your IdP:

1. **Automatic account creation:** User account created in Wolfia within 2-5 minutes
2. **Role assignment:** User receives role based on group membership (if configured)
3. **Welcome email:** User receives invitation to access Wolfia
4. **SSO login:** User can immediately log in via SSO

### For existing users

When you enable SCIM for an organization with existing users:

1. **Account matching:** SCIM matches users by email address
2. **No duplicate accounts:** Existing users are updated in place
3. **Role updates:** If role assignment is enabled, existing user roles are updated
4. **Seamless transition:** Users experience no interruption

### For user changes

When a user's details change in your IdP:

| Change          | SCIM Action       | Result in Wolfia                     |
| --------------- | ----------------- | ------------------------------------ |
| Name updated    | User update       | Name updated immediately             |
| Email changed   | User update       | Email and login updated              |
| Group added     | Group sync        | Role updated (if mapped)             |
| Group removed   | Group sync        | Role downgraded (if applicable)      |
| User unassigned | User deactivation | Account deactivated, loses access    |
| User reassigned | User reactivation | Account reactivated, access restored |

## Role assignment in detail

### How role assignment works

When you map IdP groups to Wolfia roles:

1. **Initial assignment:** When a user is first synced, Wolfia checks their group memberships
2. **Role determination:** User receives the highest privilege role from their groups
3. **Automatic updates:** When group membership changes, role updates within minutes
4. **Default role:** Users without any group mapping receive Standard User role

### Role hierarchy and permissions

| Role              | Permissions                                                                                                                                                                                                                    | Use Cases                                                           |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| **Administrator** | • Full access to all features<br />• Manage organization settings<br />• Manage users and permissions<br />• Configure integrations<br />• Manage trust portals<br />• Access internal admin tools                             | IT Admins, Engineering Leads, Security Administrators               |
| **Expert**        | • Create and manage content<br />• Configure integrations<br />• Approve answers in questionnaires<br />• Manage questionnaires and policies<br />• Collaborate across teams<br />• Cannot modify org settings or manage users | Security Team, Compliance Team, Product Managers, Technical Writers |
| **Standard User** | • View and interact with shared content<br />• Upload questionnaires and edit answers<br />• Access trust portals<br />• Collaborate with team members<br />• Cannot approve answers, create integrations, or modify content   | All Employees, Contractors, External Collaborators                  |

### Example role assignment scenarios

**Scenario 1: IT Administrator**

* Member of "IT Administrators" group
* Mapped to Administrator role
* Has full access to all Wolfia features

**Scenario 2: Security team member**

* Member of "Security Team" and "All Employees" groups
* "Security Team" mapped to Expert role
* Receives Expert role (highest available)

**Scenario 3: Regular employee**

* Member of "All Employees" group only
* "All Employees" not mapped to any role
* Receives Standard User role (default)

**Scenario 4: Multiple privileged groups**

* Member of both "Security Team" (Expert) and "IT Admins" (Administrator)
* Receives Administrator role (highest privilege)

<Note>
  **Single role limitation:** Users can only have one role at a time. If a user is in multiple groups with different role mappings, they receive the highest privilege role.
</Note>

## Reconciliation and sync frequency

SCIM keeps Wolfia synchronized with your IdP through:

1. **Real-time sync:** Changes pushed immediately via webhooks (typically 1-5 minutes)
2. **Daily reconciliation:** Full sync runs daily to catch any missed updates
3. **Manual sync:** Contact Wolfia support to trigger immediate full reconciliation

### What syncs in real-time:

* User creation, updates, and deactivation
* Group membership changes
* Role updates (via group changes)

### What syncs during reconciliation:

* Verification of all users and groups
* Correction of any sync discrepancies
* Role verification and updates

## Monitoring and troubleshooting

### Check sync status

1. **In your IdP:**
   * Check provisioning logs for sync events
   * Look for any error messages or warnings
   * Verify users are assigned to Wolfia app

2. **In Wolfia Admin Panel:**
   * Go to Settings → Users
   * Verify users appear with correct roles
   * Check last login and account status

3. **In the configuration portal:**
   * View sync event logs
   * Check connection health status
   * Review recent sync operations

### Common issues and solutions

<AccordionGroup>
  <Accordion title="User not syncing to Wolfia">
    **Common causes:**

    * User not assigned to Wolfia app in IdP
    * Email attribute mapping incorrect
    * SCIM connection credentials expired

    **Solutions:**

    1. Verify user is assigned to Wolfia in your IdP
    2. Check attribute mappings (email must be included)
    3. Re-validate SCIM credentials in the configuration portal
    4. Review IdP provisioning logs for errors
    5. Contact Wolfia support with error details
  </Accordion>

  <Accordion title="User has wrong role">
    **Common causes:**

    * Group membership not synced
    * Role mapping incorrect in configuration portal
    * User in multiple groups with different mappings

    **Solutions:**

    1. Verify user's group memberships in IdP
    2. Check role mappings in the configuration portal
    3. Remove user from groups they shouldn't be in
    4. Wait 5-10 minutes for sync to complete
    5. Trigger manual reconciliation if needed
  </Accordion>

  <Accordion title="Sync stopped working">
    **Common causes:**

    * SCIM credentials expired or rotated
    * Network/firewall blocking requests
    * IdP configuration changed

    **Solutions:**

    1. Check SCIM connection status in configuration portal
    2. Re-validate credentials if expired
    3. Review recent IdP configuration changes
    4. Check IdP provisioning logs for errors
    5. Contact Wolfia support for investigation
  </Accordion>

  <Accordion title="Group changes not reflecting">
    **Common causes:**

    * Group sync not enabled
    * Group not assigned to Wolfia app
    * Role mapping not configured for group

    **Solutions:**

    1. Ensure group sync is enabled in your IdP
    2. Verify group is assigned to Wolfia application
    3. Check role mapping exists for the group
    4. Wait 5-10 minutes for sync
    5. Manually trigger reconciliation
  </Accordion>
</AccordionGroup>

## Security considerations

### Best practices

* **Least privilege:** Only map groups that need elevated permissions to Admin/Expert roles
* **Regular review:** Periodically review role mappings and group memberships
* **Audit logging:** Monitor sync logs for unexpected changes
* **Test before rollout:** Test with a small group before enabling for entire organization

### Data sync

SCIM syncs the following data:

* **User identifiers:** Email, first name, last name, external ID
* **Group memberships:** Only groups mapped to Wolfia roles
* **Status:** Active or deactivated

<Info>
  Wolfia does **not** store your IdP passwords or authentication credentials. All authentication goes through your IdP via SSO.
</Info>

## Disabling SCIM

If you need to disable SCIM:

1. **In your IdP:** Turn off provisioning or unassign users
2. **Contact Wolfia support:** Request SCIM disconnection
3. **User impact:** Existing users remain active but won't auto-sync

<Warning>
  After disabling SCIM, you must manually manage user accounts and roles through the Wolfia Admin Panel.
</Warning>

## Need help?

SCIM setup can be complex. Our team is here to help:

* **Email:** [support@wolfia.com](mailto:support@wolfia.com)
* **Include:** Organization name, IdP type, and sync logs/errors
* **Response time:** We typically respond within 1 business day
* **Setup assistance:** We can join a call to help configure SCIM

## Related guides

* [SSO Setup](/how-to/sso-setup) - Configure Single Sign-On (required before SCIM)
* [Okta Directory Sync](/how-to/okta-directory-sync) - Sync users and groups directly from Okta
* [Setting up Wolfia](/how-to/setup-admin) - General admin setup guide
* [API User Invites](/how-to/api-invite-users) - Programmatic user management alternative