Using XACML Fine Grained Authorization with the WSO2 Product Platform

Archived Content
This article is provided for historical perspective only, and may not reflect current conditions. Please refer to relevant product page for more up-to-date product information and resources.
  • By Tharindu Mathew
  • 17 Oct, 2010

The problem in most security schemes is that it will not give you the ability to fine grain your authorization scheme unless a substantial amount of work goes into implementing such a scheme from scratch. The WSO2 product platform relieves this burden off the system architect and allows you to integrate XACML based authorization into a deployment and have a full blown authorization scheme in place with minimum effort.



The XACML Fine Grained entitlement gives you an extremely flexible way of limiting access to resources based on environment, role, user or any other attribute. An example would be “Allow Tharindu and any user in an Admin role to access MarketDataService only between 8 AM – 5 PM on weekdays”.
We will be using the WSO2 ESB and the WSO2 Identity Server (IS) to implement the XACML authorization scheme. A knowledge of Web Services, XML and security principles is expected as a pre-requirement to follow and understand this article.

Applies To

WSO2 Identity Server Version 3.0.0 and above
WSO2 ESB Version 3.0.0 and above


Table of Contents

  1. Architecture
  2. Considerations
  3. HOWTO - Setting up the WSO2 products for XACML based authorization
  4. Testing the setup
  5. Conclusion
  6. Resources



In this scheme for authorization we will be using the Identity Server (IS) as the PDP and the ESB as the PEP. Any request that comes in to the ESB will be checked for necessary authorization by generating a XACML request and sending it to IS. IS will then validate that request against the XACML policy and inform the ESB whether to allow or deny access to the request. The ESB will then act accordingly to deny or allow access to the request.



XACML expertise

XACML expertise would be needed in defining a proper policy to accommodate complex requirements. Since this is an authorization checkpoint, extensive testing should be carried out to ensure the accuracy of the policy after a modification.

Roles and Groups in the Identity Server

The request will be authorized according to the roles and groups set up in the IS. Therefore, if the XACML policy states that admin users have access to resource X. Then all users who need access to resource X must have user accounts belonging to the 'admin' role in the IS.

HOWTO - Setting up the WSO2 products for XACML based authorization

In this pattern, the guide explains first how to set up roles and groups in the Identity server according to authorization requirements, setup the Identity server with the XACML policy, the Entitlement mediator in the ESB and then set up the Entitlement Proxy Service. A sample Java client will be used to test this pattern. The communication between the IS and the ESB will be thorough HTTPS.

The following sections will explain each of these steps:

  1. Setting up the servers
  2. Setting up roles and groups in Identity Server
  3. Setting up IS with XACML Policy
  4. Setting up in out sequences with an Entitlement mediator
  5. Setting up an Entitlement Proxy Service 

Setting up the servers

The WSO2 Identity Server and the WSO2 ESB both use the ports 9763 (http) and 9443 (https) by default. Therefore, we will change the ports used by the WSO2 Identity Server to 9765 (http) and 9763 (https). For this, please replace the mgt-transport.xml located at $IDENTITY_SERVER_HOME/repository/conf with the one provided here - Then start up both servers by going to the respective bin directories of each server and run the (*nix) or wso2server.bat (Windows) to start the servers.

Setting up Roles and Groups in the Identity Server

Setting up roles and groups is a simple process in the IS. But it is an important process as it determines which users get authorization to access which resource and so forth. Let us create a new role and add users into it as well as add users to an existing role.

Creating a new role and adding users

  1. Click on 'Users and Roles' on the main menu on the right.



  1.  Click on 'Roles'


  1.  Click on 'Add New Role'


  1.  Let us create a new role named 'Architect'.


  1. Now we will have to give permissions to this user. This step applies to the permissions that apply within IS. It is not related to the XACML request. Therefore, the permissions given here should only be given according to what the user in a particular role needs to do in IS. Let us just give the role, 'login' permissions.


  1.  Let us add a user into this role. In this, case it will be the user 'Tharindu' added to this role. This step can be skipped if no users exist yet or the user profiles are not yet created.


  1.  This concludes the steps needed to create a new role. The new list of roles will now be shown.


Adding a user to a role

  1.  Let us add a new user to an admin role. Go to 'Roles' as before and click on 'Users'.


  1.  Enter user name or '*' to list all users.


  1.  Select users needed in the 'admin' role and click Update.


  1.  It will indicate the role has been update accordingly.



 In the next sections a XACML policy defined to give access to any user in an admin role is setup in the Identity Server.


Setting up the Identity Server with XACML Policy

  1. Start up the Identity Server using wso2server.bat (Windows) or (Linux). Log in to the Identity Server with an account that login and manage privileges. The admin/admin default credentials work if they have not been removed. Now click on the Policies listed under the Entitlement menu.


  1. A user can click on the “Add New Entitlement Policy” and edit the template policy accordingly. The policy used for this article is located in the sample-xacml-policy.xml available at This file or any other policy file can be imported using the “Import New Entitlement Policy” button. It will then be listed under “Available Entitlement Policies”.


  1.  The XACML policy can be evaluated using by clicking “Evaluate Entitlement Policies” (refer screenshot above). This brings up a dialog where you can enter your XACML request. A sample request is included in the sample-xacml-request file available at It is also given below:
 <Request xmlns="urn:oasis:names:tc:xacml:2.0:context:schema:os" xmlns:xsi="">
 <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:subject-id"
 <Attribute AttributeId="group"
 <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id" DataType="">
 <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" DataType="">

This request means that the 'admin' user from the user group is trying to access the https://localhost:8280/services/echo web service. This will result in a Permit/Deny/Not Applicable output. In this case, it will be permitted.


Setting up in out sequences with an Entitlement mediator

  1. Log in to the ESB Management console by going to ENTER URL and using admin/admin as username and password. Now, create a sequence by clicking “Sequences” in the left menu and then clicking “Add Sequence” in the Mediation Sequences page.


  1.  Name the sequence “EntitlementInSequence” and add the “Entitlement” mediator though Add Child → Advances → Entitlement



  1.  In the Entitlement Mediator, “Entitlement Server” should be the URL of the IS server. For example, if IS is running on the local machine on port 9445, the URL is https://localhost:9445/services/. The user here should have login and manage permissions in the IS.



  1.  Now, add a “Header” mediator though “Add Sibling” → Transform → Header.


The Header mediator is configured to remove the Security header.


Click on the namespaceas and enter prefix as “wsse” and URI as “



  1.  Add a send mediator and drop mediator to the sequence through Add Sibling → Core → Send and Add Sibling → Core → Drop and save the sequence.


The in sequence is now completed with all the necessary mediators.


  1.  Create a new sequence and name it “EntitlementOutSequence”. Add a Send and Drop mediator as step 5. This will complete both sequences.



Set up the Entitlement Proxy Service

  1.  Create a Custom Proxy through Add → Proxy Service on the left menu.



  1.  Name the proxy EntitlementService and only allow https as the transport. Unclick the http option and click Next.



  1.  Pick the EntitlementInSequence as the In Sequene thorugh the import option click Next. Do the same for tne EntitlementOutSequence as the Out Sequence and click Finish to save the proxy.




  1.  Now apply Username Token security to the proxy. Click on the proxy service name. Now in the dashboard click Security under QoS configurations.


Enable Security in the drop down menu by setting option Yes. Click on Option 1: username token and click Next.


Give access to all roles. This further demonstrates that although any user will be able to access the proxy service, they will not be allowed to access the echo service due to the XACML based authorization that takes place.


This concludes all the steps necessary to setup XACML based authorization on the WSO2 platform.

Testing the setup

The following client can be used to test the pattern for admin/admin credentials. The complete source package is attached to this article at It can be opened up in an IDE and run against this setup without any modifications. Please add the jars in $ESB_HOME/repository/components/plugins to the classpath before running the project. NOTE: To test on any select users make sure the user exists on the ESB as well as on the IS. The roles that the user belongs to is evaluated according to the user data in the IS.

import org.apache.axis2.Constants;
import org.apache.axis2.addressing.EndpointReference;
import org.apache.axis2.client.Options;
import org.apache.axis2.client.ServiceClient;
import org.apache.axis2.context.ConfigurationContext;
import org.apache.axis2.context.ConfigurationContextFactory;
import org.apache.neethi.Policy;
import org.apache.neethi.PolicyEngine;
import org.apache.rampart.RampartMessageData;

public class WSEntitlementTestClient {
	 final static String ADDR_URL = "https://localhost:8280/services/echo";
	 final static String TRANS_URL = "https://localhost:8243/services/EntitlementService"; 
	 public static void main(String[] args) throws Exception {
	  ServiceClient client = null;
	  Options options = null;
	  OMElement response = null;
	  ConfigurationContext context = null;
	  String trustStore = null;

	  // You need to import the ESBs public certificate to this key store.
	  trustStore = "wso2carbon.jks";
	  // We are accessing ESB over HTTPS - so need to set trustStore parameters.
	  System.setProperty("", trustStore);
	  // Password of mykeystore.jks
	  System.setProperty("", "wso2carbon");

	  // Create configuration context - you will have Rampart module engaged in the client.axis2.xml
	  context = ConfigurationContextFactory.createConfigurationContextFromFileSystem("repo","repo/conf/axis2_client.xml");

	  // This is the security policy of the proxy service applied UT.
	  StAXOMBuilder builder = new StAXOMBuilder("policy.xml");
	  Policy policy = PolicyEngine.getPolicy(builder.getDocumentElement());

	  client = new ServiceClient(context, null);
	  options = new Options();
	  // This is the addressing URL pointing to the echo service deployed in ESB
	  options.setTo(new EndpointReference(ADDR_URL));
	  // To the ESB, the proxy service
	  // TRANS_URL points to proxy service
	  options.setProperty(Constants.Configuration.TRANSPORT_URL, TRANS_URL);
	  options.setProperty(RampartMessageData.KEY_RAMPART_POLICY, policy);
	  response = client.sendReceive(getPayload("Hello world"));
	 private static OMElement getPayload(String value) {
	  OMFactory factory = null;
	  OMNamespace ns = null;
	  OMElement elem = null;
	  OMElement childElem = null;

	  factory = OMAbstractFactory.getOMFactory();
	  ns = factory.createOMNamespace("", "ns1");
	  elem = factory.createOMElement("echoString", ns);
	  childElem = factory.createOMElement("in", null);
	  return elem;


XACML is an open standard that brings a powerful and extensible fine grained authorization model to a deployment's security framework. The sample policy demonstrated in this article barely scratches the surface of what's possible with XACML based security. But, just as we have secured a simple web service with a simple XACML policy, a system developer just needs to follow the same steps to enable XACML based security in a large, complex deployment with the WSO2 product stack.


  1. IS 2.0 as a XACML engine -
  2. Adding fine grained authorization to a proxy service in WSO2 ESB -
  3. The XACML 2.0 standard specification - 


Tharindu Mathew, Software Engineer, WSO2 Inc.

About Author

  • Tharindu Mathew
  • Technical Lead
  • Home