Saturday, June 11, 2011

A sample on calling WSO2 Identity Server functionalities through the API

This sample demonstrates how to authenticate a user and to allow that user to access authorized resources(services), using the API of WSO2 Identity Server (WSO2IS). Simply this simulates few functions without the GUI of the server.

Scenario: After authentication, if user is authenticated having the role of 'admin', will have privileges to add or remove XACML policies, and evaluate them against sample requests. Following are the steps to be demonstrated.

  • Log into server after authentication
  • Add a policy from local machine
  • Read the enabled policy of the server
  • Remove a policy
  • Evaluate the enabled policy against a request
  1. Start the Identity Server as explained in user guide. Just extracting the downloaded file, setting up JAVA_HOME environment variable and running .sh or .bat script according to your operating system.
  2. Open the downloaded project in your favorite IDE and add the plugins of the WSO2IS to the project dependencies. The plugins location will look like this at the end, /wso2is-3.2.0/repository/components/plugins. For wso2is-3.0.1 the same path is applied.
  3. If you are using WSO2IS 3.2.0 now you can run the project and see the results. If you are using WSO2IS 3.0.1 you have to generate the stubs the projects needing in a preferred way described as in the post on 'How to convert WSDL to Java' and import them to the project.
  4. When you run the code if it get all the dependencies correct it will ask you to enter the user name, password and remote IP. For the demonstration purposes lets give admin , admin and as the inputs.
  5. Now you will get authenticated in the server and allowed to proceed.
  6. Then it will prompt you to give the path of a policy file to be added to the server, you can read the enabled policy file of the server, remove a policy of your choice and evaluate them against a request of your choice. In the downloaded folder in resources section, few policy files and sample requests are provided and you can use them here. Server will reply you here saying "Permit", "Deny" or "Not applicable".At first I am trying to demonstrate how to see this in action and explaining the code segments in the later part. The code it self is self descriptive too.
All you need is the WSO2IS to test this sample which can be downloaded freely.
All the codes of this sample project can be downloaded for you to try it your own.
To sees what this sample does:
As now we know what is happening there, lets see how that is handled.
In the login method:
/*Path to Java Key Store (JKS) which is a portable repository of X.509 certificates
/*and private keys for encrypting and signing some thing with the private key*/
String path = "/home/pushpalanka/Installations/wso2is-3.0.1/resources/security/" 

+ "wso2carbon.jks";

/*Store of CA certificates to trust. Required to authenticate remote servers*/
System.setProperty("", path);
System.setProperty("", "wso2carbon");

 try {
 /*Create a configuration context. A configuration context contains information 
for a axis2 environment.*/
 configCtx = ConfigurationContextFactory.createConfigurationContextFromFileSyste
(null, null);
 }catch (AxisFault axisFault) {
This path variable should point to where the keystore file is located. You can locate the WSO2IS keystore file as shown inside the resource folder. 3 and 4 lines are setting up the trust store properties that are needed to authenticated in a server. The axis configuration is set up in line 6, that hold global level run-time information for axis2..

Authenticate method:

//hard coded URL of the service
serviceURL = BACKEND_SERVER_URL + "AuthenticationAdmin";
 try {
  authenticationAdminStub = new AuthenticationAdminStub(configCtx,serviceURL);
 } catch (AxisFault af) {
  log.error("Error creating the AuthenticationAdminStub",af)

//Set session management in enabled state
 try {
  //try to login to the system with admin information
  isAuthenticated = authenticationAdminStub.login(userName, password, remoteIp);
 } catch (RemoteException re) {
  log.error("Connection with remote server failed!",e)
 } catch (LoginAuthenticationExceptionException e)
  log.error("Authentication failed!",e);

//create cookie for future usage in the current session
authCookie = (String) authenticationAdminStub._getServiceClient().getServiceContext()
return isAuthenticated;

The backensServerURL is set up earlier as, 

//URL where the wso2 Identity Server services are running 

backendServerURL = https://localhost:9443/services/;  

It is where the service AuthenticateAdmin is running and we are consuming that service to get authenticated in the server as admin. A newly created object of AuthenticationAdminStub is providing the service and we create a cookie using it. The cookie is to avoid the annoy user will face if he/she has to type userName, password and remoreIP every new thing they try with WSO2IS. After the cookie is created we can use it instead of asking for authentication details again and again. Of course the cookie is alive for a limited time.

EntitlementPolicyAdminServiceStub is used for managing the policies as it is performing the admin tasks that are related to entitlement (eq: adding and removing policies etc.) This involve same background as AuthenticationAdminStub.

In the EntitlementAdminServiceUtilities class it is calling each functions provided by the EntitlementPolicyAdminService class.

All these functionalities you can just experience in the browser tab, this is simulating that functionality in a deeper layer.