What are SCIM Groups?
SCIM defines two main resource types — users and groups. SCIM groups are a collection of users that have something in common and play a critical role in role-based access control.
For large enterprises, managing individual access for thousands of employees using hundreds of apps is impractical.
The solution? Group-based access control. Employees are put into access groups based on their role and their permissions. But that’s just step one. These groups have to be pushed to all the company's apps, and they need to be regularly updated as group permissions and memberships change.
That’s where SCIM Groups come in.
SCIM (System for Cross-domain Identity Management) provides a standard way for identity providers and service providers to communicate. It’s a common “language” multiple providers can use to send group updates to your app. This standardization is essential for when you’re integrating with multiple providers, you don’t have to stress about each provider using a completely unique standard.
In this article, you’ll learn more about SCIM groups, how different providers handle groups, why that can be a problem, and how you can avoid any headaches.
What are SCIM Groups?
SCIM defines two main resource types — users and groups. SCIM groups are a collection of users that have something in common. While you may be used to groups being used for things like mailing lists, in SCIM these groups are usually used for role-based access control.
Similar to how it standardizes the user representation, SCIM defines a core schema for representing groups. This schema acts as a template for structuring group data.
What are SCIM Groups used for?
SCIM groups are used to organize users with similar roles and permissions into categories or teams.
However, this is more of a common practice than something SCIM was specifically designed for. The industry uses groups for permissions, not because they are ideal for that, but because groups are the lowest common denominator between the myriad of IdPs and SPs.
They simplify user management by making it easier for your customer’s IT admins to assign rights, roles, and responsibilities across different apps or services. A user added to a group is automatically provisioned to the apps, tools, and resources allocated to that group, and automatically loses access if they’re removed from the group.
What are the main SCIM Groups attributes?
Every SCIM resource contains:
- id: A value issued by the service provider to uniquely define the resource.
- externalId: An identifier provided by a client to identify the resource within their own system.
- meta: A collection of metadata from the service provider that describes the resource e.g. resourceType, created, location, and version.
In addition to these attributes, the SCIM protocol defines two default attributes for groups:
- displayName: A human-readable name for the group like “marketingTeam” or “managers”. This attribute is required.
- members: A list of members of the group.
What is a custom SCIM schema and when should you use one?
Imagine you’re developing an app that needs to manage access to sensitive records, where permissions are not only role-based but also contingent on attributes like “RiskLevel”, and “CertificationStatus”.
While SCIM's core schema supports basic group and user roles, it does not support these attributes. However, it lets you extend the core schema with custom group attributes like these, to better match your app’s permission model.
Here are some scenarios where’d use a custom SCIM group:
- When standard SCIM attributes do not fully capture the specific requirements of your app. For example, if you need to track group attributes like, project codes, or that are not part of the standard SCIM schema.
- To provide additional functionalities within your application that rely on group information. This could include custom access control policies, reporting features, or group categorization that goes beyond what standard attributes offer.
Only opt for custom group attributes when it's absolutely necessary, and there's no standard attribute that meets your needs. This is because, when you customize your schema, you make interoperability with IdPs that use the predefined attributes harder.
How do you create a Custom SCIM Group?
To create a custom SCIM group, you need to define an extension schema that includes the additional attributes you want to add. Here’s how it’s done:
First, determine which additional attributes your group needs. For example, isArchived and clearanceLevel. Second, check the SCIM specification to see if those attributes are part of an existing group schema, like the Enterprise User Schema Extension
For each attribute you can specify:
- The attribute names (minimumIAL, clearanceLevel, etc).
- A description of each attribute.
- The attribute type (string, integer, boolean, dateTime etc.) See more attribute types.
- The mutability of the attribute (readOnly, readWrite, immutable).
Here’s a sample SCIM group schema with custom attributes:
When referencing this schema, you must include both the core attributes and these custom attributes.
The core attributes are defined at the root level of the schema and the custom attributes are nested under a namespace. The namespace is the schema id (urn:example:params:scim:schemas:extension:group:2.0:GroupExtension) and is what uniquely identifies the extension schema.
Here’s an example of a group referencing the group extension:
When adding attributes to either a SCIM user or Group resource, always cross-check to ensure the attributes you add aren’t already present in the core SCIM schema or extensions.
What to watch out for: SCIM Group fragmentation
SCIM defines a standardized schema for group attributes which, in theory, allows different identity providers and applications to interact in a consistent manner.
Unfortunately in practice, this is usually not the case.
Here’s why: Different identity providers interpret the protocol in slightly varied ways so the implementation can differ from provider to provider.
This is particularly evident in how IdPs handle users' deactivation, suspension, and reactivation via SCIM. Some will delete the user, others will only suspend the user if they’re not part of a group, and others will send a request to set the user as no longer active.
Worse still, the user’s permissions and access rights may remain active when they should not, and these changes may not be communicated to your app.
So, why is this a problem?
To start with, it adds a lot of complexity to your implementation especially if you’re supporting multiple identity providers. You’ll need logic to handle multiple types of requests for the same admin action.
For instance, take user suspension. With different IdPs handling it differently, you’ll have to process requests with unique logic and flows according to each provider. You can imagine what happens when you’re dealing with 10-20 providers.
How each major IdP handles SCIM groups
Okta
In Okta, if a user is suspended (rendered inactive) and during their suspension, there are changes in their group memberships, Okta doesn’t communicate these changes to your app if the same group is used for assignment and push.
As a result, when the suspended user is eventually reactivated, the changes in group memberships will not be reflected in your app and they may end up having access permissions they shouldn’t.
Microsoft Entra/Azure AD
In Microsoft Entra, a user account is not suspended if the user is still a member of any provisioned groups. Users may retain access permissions they shouldn’t have.
Onelogin
When a user is removed from OneLogin, they are deleted rather than suspended. This means if they are re-activated at a later date, they are treated as new users.
You’ll have to provision a new account for the user — any permissions or access rights associated with their previous accounts will have to be re-provisioned which, if not done correctly, can cause users to end up with excess or limited permissions.
JumpCloud
When a group is deleted in JumpCloud, all users in the group will be disabled unless they’re associated with another active group. You can have users retaining permissions they shouldn’t have because they’re still active in another group. To completely deactivate users, admins need to remove them from each group they’re a member of — you’ll need to process all of these requests on your end.
The above inconsistencies are disastrous for security and compliance. If a user remains part of a group they’re not supposed to be a part of, you risk exposing protected resources to unauthorized users or infringing on compliance regulations and internal policies.
Worst of all, the varying implementations from each IdP mean there’s no standardized protocol for resolving issues — which makes it challenging to troubleshoot when things go wrong.
Next steps
Clearly, there are a lot of discrepancies in group behaviors among identity providers.
These inconsistencies not only introduce a lot of complexities in your implementation (you have to handle different requests for the same IT admin action) but can also cause substantial security risk.
Directory Sync by WorkOS solves this issue by providing a more unified and secure SCIM provisioning solution. Directory Sync provides a simple user provisioning and deprovisioning API with SCIM support for every major identity provider on the market. What’s more, WorkOS automatically handles each provider’s intricacies and quirks, using an ordered, real-time Events API to pass requests to your app and smooth over any security issues from mis-provisioned groups.
- Get started fast: With SDKs for every popular platform, and Slack-based support, you can implement SCIM in minutes rather than weeks.
- Events-based processing: While webhooks are also supported, WorkOS’ unique Events API means every SCIM request is processed in order, and in real-time. You’ll never miss a provisioning request again.
- Pricing that makes sense: Unlike competitors who price by monthly active users, WorkOS charges a flat rate for each company you onboard — whether they’re syncing 10 or 10,000 users with your app.