Let’s understand SCIM 2.0 — Core Schema
🤔 What is SCIM?
According to the specification SCIM means
The System for Cross-domain Identity Management (SCIM) specification is designed to manage user identity in cloud-based applications and services in a standardized way to enable interoperability, security, and scalability.
In simple terms,
SCIM is a standardized way of representing users, groups, and any other related resources and a standard way to manage in other words do CRUD (Create, Retrieve, Update, and Delete)operations on them.
Thus, the main objective of SCIM is:
- Simplify user provisioning.
- Reduce the cost and complexity of user management operations.
Even though SCIM means about a standard way of representing user data and managing them, it is not meant to replace the existing system for user management. SCIM acts as a standard interface on top of the existing systems. The underlying userstore can be either LDAP, SQL Database, NoSQL database, or whatever.
SCIM 2.0 comprises of the following three main specifications and some extensions:
You can understand the user scenarios where SCIM is required by referring to RFC7642 and https://wso2.com/library/article/2017/10/system-for-cross-domain-identity-management-scim/
In this blog, I’m exploring the SCIM core schema in a simpler way which is defined in RFC7643.
In simple English, the word “Schema” is for “representing a model”. Here also the word’s meaning remains the same. RFC7643 is about users, groups, and other resource types representation. Every data representation in SCIM is defined in JSON.
Going forward we need to know what is referred to as SCIM service provider, and client.
SCIM service provider — An HTTP web application that provides identity information via the SCIM protocol. WSO2 Identity Server is an example of the SCIM service provider. It stores the identity information of users and it has the capability to provide this information via SCIM protocol if some party requested them.
Client — The party which initiates the SCIM HTTP request to the target service provider in order to manage identity data maintained by the service provider.
📌 Resource
SCIM 2.0 is based on an object model. Resource is considered as the common denominator, and all other objects are derived from it.
As you can see below, everything that can be managed by the SCIM service provider is a resource.
- Resource is a JSON object.
- It comprises of one or more attributes.
- Those attributes can belong to one or more schemas (Next section defines what is a schema)
- eg: A user resource contains the attributes defined in both of the following schemas.
urn:ietf:params:scim:schemas:core:2.0:User
urn:ietf:params:scim:schemas:extension:enterprise:2.0:UserLet’s imaging about user profile. It is one of the main resources when comes to user management. Thus User is a Resource in SCIM. Any user profile in a system has a name, address, telephone numbers, emails, etc. Those common set of attributes are general for any user profile maintained by any system. A collection of such common user attributes is known as the User resource. However, there can be situations where maintaining system/application-specific attributes for users (eg: users login devices for the application). By considering the fact, SCIM introduces the EnterpriseUser as an extension for User resource. EnterpriseUser is an extension of User attribute which has a collection of attributes specific to applications.
Moreover, id, externalId, meta are three common attributes which are included in any SCIM resource except the resources such as “ServiceProviderConfig”, “ResourceType” which are used to discover about SCIM service provider and other service provider discovery related resources.
id — A unique identifier for a SCIM resource as defined by the service provider. It is generating by the SCIM service provider when creating the resource. It is a REQUIRED Attribute.
externalId — A String that is an identifier for the resource as defined by the provisioning client. In other words identifier of the original source where the user data is taken from (eg: database id where the user is taken by provisioning client). It is an OPTIONAL attribute.
meta — Common metadata for a resource. They are generated by the service provider. Eg: last modified time, created time, location of the resource. It is a REQUIRED Attribute.
📌 Schema
- Schema is a collection of attribute definitions that describe the contents of an entire or partial resource.
- Represents in JSON format.
- This schema representation includes the attribute definitions for User, Group, and EnterpriseUser resources.
📌 Attribute Definition
Attribute definition means how we define attributes. What are the characteristics of attributes? SCIM attributes definitions have the following details.
o "name" o "description" o "type" o "multiValued" o "required" o "canonicalValues"
o "caseExact"
o "mutability"
o "returned"
o "uniqueness"
o "subAttributes" (If resource type is COMPLEX)
I’ll take one attribute definition from here to explain further. The following is the definition of the userName attribute of User resource.
name — This is a unique name that used to describe the attribute.
type — Which type of details can be stored as values for the attribute. A user’s userName needs to be a “string”.
multiValued — Whether more than one value can be stored as attribute values. Since a user can have only one username, here multiValued is false. Email is a multiValued=true attribute because a user can store more than one email.
description — A detailed explanation about the particular attribute in a human readable language. Here it defines what is meant by userName.
required — Mention whether this attribute is mandatory for the resource or not. If the attribute is a mandatory one required = true. If it is optional required = false. Here userName is required= true attribute because every user must have a username.
caseExact — Whether the stored value in the attribute is case-sensitive or not. If it is case-sensitive caseExact=true, else caseExact=false.
mutability — Whether the attribute values are modifiable. Here userName attribute’s mutability is readWrite. It means the User’s username can be read from the service provider and as well as write to the service provider. An attribute like “password” has mutability=writeOnly . The user can modify the password, but after that, the value can’t be seen in the plain text. It will be encrypted. There are examples for readOnly attributes too. eg: id , The unique id generated by the service provider can’t be modified by the clients.
returned — Whether the attribute should be returned to the requested party in the SCIM response body. Retuned characteristics can have one of the following values.
always — Always return in the SCIM response (eg: id)default — Return if the attribute has a value/ if the attribute is non-empty (eg: name)request — The attribute is returned in response to any PUT,
POST, or PATCH operations if the attribute was specified by the client. Returned only if specified in the "attributes" parameternever — Attribute will never return in the SCIM response (eg: password)
uniqueness — Whether there can be more than one resource consisting of the same value for this attribute. The userName attribute’s uniqueness=servermeans, there can be only one user with a particular username in the SCIM endpoint. Ifuniqueness=none means there can be more than one resource with the same value for the particular attribute. If uniqueness=global no two unique resources should be residing in the same server.
canonicalValues and subAttributes are not defined in userName attribute.
subAttributes — This is required only if the particular attribute’s type=COMPLEX. If an attribute can store objects as its values, these objects contains one or more attributes. Those subAttributes’ definitions should be come as the subAttributes. eg: name of the User. There are subattributes such as givenName, familyName etc.
canonicalValues — A collection of suggested canonical values that MAY be used. eg: work, home, other are canonical values for type sub-attribute of email attributes.
📌 Attributes
When you come here, all the big things are known. We have learned how an attribute is defined, how a schema is defined with a collection of attribute definitions, how a resource is created with multiple attributes.
Let’s see how we can categorize the attributes of a resource.
We can categorize attributes based on their cardinality (i.e based on multiValued characteristic ), and also based on the type characteristic. The following chart illustrates the classification based on cardinality and then type.
Based on cardinality:
- Singular attribute — The attribute can contain at most one value (0..1)
- Multivalued attribute — The attribute can contain at most “n” values (0..n)
Based on type:
- Simple attribute — Singular or Multivalued attribute whose value is a primitive.
eg: strings, integers can be the attribute values. - Complex attribute —Singular or Multivalued attribute whose value is a composition of one or more simple attributes.
eg: Complex objects
In the above chart, I have provided examples for each category using User Resource.
Singular — Simple Attribute: userName of the user is an example.
- User should have only one username -> Thus, it is singular.
- The value of the username should be a string -> Thus, it is simple.
Singular — Complex Attribute: name of the user is an example.
- User should have only one name -> Thus, it is singular.
- But, the name is stored as a collection of subattributes such as givenName, familyName, formattedName, etc. -> Thus, it is complex.
Multi-valued — Simple Attribute: In the core schema of user resource doesn't contain an example for this category, but this type of attributes can be defined in the EnterpriseUser extension. Here I have created an attribute named devices in EnterpriseUser. It will be used to track the names of the devices which the user uses to login into the application.
- Users can use mobile phones, laptops, or more than one device to log into the application -> Thus, it is multi-valued.
- Here device name is stored as a string (a primitive value)-> Thus, it is simple.
Multi-valued — Complex Attribute: emails of the user is an example.
- Users can have more than one email address such as home email, personal email, work email, etc -> Thus, it is multi-valued.
- In SCIM, email addresses are not stored as list of strings. It stored as an object. The object comprises of email address type (home/work/other), email address as the value, and an attribute called “primary” which is used to track the user’s primary email among the given set. -> Thus, it is complex.
There is another separation for attributes as follows.
Common attributes: Attributes that are part of every SCIM resource, regardless of the value of the “schemas” attribute present in a JSON body. These attributes are not defined in any particular schema but should be assumed to be present in every resource.
Core attributes: The list of valid attributes is specified by the resource’s resource type “schema” attribute. These attributes sit at the top level of the JSON object together with the common attributes.
Extended attributes: Attributes are specified by the resource’s resource type “schemaExtensions” attribute. extended attributes are kept in their own sub-attribute namespace identified by the schema extension URI.
The following is a minimal representation of the User resource with the separation of common, core, and extended attributes.
Hey!! That’s all👏. Hope you get a basic understanding of SCIM core schema. You can read RFC7643 for further details
Will see you with another story of the SCIM series. Stay Tuned👊.
Next article of the series: How to add SCIM Extended Attributes in WSO2 Identity Server
