Introduction

XACML (eXtensible Access Control Markup Language) is a XML schema based policy language used to check the authorization of requests for particular resources in a fine grained manner. To check the authorization of a request, a set of attributes of the request are checked against XACML policies. In order to obtain the authorization for a resource all the various attributes have to be matched. For an example there can be a XACML policy such as: “Only members of the WSO2 Application Server team have read access to this document within WSO2 premises”. Here the resource is a document. To read that document, all the specified attributes have to match.

These XACML policies are hosted in a XACML engine and the checking of authorization against these polices take place inside the XACML engine. The positions where these authorization decisions are taken are named as Policy Decision Point (PDP). In the WSO2 enterprise middleware platform the particular Policy Decision Point (PDP) is the WSO2 Identity Server.

When we are providing entitlement, there has to be a point where the requests are intercepted and checked for authorization. That particular point is named as a Policy Enforcement Point (PEP). In the scenario of providing entitlement for web application requests the WSO2 enterprise middleware platform uses a Servlet Filter as the PEP. This Entitlement Servlet Filter feature is available in WSO2 Application Server 5.0.1 on wards.

In the following sections I will describe how to use the Servlet Filter feature to protect your web application and check the authorization of the request.

Pre Requisites

1. WSO2 Application Server 5.0.1 or newer version
2. WSO2 Identity Server 3.2.3 or newer version
3. Existing Web Application (In this I have used Entitlement_Sample_WebApp)

Existing Web Application

Lets assume that you have a basic web application with several servlets. The requirement is to check the authorization of requests coming in for these servlets. Here I have given a simple web application with three servlets - index.jsp, protected.jsp and other.jsp. Lets see how we can use the Entitlement Servlet Filter feature to provide XACML based entitlement to the protected.jsp.

Abstract View of the Scenario

This diagram shows an abstract view of the solution which will fulfill our requirement to check the authorization of the requests for protected.jsp.

Here the Entitlement PEP Proxy component acts as a proxy for communication between WSO2 Identity Server (PDP) and PEP. The functionality is not important for this tutorial but what you have to understand is our PEP servlet filter will intercept the requests which are coming into protected.jsp, and will check the authorization of those requests using the help of WSO2 Identity Server PDP.

Setting up the WSO2 Identity Server as the PDP

The responsibility of the WSO2 Identity Server is to provide a decision on whether or not the request matches the policy conditions. To check the authorization of our web app request we have to add a XACML policy to the WSO2 Identity Server. The following XACML policy will do that task.

  
  
    
      
        
          
            /Entitlement_Sample_WebApp/protected.jsp
            
          
          
            GET
            
          
          
	    admin
            
          
        
      
    
  

What you have to do is Import this XACML policy to the Identity Server. From here you can download the XACML policy. Then follow these steps,

Step 1 :

Start the WSO2 Identity Server and access the Management Console with the following URL. https://localhost:9444/carbon/ (Here I am running the Identity Server in port 9444 - the default is 9443.)

Step 2 :

Go to the Administration option in the Management Console,

Step 3 :

Go to the Import New Entitlement Policy option in the Administration tab.

Step 4 :

Upload the policy which I have given above using the UI.

Step 5 :

Click the enable button to enable the policy.

Step 6 :

Click the TryIt option to check whether the policy is enabled successfully. Fill the necessary fields with the given values and click Evaluate. Then it will give a Permit if your policy is successfully engaged.

Setting up the Entitlement Servlet Filter as the PEP

The basic way of engaging a servlet filter via web.xml of a web application applies here. The following is the web.xml of my initial web app.

    Entitlement_Sample_WebApp

Step 1 :

To provide authorization for a user request for a web application, first you have to authenticate your user. For that we use Basic Authentication. To enable basic authentication to my protected.jsp inside my initial web app, we have to add this code to the web.xml

Example Security Constraint

    Protected Area
    
    /protected.jsp
    
    DELETE
    GET
    POST
    PUT


    
    admin



        

BASIC

Example Form-Based Authentication Area

    /protected.jsp



        

everyone


admin

Step 2 :

We have to engage the Entitlement Servlet Filter for the particular protected.jsp. For that we have to add following to the web.xml of my initial web application. This configuration can be bit long but it will define all the possible options to configure the Entitlement Filter.

subjectScope
basicAuth




subjectAttributeName
username




userName
admin




password
admin




remoteServiceUrl
https://localhost:9444/services/




EntitlementFilter
org.wso2.carbon.identity.entitlement.filter.EntitlementFilter



    client
    basicAuth




    cacheType
    simple




    maxCacheEntries
    1000




    invalidationInterval
    100000




    authRedirectUrl
    /index.jsp




    thriftHost
    localhost




    thriftPort
    10500






EntitlementFilter
/protected.jsp




EntitlementFilter
/other.jsp




EntitlementFilter
/updateCacheAuth.do
FORWARD




EntitlementCacheUpdateServlet
org.wso2.carbon.identity.entitlement.filter.EntitlementCacheUpdateServlet




    httpsPort
    9453




    authentication
    webapp




    authenticationPage
    default




    authenticationPageUrl
    /updateCache.html





EntitlementCacheUpdateServlet
/updateCache.do

Step 3 :

Put the edited web app to the WSO2 Application Server in the following directory wso2as-5.0.1\repository\deployment\server\webapps.

Step 4 :

Start the WSO2 Application Server and access the Management Console with the following URL. https://localhost:9443/carbon/.

Step 5 :

Go to the List link under the Applications option.

Step 6 :

You will find our new Entitlement_Sample_WebApp has been deployed. Click the Go to URL link and you will see the index.jsp of the application.

Step 7:

Enter the protected.jsp using the following URL, https://localhost:9763/Entitlement_Sample_WebApp/protected.jsp You will see a User Name Password Box is given. Enter “admin” in both fields.

Step 8 :

You will now be able to access the protected.jsp successfully. Try to enter logging credentials of another user of Application Server. Then you can see that you will be redirected to the index.jsp. That means the user is not authorized to access the protected.jsp.

Conclusion

As mentioned in this tutorial, you can engage this entitlement servlet filter for any of your web applications. Also this filter is not specific to the WSO2 Application Server. You can use this inside Tomcat while pointing to a WSO2 Identity Server as the PDP. What you have to do is put the dependencies of the Entitlement Servlet Filter feature to your web application’s lib folder. You can download all those jar files here. Also if you want to look at the code go to this source. Also a independent version of source is available here.

Author :

Andun S.L. Gunawardana, Trainee Software Engineer , WSO2 Inc.

References:

1. https://wso2.org/library/articles/2011/10/understanding-xacml-policy-language-xacml-extended-assertion-markup-langue-part-1
2. https://insightforfuture.blogspot.com/2012/07/providing-xacml-fine-grained.html
3. https://insightforfuture.blogspot.com/2012/07/providing-xacml-fine-grained_22.html
4. https://insightforfuture.blogspot.com/2012/09/xacml-policy-definition-pointpdp-proxy.html
5. https://insightforfuture.blogspot.com/2012/10/securing-exisiting-webapp-using.html
6. https://wso2.org/library/articles/2010/10/using-xacml-fine-grained-authorization-wso2-platform