Checking the Authorization of WebApp Requests

Introduction to XACML Fine Grained Authorization

When we talk about a resource ( Here resource is the Webapp hosted in either WSO2 Application Server, Apache Tomcat etc.) we have to talk about authorization of the users who use those resources. That means some users are authorized to use the resource and some users are not. So what does it mean by Fine Grained Authorization ? Traditionally authorization of the user for resource is decided by the users, resource and the action which user does on the resource. But if we can provided authorization based on user, resource, action user does on resources, environment, time, user's role etc, that is fine grained authorization. We use more details of the scenario to decide the authorization of the user. For a example if there is requirement like this, " This document can be edited by only PersonX, who is a Teacher and between 8am to 10am in the school office premises". The given requirement is a fine grained authorization requirement.

To evaluate such requirement against users request, we have to document those fine grained authorization requirements. Those are called Polices. XACML is used to document these kind of polices. We can evaluate user's requirements against these XACML polices using a XACML engine.

We can use WSO2 Identity Server for this requirement. It has a XACML Policy Engine where users can evaluate their requests. It also provides so many functionalities related to XACML Authorization.

Providing XACML Fine Grained Authorization to WebApp Requests

WSO2 Application Server or Apache Tomcat or any other web container can be used to host our web apps. If there is a requirement to provide authorization to those web apps? That means some one want to allow access to there web apps on a fine grained manner. So using WSO2 Identity server as the XACML Policy Decision Point (PDP) we can provide fine grained authorization to webapps. This PDP can be accessed via a web service called Entitlement Service.

So what will be the Policy Enforcement Point (PEP) for the webapp authorization ? To use in any webapp container in a flexible way, we used Servlet Filter as PEP. This servlet filter is named as Entitlement Servlet Filter . It uses a Proxy to communicate with WSO2 Identity Server.

The following digram shows how the the servlet filter gets the authorization decision,

To get and entitlement decision we need some parameters like UserName, ResourceName, Action and Environment. We can map the Resource Name to the servlet which the request is sent. Environment will be the WebApp. Action will be the HTTP action GET, POST etc. How we can get the user name of the person who sent the web app request? For that we used J2EE authentication mechanisms,

Basic Authentication
Client Cert Authentication
Digest Authentication
Form Authentication

To provide authorization, we have to authenticate the person. After the authentication we can obtain the username in the the servlet filter using the above mentioned methods. All the parameters can be obtained to get an entitlement decision. As shown in the digram, when a request comes to a particular webapp which has the engaged Entitlement Servlet Filter it obtains the parameters UserName, ResourceName, Action and Environment. Then it initialize the PDP Proxy to communicate with WSO2 IS. After that it send the parameters as a XACML request and get the Entitlement decision. On the provided decision it stop or pass the request which has came to the web app.

The next critical thing is how the user can engage the Entitlement Servlet Filter. For that we use the web.xml. From that the Servlet Filter will read necessary parameters to initialize the communication between WSO2 IS. The following shows a example web.xml which configures the Entitlement Servlet Filter.

Example web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://java.sun.com/xml/ns/javaee"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         id="WebApp_ID" version="2.5">
    <display-name>Entitlement_Sample_WebApp</display-name>

    <!-- The scope in which the subject would be available.  Legal values are basicAuth, request-param, request-attribute, session -->
    <!-- This param is optional. If not provided would be set to default value -->
    <context-param>
        <param-name>subjectScope</param-name>
        <param-value>basicAuth</param-value>
    </context-param>

    <!-- The name of the identifier by which to identify the subject -->
    <!-- This param is Mandatory. Should be provided -->
    <context-param>
        <param-name>subjectAttributeName</param-name>
        <param-value>username</param-value>
    </context-param>

    <!-- The username to perform EntitlementService query-->
    <!-- This param is Mandatory. Should be provided -->
    <context-param>
        <param-name>userName</param-name>
        <param-value>admin</param-value>
    </context-param>

    <!-- The password to perform EntitlementService query -->
    <!-- This param is Mandatory. Should be provided -->
    <context-param>
        <param-name>password</param-name>
        <param-value>admin</param-value>
    </context-param>

    <!-- The URL to perform EntitlementService query-->
    <!-- This param is Mandatory. Should be provided in this format -->
    <!--If the transport type is SOAP give the url like https://localhost:9443/services/-->
    <!--If the transport type is Thrift give the url like https://localhost:9443/-->
    <context-param>
        <param-name>remoteServiceUrl</param-name>
        <param-value>https://localhost:9443/services/</param-value>
    </context-param>

    <!-- EntitlementFilter Settings -->
    <filter>
        <filter-name>EntitlementFilter</filter-name>
        <filter-class>org.wso2.carbon.identity.entitlement.filter.EntitlementFilter</filter-class>

        <!--Client Class that extends AbstractEntitlementServiceClient. Legal values are basicAuth, soap and thrift.Default is 'thrift'.-->
        <init-param>
            <param-name>client</param-name>
            <param-value>basicAuth</param-value>
        </init-param>

        <!--Decision caching at PEPProxy. Legal values are simple and carbon.This parameter is optional.
        If not specified no caching is done.-->
        <init-param>
            <param-name>cacheType</param-name>
            <param-value>simple</param-value>
        </init-param>

        <!--Maximum number of cached entries. Legal values are between 0 and 10000 .Only works with caching.-->
        <init-param>
            <param-name>maxCacheEntries</param-name>
            <param-value>1000</param-value>
        </init-param>

        <!-- Time interval for which cached entry is valid. Only works with simple cache type. -->
        <init-param>
            <param-name>invalidationInterval</param-name>
            <param-value>100000</param-value>
        </init-param>

        <!-- URL ro redirect to if authorization fails -->
        <!-- This param is Mandatory. Should be provided -->
        <init-param>
            <param-name>authRedirectUrl</param-name>
            <param-value>/index.jsp</param-value>
        </init-param>

	    <!-- This will be used if the transport type is thrift. This is mandatory -->
        <init-param>
            <param-name>thriftHost</param-name>
            <param-value>localhost</param-value>
        </init-param>

        <!-- This will be used if the transport type is thrift. This is optional. If not provided would be set to default value -->
        <init-param>
            <param-name>thriftPort</param-name>
            <param-value>10500</param-value>
        </init-param>

    </filter>

    <!-- Filter mappings used to configure URLs that need to be authorized  -->
    <filter-mapping>
        <filter-name>EntitlementFilter</filter-name>
        <url-pattern>/protected.jsp</url-pattern>
    </filter-mapping>
    <!-- Filter mappings used to configure URLs that need to be authorized  -->
    <filter-mapping>
        <filter-name>EntitlementFilter</filter-name>
        <url-pattern>/other.jsp</url-pattern>
    </filter-mapping>
    <!-- Mandatory mapping that needs to be present to work with PEP cache update authorization-->
    <filter-mapping>
        <filter-name>EntitlementFilter</filter-name>
        <url-pattern>/updateCacheAuth.do</url-pattern>
        <dispatcher>FORWARD</dispatcher>
    </filter-mapping>
    <servlet>
        <servlet-name>EntitlementCacheUpdateServlet</servlet-name>
        <servlet-class>org.wso2.carbon.identity.entitlement.filter.EntitlementCacheUpdateServlet
        </servlet-class>

        <!-- HTTPS port of the web container used when redirecting request to come over https port for cache update authentication -->
        <init-param>
            <param-name>httpsPort</param-name>
            <param-value>9453</param-value>
        </init-param>

        <!-- Authentication mode for cache update. Legal values are webapp and wso2is -->
        <init-param>
            <param-name>authentication</param-name>
            <param-value>webapp</param-value>
        </init-param>

        <!-- Authentication page used for cache update authentication. Legal values are default and custom -->
        <init-param>
            <param-name>authenticationPage</param-name>
            <param-value>default</param-value>
        </init-param>

        <!-- Authentication page URL used for cache update authentication. Works only with custom for authenticationPage -->
        <init-param>
            <param-name>authenticationPageUrl</param-name>
            <param-value>/updateCache.html</param-value>
        </init-param>
    </servlet>
    <!-- Servlet mapping needed for cache update authentication -->
    <servlet-mapping>
        <servlet-name>EntitlementCacheUpdateServlet</servlet-name>
        <url-pattern>/updateCache.do</url-pattern>
    </servlet-mapping>
</web-app>

Running The Entitlement Servlet Filter Sample

Pre Requests

Start an instance of WSO2 IS
Import the sample XACML policy to the IS, which is given in sample directory's src/main/resources
Please see the web.xml file given in the sample directory's src/main/webapp/WEB-INF/web.xml
If you are running WSO2 IS in a configuration other than default please edit the web.xml as needed.
Apache Ant is installed in your system

Running the Sample

The base directory of this sample has the build.xml file which is used to build the necessary webapp and deploy it in WSO2 App Server.

To build and deploy the sample,type "ant"
Start the App Server and access the Management Console. Go to the webapp service listing page. You will see the deployed service.
You have to run the run-client.sh or run-client.bat script. It has all the arguments and classpaths configured to run the sample.
In the console it will show the result for several Entitlement Decision Scenarios.

Output Of the Sample

Following output will be shown in the console if you run the Sample correctly,

***********Starting the Entitlement Servlet Filter Sample************
 

Sending Request For a Web Page Which Requires Authorization
Subject : admin
Resource : /Entitlement_Sample_WebApp/protected.jsp
Action : GET
Environment : Not Specified
***Response BEGIN ***
<html>
<head><title>Protected Page</title></head>
<body>Only Authorized Users Can View This</body>
</html>
***Response END ***
 

Sending Request For a Web Page Which Not Requires Authorization
Subject : admin
Resource : /Entitlement_Sample_WebApp/index.jsp
Action : GET
Environment : Not Specified
***Response BEGIN ***
<html>
<head><title>Index Page</title></head>
<body>Anybody Can Access This Page....</body>
</html>
 

***Response END ***
 

Sending Request For a Web Page Which Requires Authorization with False Subject NAME
Subject : andunslg
Resource : /Entitlement_Sample_WebApp/protected.jsp
Action : GET
Environment : Not Specified
***Response BEGIN ***
<html>
<head><title>Index Page</title></head>
<body>Anybody Can Access This Page....</body>
</html>
 

***Response END ***
 

Sending Request For a Web Page Which Requires Authorization with False Action
Subject : admin
Resource : /Entitlement_Sample_WebApp/protected.jsp
Action : POST
Environment : Not Specified
***Response BEGIN ***
<html>
<head><title>Index Page</title></head>
<body>Anybody Can Access This Page....</body>
</html>
 

***Response END ***
 

Sending Request For a Web Page Which Requires Authorization But Policy is not defined
Subject : admin
Resource : /Entitlement_Sample_WebApp/other.jsp
Action : GET
Environment : Not Specified
***Response BEGIN ***
<html>
<head><title>Index Page</title></head>
<body>Anybody Can Access This Page....</body>
</html>
 
***Response END ***
 
***********Ending the Entitlement Servlet Filter Sample************

Note

In this Sample we create a WebApp with Entitlement Servlet Filter engaged. All the dependencies are packed in to the lib. So this sample can be run in any other webapp container. What you have to do is just host the webapp in the container and edit the pom.xml to give the URL of the web app. So you can check the functionality.