Version 0.1.2 2010/11/04, Stijn Lievens, Initial draft Version 0.2.0 2010/11/19, Stijn Lievens, Added information on how to add reset BTG functionality. Protecting a Web Application using ZXID and PERMIS In this document we go through the steps required to protect a web application (running in Tomcat say) so that users need to login to access certain parts of the web application and may optionally need to have certain attributes to access some parts of the web application. As a final step we will show how to add BTG-functionality to your web application where some users get the possibility to override the original deny decision when they indicate that they take full responsibility for their actions. We will assume knowledge of web applications in general. Thus, you should e.g. know how to install Tomcat and deploy a unprotected web application in it. No other knowledge will be assumed. This package requires the use of the ZXID library which you will have to compile yourself. 0. Obtain and compile the ZXID native library. Here, we refer to http://zxid.org. The ZXID software is written in C and depends on few external libraries. Compiling should be relatively straigthforward. Just remember to use localconf.mk to specify directives like APACHE_INCLUDE, APR_INCLUDE and APACHE_MODULES. Edit the makefile to set JNI_INC and SERVLET_PATH. Then do make javazxid This should compile some servlets and the native library (libzxidjni.so) 1. Install the unprotected web application. We assume that you have a clean Tomcat installation with its top-level directory called TOMCAT. 2. Provide it with SSO capability This will require users to login to parts of the web application. If you don't want to use/install your own IDP, consider using one that is freely available such as: https://zxidp.org/index-idp.html [You will have to provide the metadata for your SP to be able to use this IDP.] Alternatively you can install your own IDP (such as a ZXID IDP or a Shibboleth one). Then, follow the instructions in DeployingZxidServlets.txt which is distributed with the ZXID software. Test that users now indeed have to login. 3. Add additional authorization to your web application. This is done by adding the ZxidAuthorizationFilter filter to the protected parts of your web application. This filter should follow the ZxidSSOFilter. You will need the set the PDP_URL ZXID configuration parameter to the endpoint of the authorisation service you will be using. The filter is known to work will in confunction with the PERMIS standalone authorisation server. You will probably also need to set the PEP_MAP configuration parameter to control which attributes go where in the request sent to the authorisation server. The ZXID configuration is either supplied in a ZXID configuration file. Additional configuration parameters are supplied by using the init-parameter zxid-configuration (as it also is for the ZxidSSOFilter). The filter takes a second init-parameter called 'deny-location'. This specifies the location where the user will be forwarded to when her request was not granted (and when she didn't have the possibility to override the access control decision). Make the ZxidAuthorizationFilter available by copying the libraries (i.e. the JAR-files) to the web application's WEB-INF/lib directory. 4. Provide BTG capability to your web application The involves three steps: - install the BreakTheGlassServlet - install a BTG interaction page - add BTG capability to your PDP (policy). This is outside the scope of this document. However, instructions how to do this for the authorisation server provided by the ISSRG are provided in its documentation. This requires you to install the 'BreakTheGlass' servlet. This servlet is included in the package. Provide a URL mapping in your deployment descriptor (web.xml) for this servlet. Don't add the ZxidSSOFilter or ZXidAuthorization filter to this servlet. The BreakTheGlass servlet takes one init-parameter called 'no-btg-location'. If the user has indicated that she doesn't want to break the glass, then she will be redirected to this location. You will also need to set up an 'interaction page' where the user can indicate whether or not she would like to break the glass. An example interaction JSP page is included with the package. The look-and-feel of this page is immaterial, its actions, however, are not. The important aspects of this page are that it *always* calls the BreakTheGlassServlet with a POST request. This request has to include certain parameters: - When the user has indicated that she does *not* want to break the glass, then the 'nobtg' parameter should be present (and have any value). - When the user does want to break the glass then the parameters 'btg:action' and 'btg:resource' need to present in the request and should contain the original requested action and resource. In general the interaction page will obtain these values from the session as the ZxidAuthorizationFilter puts them in the session. - An additional parameter 'btg:reason' may be present. This can e.g. be used to include a user indicated reason in a message to her line manager. 5. Provide reset BTG facility to your web application This involves the following steps: - Add the ability to reset BTG state (be it complete tables or individual instances) to your policy. The example policy file policy-btg-demo.xml shows how to do this for a PERMIS policy. - add BTG capability to your PDP (you have already done this in the previous step) - install the ResetBreakTheGlassServlet and its frontend JSP page (ResetBtgTable.jsp) In order to install the ResetBreakTheGlassServlet you will need to provide a URL mapping for this servlet in the deployment descriptor of your application. As the other servlet this one employs the ZXID native library to make the authorisation call (to check whether the requestor is allowed to reset the BTG state) to the authorisation server. The servlet has the following init parameters: - zxid-configuration: gives the configuration string for the ZXID native library - success-location: where to forward the user to when her request was granted - deny-location: where to forward the user to when her request was denied Because the ResetBreakTheGlassServlet needs to be called using a POST request, it is paramount that the ZxidServlet does *not* get called directly when accessing this servlet (this is a limitation of the ZxidServlet), rather one should put the SSO filter on the JSP page that provides the frontend to this servlet. A very crude and basic looking frontend JSP page is provided as an example. The important bits are that: - the ResetBreakTheGlassServlet is called using a POST request. - if the btg:resetbtgtable request parameter is present, then it is assumed that the user wants to reset a complete BTG table. If this request parameter is absent then it is assumed that the user wants to reset an individual row of a BTG table. - the btg:reset:resource parameter needs to specify the resource-id of the authorisation request to reset some BTG state. This will need to be agreed upon by the PEP (i.e. this JSP page) and the policy writer. The btg:reset:resource parameter will need to contain a target mentioned in the policy on which either the 'ResetBreakTheGlass' or 'ResetBreakTheGlassTable' is defined. - the btg:attributeidinstances is needed if the user is trying to reset an individual row of the BTG table. This parameter needs to be in the form of a query string which contains one or more assignment like atttribute-id(X)=attribute-value, where 'X' can either be 'S', 'A', 'R' or 'E' to specify whether the attribute belongs to the Subject, Action, Resource of Environment section of the XACML request. For instance if the BTG variable is BTG:(subject-id(S),action-id(A),resource-id(R)) then such a query string could be "subject-id(S)=Stijn&action-id(A)=GET&resource-id(R)=http://localhost/confidential" The idea is that the administrator is supplied this query string in the message informing her that the glass has been broken. So, it is up to policy writer to include this string e.g. in the obligation to send an email. Using the authorisation server supplied by the ISSR group this can be done as follows: subject-id(S)=%subject-id(S)%&action-id(A)=%action-id(A)%&resource-id(R)=%resource-id(R)% because the parts between % signs will be replaced with the actual value from the request context. The example policy provided with the software also shows this.