Deploying WSO2 Carbon 2.0.x in IBM WebSphere Application Server 6.1

Contents

• Introduction
• Background
• Steps in Detail
• Conclusion

Introduction

All WSO2 Carbon based products can be deployed in application servers such as WebSphere, WebLogic, Tomcat and JBoss. In the illustration below I will be using WSO2 Identity Server to describe the steps to deploy the Carbon based products in IBM WebSphere Application Server 6.1.

WSO2 Identity Server is a Carbon based product and is an open source Identity and Entitlement management server containing the support for XACML, Information Cards and OpenID.

Applies To

Background

This deployment involves:

1. Downloading WSO2 Identity Server 2.0.2 and configuring it.
2. Configuring IBM WebSphere Application Server (WAS)

Pre-requisites: 

1. Install IBM WebSphere Application Server 6.1
2. Create a profile using the WebSphere Profile Management Tool.
NOTE : You can follow the steps given in "Creating an IBM WebSphere Application Server Profile" section of this tutorial - http://wso2.org/library/2735.

Steps in Detail

Step 1 - Download WSO2 Identity Server 2.0.2

 

WSO2 Identity Server (WSO2 IS) version 2.0.2 is the latest version that was released in December 2009. So I will be using that. However the same steps can be applied to any other 2.0.x versions of the product. 

WSO2 Identity Server 2.0.2 can be downloaded from here. Download and extract it to a location in your file system.

When the WSO2 Identity Server distribution is extracted it will have the following content that I have detailed in the below figure.

 

For our purpose, that is to deploy it in IBM Websphere we need only the files and folders that I have marked below.

conf - Contains configuration files.

database - Contains the database.

lib - Contains the basic set of libraries required to startup WSO2 IS in standalone mode.

repository  - The repository is where Carbon artifacts and Apache Axis2 services and modules deployed in WSO2 Identity Server are stored. In addition to this other custom deployers such as javascript, dataservices, axis1services and pojoservices are also stored.

resources - Contains additional resources that may be required.

webapps - Contains the WSO2 Identity Server webapp. Any other webapp also can be deployed in this directory.

Now that we have identified the files and folders that we require for the deployment, lets start with it. 

 

Step 2  -Create a repo in your file system.

Create a new folder in your local file system and give it a name, I will call it 'was_repo'. Now copy the folders we identified above, to this. That is from the WSO2 IS distribution, copy the following folders in to 'was_repo'.

• IS_HOME\conf
• IS_HOME\database
• IS_HOME\repositoy
• IS_HOME\resources 

 

Step 3 -Create a war file.

We need to create a war file from the WSO2 Identity Server webapp which resides in the 'webapps' folder. Later we will be deploying this war file in WebSphere Application Server. Follow the following steps to create the war file.

1. In the file system create a folder.
2. Copy IS_HOME\webapps\ROOT\WEB-INF folder into this.
3. Also copy IS_HOME\lib\log4j.properties file in to is.war\WEB-INF\classes folder. This will help us to see WSO2 Carbon specific logs in the WAS console.
4. Open a command promt within the above created folder.
5. Type jar -cvf is.war *

  

Step 4 - Update the configuration files

Now that we have the war file created and ready to be deployed, lets go back and change the configuration files to use in IBM WebSphere Application Server. A reminder here, the was_repo that I have mentioned below is the repository folder that we  created in step 2 to store the files relevant to this deployment.

 

1. was_repo\conf\axis2.xml;

Change HTTP and HTTPS ports within In Transports to 9081 and 9444.

In IBM WebSphere Application Server the http and http ports are assigned per profile. By default it starts with 9081 and 9444 for http and https ports. My deployment is in the first profile that I created and I am using 9081 and 9444 as my ports. You may change these according to your settings.

<transportReceiver name="http"
class="org.wso2.carbon.core.transports.http.HttpTransportListener">
<parameter name="port">9081</transportReceiver>

<transportReceiver name="https"
class="org.wso2.carbon.core.transports.http.HttpsTransportListener">
<parameter name="port">9444</transportReceiver>

 

2. was_repo\conf\carbon.xml

We need to change the value within WebContextRoot and ServerURL.

WebContextRoot represents the webapp context root of WSO2 Identity Server. When WSO2 Identity Server is to be deployed in Websphere we need to change it to a different context than root. That same name we used need to be updated here also.

<WebContextRoot>/is</WebContextRoot>

The ServerURL represents the URL of the back end server, where the admin services are hosted.  We can update the parameters in this to exactly match our values.

<ServerURL>https://localhost:9444/is/services/</ServerURL>

  

3. was_repo\conf\registry.xml

Here we need to update the path to default h2 database. Provide the path to the database folder within was_repo like shown below.

<URL>jdbc:h2:D:/Testing/IS/2.0.1/was_repo/database/WSO2CARBON_DB</URL>

 

4. was_repo\conf\user-mgt.xml

Same as above, here also we need to update the path to h2 database within the was_repo folder.

 

5. WAS_repo\conf\identity.xml

Please note that this configuration is specific to WSO2 Identity Server. You can omit this step for all the other products. In identity.xml we need to update the values within OpenIDServerUrl and OpenISUserPattern. These are used in openID signing-in and when generating openID as an openIS provider.

Update these to contain the IBM WebSphere Application Server port and the context.

<OpenIDServerUrl>https://localhost:9444/is/openidserver</OpenIDServerUrl>
<OpenIDUserPattern>https://localhost:9444/is/openid/</OpenIDUserPattern>

 

  Now lets move to configurations in IBM Websphere Application Server. Assuming that IBM WebSphere Application Server 6.1 is successfully installed and a profile is created usig the 'Profile Management Tool', follow the below instructions.

 

Step 5 -  Start IBM WebSphere Application Server

1. From a command prompt go to WAS_HOME/profiles/AppSvr02/bin.
2. Set CARBON_HOME to the was_repo that we created above.
3. Type startServer.bat server1 to start the server 

 

Step 6 - Configure WebSphere Application Server

1. Open IBM WebSphere Application Server admin console from a browser (e.g. https://localhost:9044/ibm/console/logon.jsp)
2. Go to Security > SSL certificate and key management > Key stores and certificates > New and give the name, path and password for the keystore files. For WSO2 Identity Server you can use the details below.  Save your settings when you are done.

name = anything (I'll put wso2carbon_cert)

path  =  CARBON_HOME\resources\security\wso2carbon.jks (for CARBON_HOME you need to give the absolute path for was_repo that you created above.)

password = wso2carbon

type = jks

4. Go to Security > SSL certificate and key management > SSL configurations > NodeDefaultSSLSettings and update the SS configurations as below.

• From the drop down select the 'Trust store name' you gave in previous step.
• Also select the 'Keystore name' .
• Press 'Get certificate aliases' button and the rest of the details will be automatically generated.
• Save you're settings. 

5. Go to Applications > Install New Application and give the path and the context root for the application. In our case;

     path = path to the is.war we created

     context root = /is 

6. Go to Applications > Enterprise Applications
7. Select the is_war that we deployed just now. Press 'start'.

 

Step 7 - Restart IBM WebSphere Application Server 

Restart IBM Websphere Application Server after setting CARBON_HOME environment variable as before.

Our deployment in Websphere Application Server is completed after the server is successfully started. Now we can access WSO2 Identity Server from IBM Websphere Application Server using the following URL.

https://localhost:9444/is/carbon

 

Conclusion

The steps given above can be applied to all the products under the WSO2 Carbon product family. If you need to have multiple products installed and invoked from IBM Websphere Application Server at the same time it is advisable to create different profiles.

In WSO2 Identity Server, there need to be an additional step to be performed if you need to enable 'Information cards support for SAML 1.1/2.0'. Here you need to update 'IBM JCE files' within the WebSphere Appliction Server. The IBM JCE files can be downloaded from the IBM website.  To update these files you need to navigate to WebSphere_home\AppServer\java\jre\lib\security folder and replace local_policy.jar and US_export_policy.jar. 

Author

Yumani Ranaweera, Senior Software Engineer, WSO2, yumani AT wso2 DOT com.