Page History

...

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 in order to share the users, roles and 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.

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

2. Share the registry of both WSO2 API Manager and WSO2 Identity Server. For more information, see Sharing the registry space.

3. Start the WSO2 API Manager server and log in to the Management Console. Create user information with the following permission structure.

   User	Role
   api_user	webuser
   api_admin	admin

4. When adding the webuser role, set the Login and Subscribe permissions from permission tree.
   

5. Start the WSO2 Identity Server and log in to its Admin Console. 

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

6. Under the Entitlement section, click Policy Administration > Add New Entitlement Policy.
   
    
7. 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. Refer Creating a XACML Policy in WSO2 Identity Server for more information.
   1. Entitlement Policy Name: PizzaShackPolicy
   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. 
   
8. In the Define Entitlement Rule(s) area, set the following 2 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: Under Define your conditions by using followings.... , select drop down options as Subject , is/are , at-least-one-member-of in order and enter admin in the last field.
      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
      
      Click on Add button after providing above values as shown below.
      

   2. GetOrder- allows web users to get order information from the API. Give the information below,
      Rule Name: GetOrder
      Conditions: Under Rule's conditions are evaluated...... , select drop down options as Action , is , equal in order and enter GET in the last field.
                           
                           Under Define your conditions by using followings.... , select drop down options as Subject , is/are , at-least-one-member-of in order and enter webuser in the last field.

                            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
      
      Click on Add button after providing above values as shown below.

9. Click Add to add the XACML Policy once done.
   
10.  The rules are added to the policy. Click Finish to save the policy. 
    

11. In the Policy Administration page, click Publish to My PDP to publish the policy to the PDP. 
    

    Keep the default selected values in the Publish Policy window appears and select publish.
    

    Tip
    You can test the service by clicking Try option infront of the entitlement policy. It is the tryIt tool developed for XACML in WSo2 Identity Server and you an access the same tryIt tool by navigating to Tools > XACML > TryIt. Refer Evaluating a XACML Policy for more information on how to use the TryIt tool for XACML Policy evaluation.

12. Download the entitlement-1.0-SNAPSHOT.jar and add it to the <API-M_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.
13. Restart the server once the JAR file is added.

14. 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
    language xml
    <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"/> </sequence>

    Note

    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.

    Info
    The attribtes in the <entitlementService> element above should be modified according to the services endpoint configuration as follows.  remoteServiceUrl - Service url of WSO2 Identity Server, acting as the XACML entitlement server in this scenario. remoteServiceUserName - Username remoteServicePassword - Password used to connect to the service

15. Log in to the API Publisher and create an API.
16. Attach the custom sequence to the inflow of the message as shown below.
    

17. Save, publish and test the API to make sure that the requests specified in the 2 rules defined in step 8 are accessible according to the user role specified. For example, the POST operation is only available to users with the role admin. If an anonymous user tries to access the POST operation, it should fail.

    Note
    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"/-->

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