Use of WSO2 API Manager to validate fine grained policy decisions using XACML

  • By Nadeesha Gamage
  • 26 Feb, 2014


WSO2 API Manager


WSO2 API Manager provides a complete API management solution that allows APIs to be published, managed, and secured via the API Manager. It also provides the ability to manage API subscriptions and monitor/monetize APIs. WSO2 API Manager itself provides a high level of access restrictions on the APIs that are exposed via API Manager. However, a requirement may arise where the API Manager would require a very fine-grained access control mechanism to secure its APIs. In such a scenario, WSO2 API Manager can delegate policy decision making to a XACML entitlement server, which would evaluate each request based on pre-defined XACML policies to allow or deny service invocations.

The XACML entitlement server is not shipped with the API Manager distribution; however, the XACML entitlement server feature can be installed to an API Manager although the instance through the feature manager is available in the API Manager. This allows API Manager to act as a fully-fledged XACML entitlement server.

Applies to

WSO2 API Manager

1.5.0 or above

Table of contents

1. The problem

2. Scenario

3. Running the scenario

4. Summary

The problem

Organizations would have their own access control requirements when exposing APIs to its users. WSO2 API Manager provides a comprehensive authentication and authorization mechanism by which APIs can be secured when exposing them to a developer community. However, the granuility of the authorization mechanism provided by WSO2 API Manager may not be sufficient to support a very fine0grained access control requirement. In order to support such a scenario, XACML-based entitlement policy evaluation capabilities can be installed in WSO2 API Manager. The API Manager’s API Gateway would act as a policy enforcement point (PEP) and the XACML entitlement server within WSO2 API Manager would act as the policy decision point (PDP). The API invocations would be evaluated by the entitlement server within the WSO2 API Manager and the status would be communicated to the API Gateway. This has been graphically illustrated by Figure 1.1

API Manager architecture with a seperate PDP

Delegating authorization to a PDP allows the implementation of more complex access control policies that would provide the organization with greater flexibility in exposing the APIs. It also creates an opportunity for the organizations to expose their APIs to users with different levels of access privileges, who will be able to access only the required capabilities of each API based on their access privileges. For example, an organization would have an API that should be fully available to one user, while only some capabilities of the same API should be made available to another user. Such a requirement can be fulfilled by extending the security model of the WSO2 API Manager to include a separate XACML entitlement server as a PDP to evaluate the service invocations based on a set of pre-defined entitlement policies.


The scenario involves a backend server that returns the risk rating for different risk types. An application would make an API invocation with the risk type, and in turn, the backend service would return the risk rating for each type of risk. The risk assessment API is exposed via WSO2 API Manager. The API would be available for subscription from the API store of the API Manager. Each developer can subscribe to this API from the API Store. All API invocations to the Risk API would be routed via the API Gateway of the API Manager. The API Gateway would delegate the security authentication to the Entitlement Server of the API Manager. The Entitlement Server would authenticate the request against XACML policies defined within the PDP. The XACML entitlement policies defined in the Entitlement Server would contain policies pertaining to different users who are allowed to access the API.

The existing API Manager functionality would be extended through a handler to accommodate this behavior. The handler would be included inside each API that needs the API Gateway to delegate policy decision making to the Entitlement Server. For this scenario, a callback handler is used to send the username, HTTP action, and the service name to the Entitlement Server.

Running the scenario

1. Add the entitlement-0.0.1-SNAPSHOT.jar to WSO2 API Manager

Before starting the WSO2 API Manager, it is required to add the entitlement-0.0.1-SNAPSHOT.jar that contains the callback handler class to WSO2 API Manager. Add the entitlement-0.0.1-SNAPSHOT.jar to <APIM_Home>/repository/components/lib folder (the source file and the jar file of the callback handler are attached).

2. Add the following configuration to the registry.xml of API Manager. Registry.xml can be found in the following folder path

    <handler class="org.wso2.carbon.identity.entitlement.policy.finder.registry.RegistryPolicyHandler">
    <filter class="org.wso2.carbon.identity.entitlement.policy.finder.registry.RegistryPolicyMediaTypeMatcher">
    <property name="mediaType">application/xacml-policy+xml</property>

3. Start WSO2 API Manager

4. Install XACML components to WSO2 API Manager

As all WSO2 products, including the WSO2 API Manager, are built on top of the OSGi componentized architecture, new components can be added to an existing product. In this scenario, we will be adding the XACML features to API Manager. Adding XACML features to WSO2 API Manager would allow the API Manager to act as a XACML entitlement server. XACML features can be installed via the feature manager of the API Manager. The feature manager is accessible from the admin console of the API Manager. The admin console can be accessed through the following URL.


Once inside the admin console, select the ‘configure’ tab from the tabs available on the left-hand side. Inside the ‘configure’ menu you would find the features icon as shown below.

API Manager's feature manager

Inside the features page, select the repository management tab and click on the ‘add repository’ icon

API Manager's feature manager

Add the following repository details in the ‘Add Repository’ page.

Name – Turing

Location -

Once the repository is added, click on the ‘Available Features’ tab. Select the newly added repository and un-tick the ‘Group features by category option’ and click on ‘Find features’ button.

API Manager's feature manager

Select the following two XACML features and click on the install button

API Manager's feature manager

Follow the installation flow and install the XACML features. After the installation is completed restart WSO2 API Manager.

5. Create an API through the API Publisher

Once the API Manager is restarted, log in to the API Publisher and create a new API in the API Manager.

6. Add the Callback handler to the newly created API.

Once the API is created, it is required to add the callback handler to the API. This has to be done by changing to the API definition in the API Manager. In order to do, this we need to access the admin console of the API Manager.

Once inside the admin console, click on the ‘source view’ icon available on the left hand navigation bar as shown in the image below.

API Manager's feature manager

Source view will give access to the synapse configuration of all APIs that are available in the API Manager. Search for the newly created API from the configuration and add the following configuration related to the callback handler.

    <entitlementService xmlns="" remoteServiceUrl="https://localhost:9443/services" remoteServiceUserName="admin"
    remoteServicePassword="admin" callbackClass="org.wso2.sample.handlers.entitlement.APIEntitlementCallbackHandler"/>

Once the callback handler is added, the configuration should be as shown below.

    <?xml version="1.0" encoding="UTF-8"?><api xmlns="" name="admin--RiskAPI" context="/riskAPI" version="1.0.0"
    <resource methods="POST GET OPTIONS DELETE PUT" url-mapping="/*">
    <entitlementService xmlns="" remoteServiceUrl="https://localhost:9443/services" remoteServiceUserName="admin"
    remoteServicePassword="admin" callbackClass="org.wso2.sample.handlers.entitlement.APIEntitlementCallbackHandler"/>
    <property name="POST_TO_URI" value="true" scope="axis2"/>
    <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">

7. Add the entitlement policies to the Entitlement Server

XACML policies need to be added to WSO2 API Manager to evaluate API invocations based on those policies. For this scenario we would create an
entitlement policy that would allow subscriber1 to access only the fire related risk rating and deny any other type of risk rating.

Login to the WSO2 API Manager’s administration console. Once inside the administration console you would be able to find the Entitlement Server related features on the left-hand side panel. Select ‘Policy Administration’ and click on the ‘Add New Entitlement Policy’ icon as shown below.

API Manager's source view to access API definition

Of the different policy creation methods, select ‘Simple Policy Editor’. This will redirect the page to the policy creation page. Enter policy information as shown below and click on the finish button.

API Manager's source view to access API definition

This policy would allow the user ‘subscriber1’ to invoke a GET method using query string ‘fire’.

After creating the XACML Policy it needs to be published to the PDP. This can be done by clicking the ‘Publish to my PDP’ icon available in the Policy
Administration page as shown below.

XACML Policy administration

Once the policy is published, go to the PDP policy view and enable the policy in the PDP as shown below.

XACML Policy view

Once the policy is enabled in the PDP, it is possible to test the policy using the in-built ‘try it’ tool.

8. Subscribe and invoke the API

In order to subscribe the API, create a new user through the self-signup interface available in the API Store. The username of the new user should be the same username provided in the XACML entitlement policy given in the previous step (in this case subscriber1). Once the user is created login to the API Store and subscribe to the API. After subscribing to the API, make a service invocation to the API. The Service invocation should be made with the query string that is defined in the XACML entitlement policy (in this case ‘fire’). The invocation should be made as a GET request. The API Manager should authorize this request and allow the subscriber1 to access the backend service. On the next attempt change the query string to a different value and make the invocation. WSO2 API Manager should deny access to the API in this case. Alternatively, service invocation can be made from a different user and the API Manager should still deny access to the API.


This article demonstrated the capabilities of the WSO2 API Manager to work as a XACML entitlement server to validate API invocations based on a set of XACML entitlement policies. The use of a XACML entitlement server allowed the API Manager to enforce fine-grained access controls on APIs that are exposed via the WSO2 API Manager.





About Author

  • Nadeesha Gamage
  • Lead Solutions Engineer
  • WSO2