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 catalina.sh jpda run.
7. Access http://localhost:8080/ and click on Manager APP.
8. Login with credentials: hasini@wso2.com, 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..! :)

Implementing SCIM with WSO2 Charon - Part III

In this post, lets look at how to implement few use cases of SCIM with WSO2 Charon.
You may need to refer to my previous posts on SCIM and Charon to get an overview of them.

Being the third post on Charon, lets continue looking at it in the top down approach.

Part II described the composition of Charon-Impl. which is the SCIM service provider reference implementation shipped with Charon. It is a Apache Wink based webapp that utilizes Charon-Core and Charon-Utils to expose a SCIM REST API for identity provisioning operations.

This post will demonstrate the following capabilities of Charon according to SCIM spec.

1). Create user
2). Create group
3). List Users

Setting up SCIM Service Provider with Charon-Impl:

Download CharonDemoApp from M1 Distribution and deploy it in an application server like Apache Tomcat and start the server.
As shown in the diagram of the part-II post, User Resource and Group Resource are now exposed based on Apache Wink JAX-RS implementation, via following URLS.

• User Resource: http://localhost:8080/charonDemoApp/scim/Users
• Group Resource: http://localhost:8080/charonDemoApp/scim/Groups

Sample use cases:

1. Creating a user.. 
This demonstrates how a SCIM consumer creates (provision) a User in SCIM service provider via a REST call in which User attributes are carried as a JSON encoded string.

Client code :  SCIM client uses the previously registered credentials to authenticate the request.

package org.wso2.charon.samples.user.sample01;

import org.apache.wink.client.ClientConfig;
import org.apache.wink.client.ClientWebException;
import org.apache.wink.client.Resource;
import org.apache.wink.client.RestClient;
import org.apache.wink.client.handlers.ClientHandler;
import org.wso2.charon.core.client.SCIMClient;
import org.wso2.charon.core.exceptions.CharonException;
import org.wso2.charon.core.objects.User;
import org.wso2.charon.core.schema.SCIMConstants;
import org.wso2.charon.samples.utils.CharonResponseHandler;
import org.wso2.charon.samples.utils.SampleConstants;
import org.wso2.charon.utils.authentication.BasicAuthHandler;
import org.wso2.charon.utils.authentication.BasicAuthInfo;

public class CreateUserSample {

    //user details
    public static final String USER_NAME = "hasinig";
    public static final String EXTERNAL_ID = "hasini@gmail.com";
    public static final String[] EMAILS = {"hasini@gmail.com", "hasini@wso2.com"};
    public static final String DISPLAY_NAME = "Hasini Gunasinghe";
    public static final String PASSWORD = "dummyPW";
    public static final String LANGUAGE = "Sinhala";
    public static final String PHONE_NUMBER = "9077657623";

    public static void main(String[] args) {

        try {
            //create SCIM client
            SCIMClient scimClient = new SCIMClient();
            //create a user according to SCIM User Schema
            User scimUser = scimClient.createUser();
            scimUser.setUserName(USER_NAME);
            scimUser.setExternalId(EXTERNAL_ID);
            scimUser.setEmails(EMAILS);
            scimUser.setDisplayName(DISPLAY_NAME);
            scimUser.setPassword(PASSWORD);
            scimUser.setPreferredLanguage(LANGUAGE);
            scimUser.setPhoneNumber(PHONE_NUMBER, null, false);
            //encode the user in JSON format
            String encodedUser = scimClient.encodeSCIMObject(scimUser, SCIMConstants.JSON);
            //create a apache wink ClientHandler to intercept and identify response messages
            CharonResponseHandler responseHandler = new CharonResponseHandler();
            responseHandler.setSCIMClient(scimClient);
            //set the handler in wink client config
            ClientConfig clientConfig = new ClientConfig();
            clientConfig.handlers(new ClientHandler[]{responseHandler});
            //create a wink rest client with the above config
            RestClient restClient = new RestClient(clientConfig);
            //create resource endpoint to access User resource
            Resource userResource = restClient.resource(SampleConstants.USER_ENDPOINT);

            BasicAuthInfo basicAuthInfo = new BasicAuthInfo();
            basicAuthInfo.setUserName(SampleConstants.CRED_USER_NAME);
            basicAuthInfo.setPassword(SampleConstants.CRED_PASSWORD);

            BasicAuthHandler basicAuthHandler = new BasicAuthHandler();
            BasicAuthInfo encodedBasicAuthInfo = (BasicAuthInfo) basicAuthHandler.getAuthenticationToken(basicAuthInfo);


            //TODO:enable, disable SSL. For the demo purpose, we make the calls over http
            //send previously registered SCIM consumer credentials in http headers.
            String response = userResource.
                    header(SCIMConstants.AUTHORIZATION_HEADER, encodedBasicAuthInfo.getAuthorizationHeader()).
                    contentType(SCIMConstants.APPLICATION_JSON).accept(SCIMConstants.APPLICATION_JSON).
                    post(String.class, encodedUser);

            //decode the response
            System.out.println(response);
        } catch (CharonException e) {
            e.printStackTrace();  //To change body of catch statement use File | Settings | File Templates.
        } catch (ClientWebException e) {
            System.out.println(e.getRequest().getEntity());
            System.out.println(e.getResponse().getMessage());
            e.printStackTrace();
        }
    }
}

Request-Response: Please click on the below image to see it in full size. After successful creation of the user;
- service provider responds with 201-Created response code and
- includes newly created user in response body.
- Representation in response contains an additional attributes 'id', 'created date', 'last modified date' etc which is assigned by the SP and
- the "Location" header contains the unique URI of the created user resource.

2. Create Group..(From SCIM spec)

Following request/reponse is captured when creating a group with two exisiing users in the system.

Request-Response: Please click on the below image to see it in full size.
Server responds with 200 OK including group resource in the body encoded in JSON.

3. List Users
Following request/response illustrates a SCIM consumer call to list all the users.
Server responds with two user entries existing in its user store.

Note:

1. Libraries for sample client code:
You can find the required libraries to run the WSO2 Charon samples from here.
2. Sample source code can be found in the M1 distribution linked above.

3. As illustrated by above sample use case, SCIM consumer will be able to perform identity provisioning operations with any SCIM service provider in a unified way by just changing the resource URLs - which avoids the need of developping multiple connectors to integrate with different cloud providers.