Every SCIM attribute explained

In a typical company, user account management becomes increasingly complex as more employees come onboard and require access to an ever-expanding list of software and tools.  

At the Enterprise level, a company can use hundreds of apps every day across their ecosystem, and access to these needs to be centrally managed.

When you create software for enterprise-scale companies, your customer’s IT admins need to provision accounts, give their users access to the right tools, adjust permissions and revoke access when no longer required. This needs to be able to happen regularly - and at scale. 

That’s where SCIM comes in. The SCIM standard lets you exchange identity information across a broad spectrum of services, and standardize the way you communicate with each of them. That standardization becomes essential as you bring on bigger customers who require enterprise-ready user management solutions which are compatible with their existing identity provider (IdP).

Key to this is SCIM’s attributes approach - a JSON-based standard which exposes the specific information your apps need to work with users.

In this article, you’ll learn more about attributes, including how the key attributes work, and how you can use custom attributes to deliver additional functionality.

Note: This guide covers version 2.0 of the SCIM specification.

What Is SCIM and How Does It Work?

The System for Cross-domain Identity Management (SCIM) is an open standard for exchanging user information between apps. SCIM uses a REST API to share information about user identities and attributes. Data is exchanged as JSON or XML. 

Implementing SCIM in your app means that you can communicate user identity and provisioning info with any major identity provider, like Azure AD/Entra ID, Okta or Google Workspace - without having to create a custom implementation tailored to that IdPs particular quirks.

What is a SCIM Attribute and What Can You Use it For?

Like REST, SCIM’s data model is based on resources. A resource object is the basic building block for data exchange. Users and groups are derived from it, as are custom objects. They inherit its properties or attributes.

All SCIM resources include these attributes—bits of information that define a user like their name, email, role, or anything else. 

SCIM attributes allow you to define both users and groups, and store information about them and their relationships. 

You can then programmatically share these attributes with the identity providers your customers use, allowing their IT departments to centrally view, manage and provision users within your app.

This concept is similar to SSO user profile attributes, where an app and an IdP can exchange user data using SAML. The key difference is that, unlike SAML data changes which can only affect a user on login, SCIM attributes can be updated in real-time, regardless of whether the user is still logged in or not. This is a much more secure approach, as your customer's IT team will be able to remove access to data and force a user out of your app immediately, if they needed to.

In SCIM, there are two types of attributes:

• Standard Attributes: Defined in the SCIM specification. These include things like userName, name, emails and phoneNumbers.
  
• Custom Attributes: Defined by you, to enable your customers to store extra details. For example, employeeNumber, costCenter and manager are all attributes you could implement to allow IT admins to more closely track and manage usage of your app by department. In the original schema, an Enterprise User schema extension is used to provide these extras.

With SCIM, you define a "schema" for your users which lists all the standard and custom attributes you want to use. Then, when a new user is created or an existing user is modified, the SCIM API is used to exchange the attribute values.

There’s a core schema included by default with defined users and groups, and over 70 different attributes covering a wide range of common profile properties.

There’s also an extension defining enterprise users. The attributes in these schemas can be used as an example of the kinds of custom attributes you can add yourself, but you should always check if an appropriate core attribute exists before adding your own.

SCIM Attributes: A Breakdown

SCIM includes various kinds of attributes.

Common Attributes to each group/user

Every SCIM resource contains the following attributes:

• id: A unique value issued by the service provider. It must uniquely identify the resource among all those controlled by the service provider.‍
• externalId: An identifier provided by a client for identifying resources within its own system. Must always be issued by the client.
• meta: A collection of data fully controlled by the service provider, including sub-attributes like resourceType, created, lastModified, location and version.

Default Attributes

The SCIM specification includes definitions for User and Group resources. The basic elements of these are defined via attributes.

User Resources

Single-Valued Attributes have a single value.

• userName: The service provider’s identifier for the user. This must be unique among the service providers’ users.
• name: This is a compound value that separates users’ given, middle and family names and also provides honorific prefixes and suffixes.
• displayName: A human-readable version of the name.
• profileUrl: A standard URI pointing to the user’s online profile.
• userType: Specifies the type of user, for example, ‘Contractor’ or ‘Employee’.
• preferredLanguage: This specifies the user’s language. The format used is the same as the ‘Accept-Language’ field in the HTTP specification, for example, en-gb.
• password: The user’s password. This should be hashed if stored. Cleartext values can be used for the purpose of setting or replacing values. You should consult the documentation closely, because handling passwords correctly is obviously security critical.
• locale: This specifies the user’s default location and is used for things like deciding what date format to use and what currency symbol to present. For example, ‘fr’ represents France.
• timezone: The user’s time zone.
• active: A boolean value to determine whether a user is active. How this is used is implementation-dependent.
• title: The user’s title.
• nickName: The user’s nickname.

Multi-Valued Attributes can have multiple values.

• groups: A list of groups. Groups refer to the group resource type. This can be used to implement features like Role Based Access Control (RBAC).
• roles: Roles the user belongs to. Specific roles are not defined by the spec, but you can use Strings like ‘admin’ or ‘manager’. This can also be used to implement RBAC, if you prefer to do that by assigning a string to a user rather than by having an explicitly defined group.
• entitlements: This allows you to store a list of the user’s entitlements. These can be used to determine permissions on a per-user basis.

Groups

SCIM also includes default attributes for groups. This includes just two additional attributes:

• displayName: A required attribute with a human-readable group name.
• members: A list of members the group includes. This can be both users and other groups, allowing you to create nested groups.

Enterprise Users

The SCIM specification also includes the Enterprise User extension. This derives from the User resource type, in the same way that User and Group derive from the base resource object.

Enterprise User attributes include the following:

• employeeNumber / costCenter / organization / division / department: These fields correspond to their real world equivalents.
• manager: The manager attribute is designed to let you represent hierarchical relationships in your data. It includes three fields. value is the SCIM id of the user’s manager. $ref is the URI of the manager resource. displayName is an optional value showing you the manager’s name in a human-readable format.

You can find the full schema reference by clicking here.

Extending SCIM with custom attributes

SCIM allows you to extend its core schema by adding custom attributes. This enables you to capture additional details about users and groups that are specific to your app.

Defining Custom Attributes

To add custom attributes in SCIM, you define an extension schema that specifies your new attributes. This extension schema should include:

• The attribute names.
• A description of each attribute.
• The attribute type (string, integer, boolean, etc.)
• Whether the attribute is multi-valued.
• The mutability of the attribute (readOnly, readWrite, immutable).

For example, you may want to add attributes like:

• workSite: An employee’s work location.
• birthDate: Store your team’s birthdays.
• project: Keep track of what each team member is working on.

These custom attributes would let you represent details in your user data that the core SCIM schema does not cover.

Conclusion

SCIM provides a standardized way to exchange user and provisioning data with any identity provider. The specification includes standard attributes that let you store basic user details, divide users into groups, and conduct RESTful operations using that info.

With custom attributes, you can go further - this makes it simple for your customers’ IT admins to sync custom data that might be useful in your app or hold proprietary user data your app needs to function.

Prefer a done-for-you approach and don’t want to spend days configuring your app to use SCIM? 

Directory Sync by WorkOS allows you to quickly enable SCIM provisioning from all major corporate identity providers with a straightforward, API-based integration.

• Get Started Fast: With SDKs for every popular platform, and Slack-based support, you can implement Directory Sync in minutes rather than weeks.
• Events-based processing: While webhooks are also supported, WorkOS’ 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.

Explore Directory Sync by WorkOS.