Friday, December 7, 2012

WSO2 Charon - Design

Getting started with WSO2 Charon 1.0.0

WSO2 Charon 1.0.0 is released... It is successfully integrated in WSO2 Identity Server 4.0.0 for identity provisioning.

WSO2 Charon is the open source implementation of SCIM specification, and it is made available under Apache 2.0 license.

You can check out my previous blogs which was written around its Milestone 1 release.

In this post, I will provide you step by step guide to play around with it by running the sampels.

Step 1: Obtaining binaries
Two jars are shipped with the distribution. They are:

1. Charon-Core-1.0.0 jar - This is the library that implements the specification and which can be used by any identity management solution to add provisioning capability.

2. charonDemoApp.war - This is the reference implementation of SCIM service provider which uses Charon-Core for SCIM support. It is a RESTful webapp exposing SCIM endpoint which you can host in a servlet container.

You can either obtain these jars from the release distribution or by building the source code.

Step 2: Setting up SCIM service provider
We need two parties to observe identity provisioning capability. i.e: Service Provider and the Consumer. You can use either Charon-Impl hosted in tomcat or WSO2 Identity Server 4.0.0 as the service provider.

My previous blogs explain WSO2 Identity Server's capability as a SCIM service provider. Therefore, here I will explain how to setup Charon-Impl as a SCIM SP.

1. Download tomcat 7.0.11
2. Replace server.xml and tomcat-users.xml [found in tomcat_home/conf] with the attached files here.
4. Place the attached keystore in your file system.
5. Open the server.xml and locate the HTTPS connector. Edit the keystore file location to point to the above keystore.
6. Run the server with sh jpda run.
7. Access http://localhost:8080/ and click on Manager APP.
8. Login with credentials:, 7786htg
9. Upload the
charonDemoApp.war which is obtained from step 1 and access http://localhost:8080/charonDemoApp/ - you should see the Charon home page.

Step 3: Running the samples
1. Compile the source of the charon-samples which is a maven project and found in the release distribution, using the command: maven clean install.
2. Open charon-samples from your IDE.
3 .Go to SampleConstants - here is where all the constants needed to run the samples are hard coded.
          i. Change the KEY_STORE_PATH to your file system location if the default one doesn't work. (This is only needed if you use https as the transport)
          ii. Change the User and Group resource endpoint urls according to your system.
4. Now access "CreateUserSample" class from your IDE. You will see the constants defined at the top - which are the values for the attributes of the user that we are going to create.
5. Run the client. You will see that the user created at server side is returned in JSON format and printed at client side. (You can observe the message on the wire using a tool like tcpmon, as I have shown in a previous post)
6. In the same way, try other samples as well, paying attention to instructions mentioned as comments in the sample code.

Note: You can also run the same set of samples against the SCIM endpoints of WSO2 Identity Server. The configuration that matches with Identity Server, is kept commented out in the SampleConstants file.

That's it.. Enjoy SCIM..! :)