Introduction

Part 1 of this series focused on how you could develop a simple web application using WSO2 Developer Studio as the coding environment and how to deploy it in WSO2 Application Server. In this article, we discuss ways to bring security to the web application developed, which was explained in Part 1. In this article too WSO2 Developer Studio is referred to as the coding environment. We also introduce WSO2 Identity Server as the security provider. The key points discussed are as follows:

Authentication

How to add a login page to the web application

Creating users and roles using WSO2 IS server

Authorization

What is XACML (eXtensible Access Control Markup Language) and how it is used for authorization

Integrating XACML authorization to the web application developed so far

As depicted above, the article is divided to two parts to discuss authentication and authorization separately.

Introducing WSO2 Identity Server (WSO2 IS)

WSO2 Identity Server provides sophisticated security and identity management of enterprise web applications, services, and APIs, and provides hassle-free, minimal monitoring and maintenance requirements. It has a rich management so that many operations and configurations can be performed via a web UI. In each WSO2 server, users can configure users and roles and give access, but having a central server to handle security related aspects is architecturally clean and hence easy to maintain.
As the first step, let us see how to setup and configure WSO2 IS with several users and roles.

Creating users and roles in WSO2 IS server

Navigate to /bin and start the server using sh wso2server.sh command (run wso2server.bat for Windows)

Login to the management console using default username “admin” and password “admin”. Go to Configure >> Users and Roles

Figure 01

Add roles

Navigate to Roles >> Add New Role

Figure 02

Define a role as “read” and click finish

In the same way define “write” role and roles. Note that there is another default role named “internal/everyone” which will be assigned to any user by default

Figure 03

Add users

Navigate to Users and Roles >> Users >> Add New Users

Define a user called “hasitha” with password “hasitha”

Figure 04

Click next and assign roles “read” and “write” and click finish

In the same way create following users and roles inside WSO2 IS

UserName

Password

Roles

evanthika

evanthika

read

senaka

senaka

write

shammi

shammi

internal/everyone

Figure 05

Defining users and roles in the above way. The target is to configure the web application to enable the following:

Allow Hasitha to enter new patients to the system and also to search patients.

Allow Evanthika just to search patients in the system.

Allow Senaka just to add new patients (he cannot search).

Shammi will be another user, but not be allowed to either add new patients or to search.

It should be noted here that WSO2 IS server’s built-in LDAP (powered by ApacheDS) is used. If users need to configure an external user store, such as Microsoft Active Directory, Apache Cassandra, or any JDBC database, it is possible with WSO2 IS.

As users and roles are configured with WSO2 IS, now let us see how to perform authentication and authorization within the web application communicating with the IS server.

Adding a login page for the web application

Front-end-development

First of all, let us ensure landingPage.html of the web application is developed so far as a jsp page. Make sure all the references (“home” link at other pages and declaration at web.xml file) to that page is changed to landingPage.jsp

Create an HTML page called login.html inside WebContent folder. This will have the common theme that was used throughout the web application developed

Figure 06

Now as soon as the web application is accessed, this page should be displayed instead of landingPage.html. Only successfully authenticated users should be redirected to landingPage.html. Hence,

Each page that’s already designed for the web application should have a link called “Logout” so that the user can log out of the web application whenever he/she wishes to do so. When the user clicks this link, the request should be forwarded to LogoutServlet.

Now we need to call the WSO2 IS server and see if this user is authenticated. WSO2 Identity Server enables you to manage users and roles in your system with its open web services API (RemoteUserStoreManagerService); therefore, any third-party application can consume this API to handle authentication and authorization with WSO2 Identity Server. Users can perform below operations with web calls to this API1:

Authenticates a user

Creates a new role

Creates a user and add the user to a new role

Adds a value to a predefined custom attribute under the user profile

Checks whether a given user belongs to a given role

We are going to use the first operation to do the authentication. When the above operations are considered, it is evident that creating new users, assigning roles can also be done within the web application itself with custom user interfaces, etc. which is out of scope of this article.

In order to call the above API at the compile time we need the skeleton classes (RemoteUserStoreManagerServiceStub). You can find org.wso2.carbon.um.ws.api.stub_4.2.1.jar file that provides these classes at /repository/components/plugins. Add it to the classpath of the web application project.

The following code snippet will call the webservice and check whether the user has been authenticated.

Interestingly, If somebody directly accessed a web page without going through the login page, the user should not be granted access. In order to do that, we need to monitor every request that comes into the web application.

This can be done using a Servlet filter.

What is a servlet filter

Servlet filters are pluggable Java components that we can use to intercept and process requests before they are sent to servlets and response after servlet code is finished and before the container sends the response back to the client. They also can be configured in the deployment descriptor (web.xml) file. There can be multiple filters for a single resource and a chain of filters can be created for a single resource in web.xml. The servlet filter is created by implementing javax.servlet.Filter interface.

javax.servlet.annotation.WebFilter was introduced in Servlet 3.0 and this annotation is to declare a servlet filter. We can use this annotation to define init parameters, filter name and description, servlets, URL patterns and dispatcher types to apply the filter.

Some common usages of servlet filters:

Logging request parameters to log files.

Authentication and authorization of request for resources.

Formatting of request body or header before sending it to servlet.

Compressing the response data sent to the client.

Alter response by adding some cookies, header information, etc.

Applying a servlet filter for authentication is easy. Note that we need to exclude the requests that come into login.html or LoginServlet from this filter.

Adding authorization to the web aplication

Access control in computer systems and networks rely on access policies. The access control process can be divided into the following two phases:

Policy definition phase where access is authorized

Policy enforcement phase where access requests are approved or disapproved

Authorization is thus the function of the policy definition phase that precedes the policy enforcement phase where access requests are approved or disapproved based on the previously defined authorizations.

XACML as declarative access control policy language

XACML (eXtensible Access Control Markup Language) is one of the standards that defines a declarative access control policy language implemented in XML and a processing model describing how to evaluate access requests according to the rules defined in policies. XACML is primarily an attribute-based access control system (ABAC), where attributes (bits of data) associated with a user or action or resource are inputs into the decision of whether a given user may access a given resource in a particular way. Role-based access control (RBAC) can also be implemented in XACML as a specialization of ABAC2.

This article describes how to use a XACML policy published in WSO2 IS to do a role-based access control. In the previous section, two roles were defined (read role and write role) and assigned to the users. Let us limit the search facility to the users having read role and adding new patients to the users having write role.

The XACML policy will look like the attached file shown in the appendix with the above rules.

Note the following on the XACML policy defined above.

Resource id: /WSO2HealthWebApplication/addPatient.jsp with action id : GET is conditioned by “write” role.

Resource id: /WSO2HealthWebApplication/(patientInfoPage|getPatientDetails).jsp with action id: GET is conditioned by “at least one of” write and read roles.

Uploading and publishing XACML policy to WSO2 IS

Start the server and log into the management console

Navigate to Main >> EntitleMent >> PAP >> Policy Administration tab

Select policy type as “policy” and click on Add New Entitlement Policy

Figure 11

Select “Write Policy in XML” and copy paste the above policy there and save it.

Now the WSO2 Health Web Application need to be modified so that whenever a logged in user clicks on “”Search Patient Records” or “Register a new patient” link the policy published at WSO2 IS is evaluated and the permission is granted or rejected.

If permission granted search patient page or add new patient page will be displayed.

If permission not granted the user will be redirected to the login page.

Interestly enough, WSO2 AS has a inbuilt filter named “EntitlementFilter” (org.wso2.carbon.identity.entitlement.filter.EntitlementFilter) that serves this functionality. Users do not need to write the filter code, instead this inbuilt filter can be declared in web.xml file and configured. At runtime this filter will be exposed to the web application, and the filtering will be done based on the permission given by the identity server4

Please refer the web.xml file of the web application source attached to see how the configuration is done. Following are the highlighted points when configuring EntitlementFilter.

To provide authorization for a user request for a web application, first you have to authenticate your user. For that we use Basic Authentication.

Context parameters:

The scope in which the subject would be available (how we pass the user to the filter)

HTTPS port of the web container used when redirecting request to come over https port for cache update authentication

httpsPort

9453

Filter mappings used to configure URLs that need to be authorized:

/getPatientDetails.jsp

/addPatient.jsp

/patientInfoPage.jsp

With these configurations we have added role-based authorization for the web application. Next step is to build, deploy and test the functionality.

Front-end modifications

What we are securing with the XACML authorization is the links at landingPage.jsp. For the EntitlementFilter we gave the context parameters subjectScope=request-param and subjectAttributeName=user. Thus we need to pass the user as a request parameter.

Build the web application using WSO2 Developer Studio and deploy it in WSO2 Application server (steps were discussed previously on the article series).

WSO2 DSS, WSO2 IS servers should also be running at the time of testing.

Login to the web application as “hasitha”. As it has read and write roles he would be able to search and also insert records.

Login to the web application as “Senaka”. If then clicked on “search patient details” it will not be allowed and you will be navigated to the login page.

If you try with the user “Shammi”, even though he is authenticated into the system, he can neither search nor insert records.

Conclusion and possible improvements

In this article, we discussed how to do authentication and authorization for a web application using WSO2 Identity Server. The authentication part was done validating the username and password. XACML is a standard way to do fine grain authorization with attributes of the users and the roles. The WSO2 middleware platform has management web console support for managing XACML policies and also integration with a web app was pretty straightforward with built-in filters. Going by the above example of a web application, readers would realize it is not very hard to design a web application that can create users, assign them roles, and grant permission to operations inside the web application depending on users’ roles and attributes.

In the third and final part of this series, we bring in WSO2 Enterprise Service Bus to this solution.

Proxy the data service using WSO2 ESB and handle security within ESB.

Error handling with WSO2 ESB and displaying custom error messages to the user.