SCIM Group Management

Map SCIM groups to Portkey workspaces and roles without naming restrictions.

SCIM Group Management

Portkey now supports flexible group-to-workspace mapping, allowing you to provision groups from your identity provider (Okta or Azure Entra) with any naming convention and then map them to Portkey workspaces and roles directly from the Portkey Control Plane.

---

Overview

Previously, SCIM group provisioning required groups to follow a specific naming format (ws-{group}-role-{role}) to automatically map to Portkey workspaces. This restriction has been removed.

With the new group management feature, you can:

• Provision groups with any name from your identity provider
• Map groups to workspaces after provisioning
• Assign roles to all members of a group
• Manage mappings directly from Portkey Control Plane
• Configure custom prefix and separator for automatic group-to-workspace mapping (optional)

---

Workflow

The group mapping process follows these steps:

1. Provision the group from your identity provider (Okta or Azure Entra)
2. Map the group to a Portkey workspace and assign a role from Portkey Control Plane
3. Users are automatically assigned to the workspace with the specified role when added to the group

Groups must be provisioned from your identity provider first before they can be mapped in Portkey. You cannot map a group that hasn’t been provisioned yet.

---

Provisioning Groups from Identity Provider

Before mapping groups in Portkey, ensure the groups are provisioned from your identity provider.

For Okta Users

1. Navigate to your Okta application settings
2. Go to the Push Groups tab
3. Push the groups you want to map to Portkey
4. Verify the groups appear in Portkey after provisioning

For detailed instructions, refer to the Okta Group Provisioning section.

For Azure Entra Users

1. Navigate to your Azure Entra application
2. Go to the Provisioning page
3. Ensure groups are assigned to the application
4. Verify the groups are provisioned to Portkey

For detailed instructions, refer to the Azure Entra Group Provisioning section.

---

Configuring Group Naming Format (Optional)

If you prefer automatic group-to-workspace mapping based on naming conventions, you can configure a custom prefix and separator to match your organization’s group naming format.

Default Format

By default, Portkey expects groups to follow this format:

• Format: ws-{Workspace}-role-{admin,manager,member}
• Prefix: ws
• Role Separator: -role-

Example:

• ws-Sales-role-admin
• ws-Engineering-role-manager
• ws-Marketing-role-member
• ws-Complex Workspace-role-admin

Custom Configuration

You can configure your own prefix and separator to match your group naming conventions:

1. Navigate to Admin Settings > Authentication Settings > SCIM Provisioning in Portkey Control Plane
2. Find the Pattern Based SCIM Grouping section
3. Configure the following fields:
   • Workspace Prefix: The prefix used in your group names (e.g., ws-, portkey-, org-)
   • Role Separator: The character used to separate the role from the workspace (e.g., -role-, _role_, .role.)
4. Click Save to apply the configuration

The format will be: {prefix}{Workspace}{role_separator}{admin,manager,member} Once configured, groups matching this format will automatically map to workspaces with the specified role, without requiring manual mapping in the SCIM Mappings List.

---

Mapping Groups to Workspaces

Once groups are provisioned from your identity provider, you can map them to Portkey workspaces:

1. Navigate to Admin Settings > Authentication Settings > SCIM Provisioning in Portkey Control Plane
2. Find the SCIM Mappings List section
3. Click on the Add New Mapping button
4. Select the appropriate fields from the dropdowns:
   • SCIM Group Name: The name of the group from your identity provider
   • Portkey Workspace: The workspace to map the group to
   • Role: The role to assign to the group members
5. Click Save to complete the mapping

The role you select will be applied to all members added to the group. All users in the group will have the same role in the mapped workspace.

---

Supported Roles

Role	Description
Admin	Full workspace access with management capabilities, including workspace settings and member management
Manager	Can manage workspace resources, view analytics, and manage members
Member	Standard workspace access with read and write permissions to workspace resources

A role must be selected when mapping a group. The mapping cannot be saved without selecting a role.

---

Group-Based User Provisioning

By default, when a SCIM group update includes an archived (deprovisioned) user, Portkey will not reactivate that user. This is because some identity providers (like Okta) send the full member list on every group update, which could unintentionally reactivate users that were removed.

If your identity provider (such as JumpCloud) expects group membership updates to reactivate archived users, you can enable the group_based_user_provisioning setting.

Enabling Group-Based User Provisioning

1. Navigate to Admin Settings > Authentication Settings > SCIM Provisioning in Portkey Control Plane
2. Enable the Group-Based User Provisioning toggle
3. Click Save

When enabled:

• Archived users will be automatically reactivated when they are included in a SCIM group membership update
• The user will be added back to the workspace mapped to that group with the configured role

Only enable this setting if your identity provider requires it. Enabling this with providers like Okta that send full member lists on every update may cause unintended user reactivations.

---

Managing Group Mappings

Viewing Existing Mappings

You can view all group-to-workspace mappings in the SCIM Mappings List section of SCIM Provisioning settings. Each mapping displays:

• Group name (from identity provider)
• Mapped workspace
• Assigned role

Removing Mappings

To remove a group mapping:

1. Navigate to the SCIM Mappings List section
2. Find the group mapping you want to remove
3. Click on the Delete icon next to the mapping

Removing a group mapping will not remove users from the workspace.

---

User-Based Group Management Mode (AirGapped only)

By default, group memberships are managed through the SCIM /Groups endpoint. For identity providers that manage group assignments through user attributes (e.g., Azure Entra), you can enable User-Based Group Management Mode.

When this mode is enabled:

• Group memberships can be managed via the SCIM /Users endpoint (create, update, and patch operations)
• The groups attribute on SCIM user responses includes the user’s current group memberships
• Group member operations on the /Groups PATCH endpoint are skipped to avoid conflicts

Enabling User-Based Group Management

Set the following environment variable on your backend deployment:

SCIM_MEMBERSHIP_USER_MODE=ON

This mode is useful when your identity provider pushes group membership updates as part of user provisioning rather than group provisioning operations.

---

Benefits

The flexible group management feature provides several advantages:

• No naming restrictions - Use any group naming convention that fits your organization
• Flexible mapping - Map groups to workspaces after provisioning
• Simplified management - Manage all mappings from Portkey Control Plane
• Role consistency - All group members automatically receive the same role
• Custom naming format - Configure prefix and separator to match your existing group naming conventions for automatic mapping
• User-based management - Optionally manage group memberships via the /Users endpoint for providers that require it

---

Support

If you encounter any issues with group management or need assistance with mapping groups to workspaces, please contact our support team at [e-mail].