How to define a custom schema for your SCIM Server built with the WSO2 Charon library

Leverage the extensibility of Charon library for your purpose

Did you know that WSO2 Identity Server(IS)- which is a leading open-source IAM solution provider in the market is a SCIM service provider?

Yes, it is. If you check more on WSO2 IS, you will find that SCIM is the main protocol used for identity management in WSO2 IS. The exciting thing here is, SCIM is an open standard for identity provisioning and management, and its widely used in the industry. If you were searching for an IAM solution that supports SCIM, WSO2 IS a good fit for you!😎

High-level overview of SCIM Service Provider architecture of IS

However, I wanted to tell a different story here. While WSO2 IS acts as a SCIM service provider, it has given its SCIM core and protocol implementation as an open-source java library to build your own SCIM service provider too. That is nothing but the Charon Library. If you are a developer who is searching for a Java-based SCIM library for your SCIM server, I know you are thrilled now!🤩 Refer to this blog post for more information on using the Chron library.

<dependency> 
<groupId>org.wso2.charon</groupId>                  <artifactId>org.wso2.charon3.core</artifactId>   <version>4.0.1</version>
</dependency>

Yet the best part is not revealed😶. Charon library supports not only the schemas defined in the standard specification but also has the schema extension capability. Let’s dig into that.

What is SCIM Schema?

In case you are wondering what is SCIM schema, read out my previous blog and continue here. Anyway, I’ll summarize the fact.

• In plain English, the word “Schema” is for “representing a model”. Here also the meaning is the same.
• A schema is a collection of attribute definitions that describe the contents of an entire or partial SCIM resource(User/Group/ etc).
• Represents in JSON format.
• This schema representation includes the attribute definitions for User, Group, and EnterpriseUser resources.

Why schema extension is needed?

If we take User resource in SCIM, the specification has mentioned that the default User resource is built with 2 main schemas.

1. urn:ietf:params:scim:schemas:core:2.0:User - Define the most common set of attributes of a User object.
2. urn:ietf:params:scim:schemas:extension:enterprise:2.0:User - SCIM extension defines attributes commonly used in representing users that belong to, or act on behalf of, a business or enterprise.

These two schemas cover most of the common attributes required to represent a User object, but there could be some custom attributes specific to your business/ solution. To cater to that, SCIM specification has allowed defining extensions.

Charon library also has that schema extension capability for the user resource. Now we are going to check how to do it.

How to define a custom schema in Charon?

There are two options.

Option 1:

• Define the attribute definitions in a file and build the schema using that file.
• When writing that attribute definitions file, the final config should be the definition of the extension.
• Charon method to use: buildUserSchemaExtension in SCIMUserSchemaExtensionBuilder
• NOTE: Only the user schema extension builder is available by default, but you can modify the Charon library to have schema extensions for other resources as well, by extending ExtensionBuilder
• Sample Java code to build schema using this method: (This code snippet only has schema building. You have to add this part to your SCIM server logic.)

• Refer to the code: https://github.com/AnuradhaSK/schema-extension/blob/cea1fa636bea2bb1e599ac9c71c6c45eaa339199/src/main/java/ScimSchemas.java#L29-L35
• Check the file format: https://github.com/AnuradhaSK/schema-extension/blob/main/src/main/resources/custom-schema
• The final config of the file should be the definition of the extension: https://github.com/AnuradhaSK/schema-extension/blob/cea1fa636bea2bb1e599ac9c71c6c45eaa339199/src/main/resources/custom-schema#L572-L586

Option 2:

• Use SCIMCustomSchemaExtensionBuilder in Charon.
• You have to define the extended schema URI first. Here I use "urn:scim:custom:extended:schemas" as the schema URI.
• Then create SCIMCustomAttribute objects for each attribute you need to add to the extended schema. You have to define the default set of attribute properties mentioned in the SCIM schema for an attribute
• Finally, create another SCIMCustomAttribute to represent the extended schema.
• Put all objects into a List and call buildUserCustomSchemaExtension the method in SCIMCustomSchemaExtensionBuilder
• Charon method to use: buildUserCustomSchemaExtension in SCIMCustomSchemaExtensionBuilder
• Sample Java code to build schema using this method: (This code snippet only has schema building. You have to add this part to your SCIM server logic.)

• Refer to the code: https://github.com/AnuradhaSK/schema-extension/blob/cea1fa636bea2bb1e599ac9c71c6c45eaa339199/src/main/java/ScimSchemas.java#L39-L78

That’s it, guys!! I hope you will get the fullest advantage of the open-source SCIM library Charon.👊