This documentation is for WSO2 API Manager 2.0.0. View documentation for the latest release.

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Fixed typos


The API Manager acts as the policy enforcement point (PEP). Whenever an API invocation comes to the API Manager, an authorisation authorization request is sent 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 receives the request along with these attributes and evaluates the request against the existing policies deployed in the PDP. If the request requires more information, the PDP tries to obtain that information from a policy information point (PIP). In this case, the request from the API Manager can contain the username and the policy that is deployed requires the role of the user. In such a scenario, the PDP gets this information from the user store that is defined as a PIP. Once the PDP has the required information to evaluate the request, a response is sent back to the API Manager with its policy decision.


  1. Let’s start by creating the required users. First, you need to link both the API Manager and the Identity Server to the same user store inorder to share users, roles and other related information. This can be done by linking the API manager with the LDAP user store within WSO2 Identity Server. For more information, see Configuring an external LDAP or Active Directory Userstore.


    By default, in API Manager JDBCUserStore is enabled. When you are moving to the ReadWriteLDAPUserStore, make sure you have commented the configuration of JDBCUserStore and keep only one user store configuration <PRODUCT_HOME>/repository/conf/user-mgt.xml in both nodes.


    In an actual deployment, both these servers can be linked to the user store of your organization.

  2. Share the registry of both WSO2 API Manager and WSO2 Identity Server. Refer Sharing the registry space for the steps.

  3. Create user information with the following permission structure.









  4. Install the required XACML features on the API Manager. The default API Manager distribution is not shipped with these features. 

    1. Shutdown the server. 

    2. Use the attached pom.xml, and replace the [APIM_HOME] tag with the path to the APIM installation in your local machine.

    3. Create a folder named 'identity' inside <API-M_HOME>/repository/resources location.
    4. Run the following command:

      Code Block
      mvn clean install
    5. After a successful run, the relevant XACML feature will be installed in the APIM 2.0.0 product.

    6. For XACML mediator feature, use the latest feature release of XACML Mediation 4.6.9. (From public p2 repo
  5. Once the features are installed, restart the server.
  6. Start the WSO2 Identity Server and log in to its Admin Console. 


    Since API Manager and Identity Server run on the same server, offset the Identity Server by 1.

  7. Under the Entitlement section, click Policy Administration > Add New Entitlement Policy.
  8. You are redirected to a page listing all available policy editors. Select Standard Policy Editor from the list and add the values shown below in the policy editor.
    1. Entitlement Policy Name: EDUCollegePolicy
    2. Rule Combining Algorithm: Deny unless Permit
    When the rule combination algorithm is set to Deny Unless Permit, you need to set the permit criteria as a rule. 
  9. In the Define Entitlement Rule(s) area, set the following 3 rules to define the kind of requests and from which user they should be permitted.
    1. AdminGrant - grants full access to the admin user. Give the information below,
      Rule Name: AdminGrant
      Conditions: Subject is/are at-least-one-member college_admin
      Click the icon next to END shown below to configure the attribute value and attribute source to retrieve the user roles from the user store. 
      Select the attributes as given below. Note that this needs to be done for all the rules.
      Select Attribute ID: Role
      Select Attribute Data Type: String
      Entitlement Data Module: Carbon Attribute Finder Module
    2. GetStudent - allows staff users to get student information from the API. Give the information below,
      Rule Name: GetStudent
      Conditions: Resource is equal /student/info AND 
      Action is equal GET
      Subject is/are at-least-one-member staff
      Click the icon next to END shown below to configure the attribute value and attribute source to retrieve the user roles from the user store. 

    3. GetStaff - allows staff and student members to get staff information via the API. Give the information below,
      Rule Name: GetStaff
      Conditions: Resource is equal /staff/info AND 
      Action is equal GET
      Subject is/are at-least-one-member student OR
      Subject is/are at-least-one-member staff
      Click the icon next to END shown below to configure the attribute value and attribute source to retrieve the user roles from the user store.

  10. Click Add once done.
  11.  The rues are added to the policy. Click Finish to save the policy. 
  12. In the Policy Administration page, click Publish to My PDP to publish the policy to the PDP. You can test the service by clicking Try.
  13. Download the entitlement-1.0-SNAPSHOT JAR and add it to the <APIM_HOME>/repository/components/lib directory. This JAR file contains the APIEntitlementCallbackHandler class which passes the username, HTTP verb and the resource path to the XACML entitlement server. If you want to view the source code of the JAR, go here.
  14. Restart the server once the JAR file is added.
  15. Now, you need to create a sequence containing the entitlement policy mediator that can be attached to each API required to authorize users with the entitlement server. Create an XML file with the following configuration and name it EntitlementMediator.xml.

    Code Block
    <sequence xmlns=""  name="EntitlementMediator">      
        <entitlementService xmlns="" remoteServiceUrl="https://localhost:9444/services" remoteServiceUserName="admin" remoteServicePassword="admin" callbackClass="org.wso2.sample.handlers.entitlement.APIEntitlementCallbackHandler"/>

    The Entitlement Mediator intercepts requests and evaluates the actions performed by a user against an eXtensible Access Control Markup Language (XACML) policy. Here, WSO2 Identity Server is used as the XACML Policy Decision Point (PDP) where the policy is set, and WSO2 API Manager serves as the XACML Policy Enforcement Point (PEP) where the policy is enforced. Refer Entitlement Mediator for more information on parameters and usage of this mediator.

  16. Log in to the API Publisher and create an API.
  17. Attach the custom sequence to the inflow of the message as shown below.
  18. Save, publish and test the API to make sure that the requests specified in the 3 rules defined in step 8 are accessible according to the user role specified. For example, the GET/staff/info operation is only available to users with the roles student and staff. If an anonymous user tries to access the GET/staff/info operation, it should fail.


    If you encounter an error stating "org.apache.axis2.transport.jms.JMSSender cannot be found by axis2_1.6.1.wso2v16" when publishing the API, comment out the following JMSSender configuration in the <APIM_HOME>/repository/conf/axis2/axis2_blocking_client.xml file and restart the server.

    <!--transportSender name="jms" class="org.apache.axis2.transport.jms.JMSSender"/-->

  19. If you want to debug the entitlement mediator, enable debug logs in the Management Console for the org.wso2.sample.handlers.entitlement.APIEntitlementCallbackHandler class.