Thursday, April 7, 2016

Passive STS (WS Federation) with WSO2 Identity Server 5.0.0 : A step by step guide

This blog post will guide you step by step to configure WSO2 Identity Server’s Passive STS. Please note that I am using our sample client application here for testing. The steps to be followed starting with downloading the WSO2 Identity Server will be described here.

Step 1 : Installing Product and the Service Pack 1

1. Create a directory in your local machine.
2. Download WSO2 IS 5.0.0 to and extract to the created directory.
3. Download Service Pack 1 [ ] and extract to the same above directory.
4. Install the service pack
The below steps will guide you to install the Service pack 1 in a fresh WSO2 IS 5.0.0 pack. If you need to install the service pack in the production environment where WSO2 IS is already running please refer the documentation on Installing the Service Pack in  production environment and follow the steps described there.

Installing the service pack in a fresh identity Server : 

Go to WSO2-IS-5.0.0-SP01 directory (will be referred as <SP_HOME> hereafter in this documentation) through command line.
Run Service pack installation script.

On Linux/Unix: $ sh
             On Microsoft Windows: \> install_sp.bat

Navigate to bin folder of wso2is-5.0.0 directory (  wso2is-5.0.0 directory will be referred as <IS_HOME> here after in this documentation) and start the server.

On Linux/Unix: $ sh -Dsetup
On Microsoft Windows: \> wso2server.bat -Dsetup

Open the <IS_HOME>/repository/logs/patches.log file and look for the following line. If you find it, that means the service pack has been applied successfully.
INFO {org.wso2.carbon.server.util.PatchUtils} - Applying - patch1016

Step 2 : Configure the Client application

Please note that in this section Sample client provided for WSO2 IS to demonstrate the configuration steps is used to describe the steps here. You can use your own client application and do the configuration steps accordingly as like below.

IdpUrl        :     e.g. https://localhost:9443/passivests
realm        :     e.g. PassiveSTSSampleApp

URL for Logout :
https://<IS URL>/commonauth?commonAuthLogout=true&type=passivests&sessionDataKey=xxxxxxx&commonAuthCallerPath=<redirectURL>&relyingParty=<relying party name>


Configure the Passive STS Sample 

1. Checkout the sample client application from the SVN location using following command to a directory. (You can use the same directory created above).

2. Go to the checked out directory ( will be referred as <SAMPLE_HOME> hereafter in this documentation) and modify <SAMPLE_HOME>/src/main/webapp/WEB-INF/web.xml file as follows.

  1. Specify  idpUrl  as the URL of Identity Server's Passive STS. The following is an example.


  1. Specify the replyURL as the URL of the web app. The following specifies PassiveSTSSampleApp as the web app.


  1. Specify the  realm . This should be a unique identifier for the web app as seen in the example below.


Step 3 : Configuring Identity Server for Passive STS

1. Log into WSO2 Identity Server and go to Service Providers ->Add in the Main menu in the management console.

2. Enter a unique name for the service provider and click Register. The following form appears.  

3.Expand the Inbound Authentication Configuration -> WS-Federation (Passive) Configuration section and provide the Passive STS Realm.

Note :  Here you should give the same realm name that is configured in the client application’s web.xml

4. You can add claims through Claim Configuration Tab. These claim will be sent to STS client application.

5. Click Update.

Step 4 : Deploying the sample on Apache Tomcat

Please note that the following steps are described assuming that you are using the sampleSTS application checked out from the svn location. If you are using your own client application which is deployed somewhere else you can access that link and follow step 7 only to log in to the application.

1. Build the sample's .war file.
2. By navigating inside the <SAMPLE_HOME> directory where the pom.xml file is located and running the following command.
mvn clean install
3. Copy the PassiveSTSSampleApp.war file located in the <SAMPLE_HOME>/target directory and paste a copy of it in the <Tomcat_Home>/webapps directory. 
4. Navigate inside the [Tomcat_Home/bin] directory in the command line and run sh run command to start the server.
5. On your browser, access the following link: http://localhost:8080/PassiveSTSSampleApp/index.jsp 
6. Enter user credentials and you will be redirected to the IS Passive STS Service as shown in the following login.

STS-client-app-login.png - Latest 06/Apr/16 05:42 PM IST - Kugathasan Abimaran

And you can access the app after login as follows.

STS-claim-in-client-app.png - Latest 06/Apr/16 05:40 PM IST - Kugathasan Abimaran