SCIM Integration with User Groups

Overview

SCIM (System for Cross-domain Identity Management) enables automatic user provisioning and group management from identity providers (IdPs) like Okta, Azure AD, or Google Workspace.

Benefits

1. Automatic provisioning: new users are added to groups based on IdP group membership

2. Synchronization: group membership stays in sync with the IdP

3. Deprovisioning: removing users from IdP groups removes them from Foundation groups

4. Reduced manual work: no manual group assignment

How SCIM Integration Works

1. Mapping IdP Groups to Foundation User Groups

Map IdP groups to Foundation user groups:

• IdP Group: engineering-data-team → Foundation Group: Data Engineers

• IdP Group: sales-team → Foundation Group: Sales Users

2. SCIM Group Provisioning Flow

When a SCIM provider sends group information:

IdP Group Update → SCIM API → Foundation User Groups

The SCIM integration should:

1. Receive group information from the IdP

2. Create or update Foundation user groups

3. Map users from IdP groups to Foundation groups

4. Maintain group membership synchronization

3. Implementation Approach

Step 1: Create Foundation User Groups that correspond to IdP groups.

Step 2: Configure your SCIM integration to:

• Map IdP group identifiers to Foundation group identifiers

• Map IdP user identifiers to Foundation user identifiers

Step 3: Handle SCIM Group Events

When SCIM sends group membership updates:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        {
          "value": "user-id-from-idp",
          "$ref": "https://idp.example.com/Users/user-id-from-idp"
        }
      ]
    }
  ]
}

Translate this to Foundation API calls:

POST /groups/members?identifier={foundation_group_id}
{
  "principals": ["foundation-user-uuid"]
}

4. SCIM Group Sync Best Practices

Initial Sync:

1. Fetch all groups from the IdP

2. Create corresponding Foundation groups

3. Map all users to their respective groups

Ongoing Sync:

1. Monitor SCIM webhooks for group changes

2. Update Foundation group membership accordingly

3. Handle user additions and removals

Error Handling:

• If a user doesn't exist in Foundation, create them first (if SCIM user provisioning is enabled)

• If a group doesn't exist, create it or log an error

• Maintain idempotency: repeated operations should be safe

5. Example SCIM Integration Workflow

# Pseudo-code example
def handle_scim_group_update(idp_group_id, user_ids):
    # 1. Map IdP group to Foundation group
    foundation_group_id = get_foundation_group_id(idp_group_id)
    
    # 2. Map IdP user IDs to Foundation user IDs
    foundation_user_ids = [
        get_foundation_user_id(idp_user_id) 
        for idp_user_id in user_ids
    ]
    
    # 3. Update Foundation group membership
    add_users_to_group(foundation_group_id, foundation_user_ids)

6. Role Assignment via SCIM

You can also assign roles to groups based on IdP group attributes:

# Example: Assign roles based on IdP group name
if idp_group_name.startswith("admin-"):
    assign_role_to_group(foundation_group_id, "admin-role-id")
elif idp_group_name.startswith("data-"):
    assign_role_to_group(foundation_group_id, "data-writer-role-id")

SCIM Integration Checklist

• [ ] Create Foundation user groups corresponding to IdP groups

• [ ] Configure mapping between IdP and Foundation identifiers

• [ ] Implement SCIM webhook handler for group updates

• [ ] Handle user provisioning before group assignment

• [ ] Implement error handling and logging

• [ ] Test group synchronization in both directions

• [ ] Set up monitoring for sync failures