How to write Custom Claim Provider in WSO2 Identity Server

Photo by Christin Hume on Unsplash

In WSO2 Identity Server, we can write custom claim provider as an OSGI service to add new claims to ID token in OpenID Connect protocol. According to the current implementation, we have an extension point to write a custom claim provider which can be plugged in to inject claims into ID Token. Through this blog, I will share how to write a custom claim provider.

How to write custom claim provider

1. Implement the service interface

ClaimProvider interface has two methods. So anyone can implement this interface and publish the service as follows.

First methods can be used when the ID Token request comes from Authorize endpoint and second method can be used when ID Token request comes from the token endpoint.

ClaimProvider service can be implemented in a way that can inject new claims to ID token in Identity Server. This is a convenient way to insert new claims without doing any change in the code base of DefaultIDTokenBuilder. As done in this Custom Claim Provider, you need to simply return a Map which has claim name and value pair.

2. Publish the service.

After implementing the ClaimProvider service, you need to publish the service. Then only OAuth component in IS can find your service and consume it. To publish the service, You can use a Service component.

Deploy the Sample

1. Run the below maven command from custom-claim-provider directory, mvn clean install
2. Navigate to /target directory and copy custom-claim-provider-1.0.0.jar and paste it in the <IS_SERVER_HOME>/repository/components/dropins directory.
3. Restart WSO2 Identity Server.

Testing the flow — Password Grant Type

1. You must first set up the playground sample webapp. in order to try this scenario.
2. Visit the URL http://wso2is.local:8080/playground2/oauth2.jsp to start the application.
3. Enter the following details and click Authorize.

• Authorization Grant Type: Resource Owner
• Client ID: (the client id received at the application registration step in Identity Server)
• Client Secret : (the client secret received at the application registration)
• Resource Owner User Name : (username)
• Resource Owner Password : (password of user)
• Scope: openid (This scope is a requirement to provide user information. Any token without this scope will not be allowed to access user information.)
• Access Token Endpoint: https://localhost:9443/oauth2/ token

4. At this point, the application receives the Access Token and the encrypted ID Token.

Now , by using this service, without changing the existing code, sid claim can be inserted into ID Token. Sample ID token payload which can be generated after deploying the custom-claim-provider is as follows. There we can observe that the injected sid claim has been added to the ID token.

{
  "at_hash": "0W6NbbJyCy3_NMGbcWDlYA",
  "aud": "_O8Sfj0YU2lBpCDVt99x8qsE5hsa",
  "sub": "admin",
  "nbf": 1606837150,
  "azp": "_O8Sfj0YU2lBpCDVt99x8qsE5hsa",
  "amr": [
    "password"
  ],
  "iss": "https://localhost:9443/oauth2/token",
  "exp": 1606840750,
  "iat": 1606837150,
  "sid": "123-1bc-879-uk3"
}

Similarly, there can be so many instances which need to inject new claims for some specific purposes. In that case, you can write custom claim provider OSGI service as explained.

Hope this would be helpful for you!!!