||
Skip to end of metadata
Go to start of metadata

This section explains how you can enable fine grained authorization for your web applications by integrating with WSO2 Identity Server. See the following topics for details: 

About Fine Grained Authorization

When a resource (web application) is deployed in an application server, it is necessary to specify the users that should be granted authority to use the application. Typically, authority is granted to the user of the web application depending on the type of user, resource and the action that the user performs with the resource. However, if we can use more details from the user scenario to determine the authority that should be granted to the user, we call it Fine Grained Authorization. For example, in addition to the type of user, resource and the action performed on the resource, you can use fine grained criteria such as the environment, time, user's role etc., to grant authority.

Example of a fine grained authority requirement: " This document can be edited only by PersonX, who is a Teacher and between 8am to 10am in the school office premises".

About XACML policies

To evaluate such a requirement against a user request, we have to document those fine grained details of the requirement. These documents are called Polices and XACML is used to document this type of policies. We can evaluate  a user's requirements against these XACML policies using an XACML engine. WSO2 Identity Server can be used for this purpose. WSO2 IS has an XACML Policy Engine where users can evaluate their requests and it provides many functionalities related to XACML Authorization.

Providing XACML Fine Grained Authorization to WebApp Requests

WSO2 Application ServerApache Tomcat or any other web container can be used to host our web apps. If it is required to provide fine grained access (authority) to our Web Apps, WSO2 Identity Server can be used as the XACML Policy Decision Point (PDP). This PDP can be accessed via a web service called Entitlement Service. We use the servlet filter named Entitlement Servlet Filter as the Policy Enforcement Point (PEP) for Web App authorization. This allows us the flexibility of using it in any Web App container. The Entitlement Servlet Filter uses a proxy to communicate with WSO2 Identity Server.

The following digram shows how the servlet filter receives the decision on user authority:

To get an entitlement decision, we need some parameters like UserName, ResourceName, Action and Environment. We can map the resource name to the servlet to which the request is sent. Environment will be the WebApp. Action will be the HTTP action GET, POST etc. In order to get the user name of the person who sent the Web App request, the following Java EE authentication mechanisms are used:

  Basic Authentication

  Client Cert Authentication

  Digest Authentication

  Form Authentication

To grant authority, we have to authenticate the person. After the authentication, we can obtain the username in the servlet filter using the above mentioned methods. All the parameters can be obtained to get an entitlement decision. As shown in the diagram, when a request comes to a particular Web App which has the engaged Entitlement Servlet Filter, the following parameters are obtained: UserName, ResourceName, Action and Environment. Then the PDP Proxy is initialized to communicate with WSO2 IS. After that, the parameters are sent as an XACML request and the entitlement decision is received. Depending on the entitlement decision received, the request which has came to the Web App is either stopped or passed. 

The next critical step in this process is for the user to engage the Entitlement Servlet Filter. For that, we use the web.xml. From this file, the servlet filter will read necessary parameters in order to initialize the communication with WSO2 IS. The following shows an 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>

Samples

For a demonstration of this functionality, run the Entitlement Servlet sample as explained here.

  • No labels