Assign Roles in JIT Provisioning — WSO2

A Sample on Assigning Roles to Provisioned Users via Provisioning Handlers

Athiththan Kathirgamasegaran
3 min readJul 7, 2021


Greetings Everyone!!! 👋

Have you ever come across a scenario, where you wanted to assign a set of custom roles (or the Internal roles of WSO2) to provisioned users, but don't have an attribute to perform role-mapping? If yes, then you are at the right place to get a solution for it.

WSO2 API Manager provides a platform to perform federated authentication with external IDPs, including provisioning external users to the Primary User Store of the API Manager. To assign local roles to the provisioned users, it is required to configure a Role Mapping at the Identity Provider level. Let’s assume that our external IDP is not providing any valuable attribute to perform the role mapping in API Manager.

If you are new to Just-In-Time Provisioning concept, take a look at here to get a brief understanding on how it works.

So, in such a scenario, how can we achieve the role assigning to the provisioned users❓

We can extend and implement a custom provisioning handler to assign the roles. During the Just-in-Time provisioning timeframe, a handler named DefaultProvisioningHandler is executed. This contains the implementation related to how to provision the user to the local User store of the API Manager. In this blog, we are going to extend the DefaultProvisioningHandler to achieve our use-case.

Let’s get started!!!

⭐️ The implementations are based on WSO2 API Manager v3.2.0. If you are trying to achieve the same in lower versions, please update the dependencies accordingly.

✋ JIT Provisioning Handler

By default, the API Manager v3.2.0 has an extended version of the DefaultProvisioningHandler called SystemRolesRetainedProvisionHandler. This is used to prevent the deletion of existing roles when a user is re-provisioned to the platform. We are going to extend this a little further, to assign our custom set of roles to the user.

To make it short and simple, attached a Gist with an extended implementation of SystemRolesRetainedProvisionHandler to assign the Internal/subscriber role to all provisioning users

The extension makes sure that all the provisioning users will be assigned with the Internal/subscriber role.

You can also find the complete codebase in the below location

👉 Once the implementations are made, build the project using Maven. You can execute the following command from the root directory of the project to build the JAR

mvn clean install

👉 Then, copy the built JAR artifact from the /target directory and place it inside the <apim>/repository/components/lib directory.

👉 Open the <apim>/repository/conf/deployment.toml and add the following set of configurations to engage our custom provisioning handler

provisioning_handler = "com.sample.handlers.JITRoleProvisioningHandler"

👉 Once, everything is done, perform a server restart to take effect on the changes and to load the classes properly.

Voila!!! 🎉

Now, you can test the scenario by performing a federated authentication flow with an external IDP and provisioning the users to the local User Store of the API Manager.

You can follow one of the following medium blogs to configure SSO with external KMs.

Happy Stacking!!! 😃 👌 ✌️

💡 Bonus Hint

As bonus content, let’s further extend the implementation to assign custom roles based on the External IDPs, that we have configured in the API Manager.

Assume that we have configured the API Manager portals with 2 different external IDPs (example: Okta, and OpenAM). And have a requirement as if one is provisioned from Okta, assign a custom role named okta-role and if another is provisioned from OpenAM, then assign openam-role.

To handle this scenario, we can make use of the attributes parameter of the handle method. This Map contains the name of the IDP that is involved with the federated authentication. So, by extracting those, we can conditionally assign the roles to the users.



Athiththan Kathirgamasegaran

@athiththan11 | GH:athiththan11 | Site Reliability Engineer@WSO2