[Tutorial] How to Enable Role-Based Access Control for WSO2 API Manager Using XACML

  • By Nadeesha Gamage
  • |
  • 5 Feb, 2016


As discussed in our previous article1 modern organizations are moving towards an API driven business model as many of their business capabilities are exposed through APIs. Controlling access to these exposed APIs is a key challenge for an organization where it should make sure all authorized users should be able to access its APIs without any interruption while any unauthorized users are kept out. This type of requirement would need the solution to work with parameters such as a user role in determining whether to grant or deny access to a given user to access an API. As discussed earlier, OAuth 2.0 scope is one way of controlling access to users. In this article, we look at how an external XACML entitlement server can be integrated with WSO2 API Manager to provide role-based access control to APIs exposed via WSO2 API Manager.

What is XACML?

XACML acronym for ‘eXtensible Access Control Markup Language’ is a declarative access control policy language based on XML that can provide a standardized way of validating authorization requests.

Why use XACML with WSO2 API Manager?

WSO2 API Manager provides the capability to authorize users based on OAuth 2.0 tokens and this mechanism can be extended to provide role-based access control using OAuth 2.0 scopes. However, as opposed to using OAuth 2.0 scope to provide authorization, XACML provides a standardized way of validating authorization requests. Authorization policies can be written in a standardized way using XACML and can be stored and managed through a policy administration point (PAP). Since the policies are standardized, policies written to one XACML engine can be ported to another engine from a different vendor without any issue. Similarly, XACML provides more control on how access should be enforced as different parameters and possibilities can be evaluated. XACML also provides ‘Obligations’ and ‘Advice’ as part of the XACML response that can be used by the API manager when enforcing the policy decision.

How XACML is used with WSO2 API Manager

Figure 1 depicts the scenario where WSO2 API Manager uses XACML Entitlement Server to validate API requests that come into the API manager. In this case we have used WSO2 Identity Server as the XACML entitlement server.

Figure 1

The process is initiated by an admin who creates the XACML policies and adds them to the PAP. The created policies would be stored in a policy repository and would be promoted to the policy decision point (PDP) by an authorized user. Once the policy is deployed authorization requests are evaluated against this policy; there can be more than one policy deployed in the PDP.

The API manager would act as the policy enforcement point (PEP); whenever an API invocation comes to the API manager it would send an authorization request to the PDP with the required attributes. In this case it can be the name of the user, resource path, and the HTTP verb. The PDP would receive the request along with these attributes; it will evaluate the request against the existing policies that are deployed in the PDP. If the request requires more information, the PDP would try to obtain that information from a policy information point (PIP). In this case the request from the API manager would contain the username and the policy that is deployed would require the role of the user. In such a scenario the PDP would get this information from the user-store that’s defined as a PIP. PDP would now have the required information to evaluate the request and it would respond back to the API manager with its policy decision.

Putting the scenario together

Let’s take the following requirement in exposing an API via the API manager.

The requirement is similar to what we discussed in this article1. Based on the requirement a single API should be exposed to add or retrieve student and staff information. Each member type (staff or student) is identified from the resource path. The operation (GET or POST) that needs to be performed is distinguished by the HTTP verb. Let’s see how this kind of role-based access control can be implemented.

  1. Let’s start by creating the required users. Before you do this, you will need to link both the API manager and the identity server to the same user-store. This can be done by linking the API manager with the LDAP user store within WSO2 Identity Server. Instructions on how to do this can be found here2. In an actual deployment both these servers can be linked to the user-store of your organization. User information with the following permission structure needs to be created.
    User Role
    staff_user staff
    student_user student
    admin_user college_admin
  2. Next let’s install the required XACML features on the API manager. The default API manager distribution is not shipped with these features. You can install the features by starting the API Manager Server, and logging in to the API manager’s management console. Once inside click on ‘Configure’ tab and select ‘Features’ option from the menu.

    Figure 2

    In the features menu, select the ‘Repository Management’ tab and add the following repository details:

    Name: Turing

    URL: https://product-dist.wso2.com/p2/carbon/releases/turing/

    Once you add the repository, click on the find features button; you will find all the available features in the repository. Scroll down and find the 2 XACML related feature and install the features to the API Manager as shown below. It would be easier to find the features if the ‘Group features by category’ checkbox is unchecked when searching for features.

    Figure 3

  3. Once the features are installed please restart the server.

  4. Let’s now add the XACML policy to the identity server. Since we are planning to run both the API manager and identity server in the same server, we will need to offset the identity server; in this case let’s set the offset to 1. Once this is done start the identity server and login to the admin console. Inside the admin console click on the ‘Policy Administration’ button under the ‘Entitlements’ section and click on the ‘Add New Entitlement Policy’ button as shown below.

    Figure 4

    You will be routed to a page that lists down all available policy editors; here select the ‘standard policy editor’ from this list. You will need to include the values as shown below in the policy editor.

    Figure 5

    Entitlement Policy Name – EDUCollegePolicy

    Rule Combining Algorithm – Deny unless Permit

    In this case the rule combination algorithm is set to ‘Deny Unless Permit’ which means that you need to set the permit criteria as a rule. Hence, let’s set the below 3 rules to define what kind of requests from which user should be permitted.

    Admin Grant rule – to grant full access to the admin user. Screenshot of the Admin Grant rule is given below. Once you have added the information given below make sure to click on the icon marked in red to configure the attribute value and attribute source to retrieve the user roles from the user-store.

    Figure 6

    Once inside this page select the attributes as given below. Please note that this needs to be done for all the rules the user needs as the input.

    Figure 7

    • GetStudent rule – This rule would allow staff users to get the student information from the API. The rule configuration is given below. Please note that the subject condition needs to have attributes configured as done in the above case.

      Figure 8

    • Get Staff rule – This rule would allow staff and student members to get staff information via the API. This rule configuration is given below. Please note that the subject condition needs to have attributes configured as done in the above case.

      Figure 9

    • Once you have configured all 3 rules you can save the policy. The policy should look like the figure above. You will now need to publish the policy to the PDP. This can be done by clicking on the ‘Publish to My PDP’ available in the Policy Administration page as shown below. You can also test the service using the ‘Try’ feature available in the Policy Administration page.

      Figure 10

  5. Let’s add the entitlement-1.0-SNAPSHOT jar file to API Manager. This jar file contains APIEntitlementCallbackHandler class which would pass the username, HTTP Verb and the resource path to the XACML Entitlement Server. The jar file is available here [5]. The entitlement jar needs to be added to the following location. <API_Manager_Home>\repository\components\lib

    Restart the server one this jar file is added.

  6. We now need to create a sequence that would have the entitlement policy mediator that can be attached to each API that needs to authorize users with the entitlement server. Create an XML file with the following configuration and name it as EntitlementMediator.xml. Now add this as a custom sequence to the API manager; since this needs to be invoked in the inflow add it to the ‘in’ folder. More information on adding a custom sequence can be found in the following blog3.
    <sequence xmlns="http://ws.apache.org/ns/synapse"  name="EntitlementMediator">      
        <entitlementService xmlns="http://ws.apache.org/ns/synapse" remoteServiceUrl="https://localhost:9444/services" remoteServiceUserName="admin" remoteServicePassword="admin" callbackClass="org.wso2.sample.handlers.entitlement.APIEntitlementCallbackHandler"/>
  7. Let’s now create an API in the API manager; when creating an API ensure to attach the custom sequence to the inflow of the message as shown below.

    Figure 11

You can now publish the API and test the API via the API manager. If you want to debug the entitlement mediator you can enable debug logs in the API manager for the following class ‘org.wso2.sample.handlers.entitlement.APIEntitlementCallbackHandler’. Logs can be enabled from the management console of the API manager.


This tutorial looked at how WSO2 Identity Server which is acting as a XACML entitlement server can validate authentication requests from the API Manager based on a set of predefined XACML entitlement policies. This allows a standardized way of defining entitlement policies that can be enforced from WSO2 API Manager.



About Author

  • Nadeesha Gamage
  • Lead Solutions Engineer
  • WSO2