[Tutorial] How to Secure a Jaggery File by Using Single Sign-On

  • By Sameera Jayasekara
  • 12 Dec, 2014


This sample demonstrates

  • Using SSO to secure a jag file
  • Obtaining the roles of the currently logged in user

We will be performing user-related operations using the classes found in the carbon module here.

For this sample we will be using the UserManager and User classes found under the scripts/user directory.
This sample comes with a wrapper class, which simplifies working with these classes. Refer to the carbon-sample/modules/user-mgt.js.

Note: In order to simplify the sample, we do not consider multi-tenancy.


This sample requires the following WSO2 products:

  1. WSO2 Identity Server (IS) 4.6.0
  2. WSO2 Business Activity Monitor (BAM) 2.4.0


  1. In order to run both IS and BAM you will need to run IS with a port offset.This can be done by altering the offset value found in the IS_HOME/repository/conf/carbon.xml file. For this example we have changed offset value to 5 (Figure 1)

    Figure 1

  2. Next, start the WSO2 Identity Server instance by navigating to IS_HOME/ and typing sh bin/wso2server.sh
  3. Configure a service provider entry for the service provider 'carbonSample' from the IS management console. More information on this can be obtained from: https://docs.wso2.org/display/IS460/Adding+a+Service+Provider.

    Your service provider configuration should look like what’s shown in Figure 2.

    Figure 2

  4. We need to enable SSO for the BAM server. This can be done by navigating to the BAM_HOME/repository/conf/security/authenticator.xml and enabling SSO

    Figure 3

  5. Copy the contents of the resources/jar folder to BAM_HOME/repository/components/dropins directory
  6. Copy the contents of the resources/modules directory to BAM_HOME/modules directory
  7. Copy the carbon-sample folder into the BAM_HOME/repository/deployment/server/jaggeryapps/ directory.
  8. Start the WSO2 BAM server instance by navigating to the BAM_HOME/ and typing sh bin/wso2server.sh

Testing the sample

  1. Navigate to the management console of the BAM server, using https://localhost:9443/carbon/admin
  2. You will be presented with a SSO login screen as indicated in Figure 4

    (username:admin, password:admin)

    Figure 4

  3. After you are logged in, navigate to the sample application: https://localhost:9443/carbon-sample
  4. You will be redirected to the resource page and you would see the following (Figure 5) message

    Figure 5

How does it work?

The sample application has three important files that perform the bulk of the work;

  1. controllers/index.jag
  2. controllers/acs.jag
  3. controllers/resource.jag

Initiating SSO

The index.jag file is responsible for initiating a SSO request. If a user is not logged into the management console, he/she will be prompted to log in.

Handling SSO

The acs.jag is responsible for managing the SSO requests including the login and logout requests. In fact, if we go back to the installation step where we setup the service provided it can be noted that the assertion consumer URL is set to https://localhost:9443/carbon-sample/acs.The IS server will send all SSO-related requests to this controller.

Securing the resources and listing the roles

The resource.jag file is responsible for checking the session for a logged in user and then obtaining the roles.


The User class provides a set of methods to manage user-related activities, such as obtaining the roles of the user. A complete list of available methods is given below:

Available methods

  1. getClaims
  2. setClaims
  3. getRoles
  4. hasRoles
  5. addRoles
  6. removeRoles
  7. updateRoles
  8. isAuthorize

We will be using the getRoles method in the sample.