What are SCIM Groups?

Managing individual access for thousands of employees using hundreds of apps is impractical for enterprises. But even with group-based access control, companies still need to sync groups across all their apps and keep them updated as roles change.

That’s where SCIM Groups come in. SCIM standardization automates the syncing process and reduces compatibility issues between systems.

In this article, you’ll learn about:

• What SCIM Groups are and what role they play in access management
• How different providers handle Groups and why that can be a problem
• How you can avoid compatibility headaches between providers

Let’s start by explaining what SCIM Groups are.

What are SCIM Groups?

SCIM (System for Cross-domain Identity Management) defines two main resource types: users and groups. SCIM groups are collections of users with shared attributes or roles. While you may be used to groups for things like mailing lists, in SCIM, these groups are usually used for role-based access control.

Like standardizing 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 organize users with similar roles and permissions into categories or teams. 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 provided with the apps, tools, and resources allocated to that group and automatically loses access if they’re removed from the group.

However, this use case is more of a common practice than something SCIM was explicitly 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.

What are the main SCIM Group attributes?

Every SCIM resource contains:

• id: A value issued by the service provider to uniquely define the resource.
• externalId: An identifier a client provides to identify the resource within their system.
• meta: A metadata collection 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:

1. displayName: A human-readable name for the group like “marketingTeam” or “managers”. This attribute is required.
2. members: A list of members of the group.

What is a custom SCIM schema and when should you use one?

If your app requires specific attributes beyond those provided by the standard SCIM schema, you can create a custom SCIM schema. For instance, if your app's permissions depend on attributes like “RiskLevel” or “CertificationStatus,” you can extend the core schema to capture these details.

Consider using a custom schema in situations where:

• Standard attributes don’t meet your needs: For example, if you need to track project codes or other identifiers not covered by default SCIM attributes.
• Your app relies on additional group information for functionality: Custom attributes can support complex access control policies, reporting, or group categorization.

Only opt for custom group attributes when necessary and no standard attribute meets your needs. Extending the schema can complicate interoperability with IdPs that rely on predefined attributes.

How to create a custom SCIM Group

To create a custom SCIM group, you must define an extension schema that includes the additional attributes you want to add.

First, determine which additional attributes your group needs. For example, you might want isArchived and clearanceLevel. Second, review the SCIM specification to ensure these attributes aren’t already part of an existing group schema, such as the Enterprise User Schema Extension.

Then, specify each attribute. For each, you can define the following:

• The attribute names (e.g., minimumIAL, clearanceLevel, etc).
• A description of each attribute.
• The attribute type (e.g., string, integer, boolean, dateTime, etc.) See more attribute types.
• The attribute's mutability (e.g., readOnly, readWrite, immutable).

Here’s an example of a custom SCIM group schema with added attributes:

{
  "id": "urn:example:params:scim:schemas:extension:group:2.0:GroupExtension",
  "name": "GroupExtension",
  "description": "Custom extension schema for Groups"
  "attributes": [
    {
      "name": "clearanceLevel",
      "type": "string",
      "description": "The clearance level associated with the group.",
      "mutability": "readWrite"
    },
    {
      "name": "isArchived",
      "type": "boolean",
      "description": "The group's current status.",
      "mutability": "readOnly"
    }
  ]
}

You must reference core SCIM and your custom attributes when using a custom schema. Core attributes appear at the root of the schema, while custom attributes are nested under a namespace, which is the schema ID (e.g., urn:example:params:scim:schemas:extension:group:2.0:GroupExtension). This namespace uniquely identifies your extension schema.

Here’s an example of a group referencing the custom group extension:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group", "urn:example:params:scim:schemas:extension:group:2.0:GroupExtension"],
  "id": "group-unique-id",
  "displayName": "Project Team Alpha",
  "members": [
	{
         "value": "2819c223-7f76-453a-919d-413861904646",
         "$ref":
   "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
         "display": "Babs Jensen"
       },
       {
         "value": "902c246b-6245-4190-8e05-00816be7344a",
         "$ref":
   "https://example.com/v2/Users/902c246b-6245-4190-8e05-00816be7344a",
         "display": "Mandy Pepperidge"
       }
],
  "urn:example:params:scim:schemas:extension:group:2.0:GroupExtension": {
    "clearanceLevel": "secret",
    "isArchived": "false"
  }
}

Watch out for SCIM Group fragmentation

As mentioned, SCIM defines a standardized schema for group attributes, which, in theory, allows different identity providers and applications to interact consistently.

Unfortunately, this is usually not the case in practice.

Here’s why: SCIM implementations usually differ from provider to provider since different identity providers interpret the protocol differently.

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?

It adds a lot of complexity to your implementation, especially if you’re supporting multiple identity providers. You’ll need logic to handle multiple 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 dealing with 10-20 providers.

How major IdP handle SCIM Groups

Okta

In Okta, if a user is suspended (rendered inactive) and their group memberships change during their suspension, 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 have access permissions they shouldn’t.

Microsoft Entra (formerly 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.

Related read: Active Directory SCIM: Can you sync Active Directory users and groups with SCIM?

OneLogin

Users who are removed from OneLogin are deleted rather than suspended. This means if they are re-activated later, 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 will be disabled unless associated with another active group. Users can retain 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 in a group they’re not supposed to be in 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 risks.

Directory Sync by WorkOS solves this issue by providing a more unified and secure SCIM provisioning solution. With a single API-based integration, you can connect to any SCIM-compliant provider in the market within minutes.

• 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.
• Avoid the back-and-forth: WorkOS’s Admin Portal takes the pain out of onboarding your customers’ IT teams and configuring your app to work with their identity provider.
• 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.

Sign up for WorkOS today, and start selling to enterprise customers tomorrow.

‍