

Enabling Role-Based Access Control Using XACML¶

Many organizations expose their business capabilities through APIs. One of the key challenges is controlling access to these exposed APIs in such a way that all authorized users are able to access its APIs without any interruption, while at the same time making sure that any unauthorized users are kept out. In order to achieve this, parameters such as the user role can be used in determining whether to grant or deny access to an API for a given user. There are two ways to control access to users, namely OAuth 2.0 scope and XACML. This section explains how an external extensible Access Control Markup Language (XACML) entitlement server can be integrated with MWARE ESB to provide role-based access control to APIs exposed via MWARE ESB. XACML is a declarative access control policy language based on XML that can provide a standardized way of validating authorization requests.

MWARE ESB 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 ESB when enforcing the policy decision to implement fine-grained access control for APIs.

How XACML is used with MWARE ESB¶

The diagram shown below depicts the scenario where MWARE ESB uses the XACML entitlement server to validate API requests that come into the ESB. In this case, MWARE IAM has been used as the XACML entitlement server.

The process is initiated by an administrator who creates the XACML policies and adds them to the PAP. The created policies are stored in a policy repository and 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 ESB acts as the policy enforcement point (PEP). Whenever an API invocation comes to the ESB, an 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 ESB 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 ESB with its policy decision.

Enabling role-based access control¶

The steps below demonstrate how MWARE IAM, acting as a XACML entitlement server, can validate authentication requests from the ESB based on a set of predefined XACML entitlement policies. This allows a standardized way of defining entitlement policies that can be enforced from MWARE ESB. For detailed information on XACML, see XACML Architecture in the MWARE IAM documentation.

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

Based on the requirement, a single API is exposed to add or retrieve order information. Each member type (webuser or admin) is identified from the resource path. The operation (GET or POST) that needs to be performed is distinguished by the HTTP verb. Follow the steps below to implement this kind of role-based access control.

Let’s start by creating the required users. First, you need to link both the ESB and the Identity Server to the same user store in order to share users, roles and other related information. This can be done by linking the API manager with the LDAP user store within MWARE IAM. For more information, see Configuring an external LDAP or Active Directory Userstore . For this you can create a read write LDAP user store.

Note

By default, in ESB 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 <API-M_HOME>/repository/conf/user-mgt.xml in both nodes.

Tip

In an actual deployment, both these servers can share the user store of your organization.
Start the MWARE ESB server and log in to the Management Console. Create user information with the following permission structure.

User Role

api_user webuser

api_admin admin
When adding the webuser role, set the Login and Subscribe permissions from permission tree.
Start the MWARE IAM and log in to its Admin Console.

Tip

Since ESB and Identity Server run on the same server, offset the Identity Server by 1.
Under the Entitlement section, click Policy Administration > Add New Entitlement Policy .
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 MWARE IAM 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.
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,
  
  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.
Click Add once done.
The rules are added to the policy. Click Finish to save the policy.
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 and select publish.

Tip

You can test the service by clicking Try option in front of the entitlement policy. It is the tryIt tool developed for XACML in MWARE IAM and you can access the same tryIt tool by navigating to Tools > XACML > TryIt .

You need to enter your username as the Subject Name . Refer Evaluating a XACML Policy for more information on how to use the TryIt tool for XACML Policy evaluation. For example, try api_user as the Subject Name and GET as the Action Name. If the policy is configured correctly, you should get a successful message. Try `POST' as the Action Name and you would get a deny message.
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 .
Restart the server once the JAR file is added.
Now, you need to create a API Policy 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.j2 .

xml <entitlementService xmlns="http://ws.apache.org/ns/synapse" remoteServiceUrl="https://localhost:9444/services" remoteServiceUserName="admin" remoteServicePassword="admin" callbackClass="org.wso2.sample.handlers.entitlement.APIEntitlementCallbackHandler"/>

Note

The Entitlement Mediator intercepts requests and evaluates the actions performed by a user against an eXtensible Access Control Markup Language (XACML) policy. Here, MWARE IAM is used as the XACML Policy Decision Point (PDP) where the policy is set, and MWARE ESB 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 attributes in the <entitlementService> element above should be modified according to the services' endpoint configuration as follows.

remoteServiceUrl - Service URL of MWARE IAM, acting as the XACML entitlement server in this scenario.

remoteServiceUserName - Username

remoteServicePassword - Password used to connect to the service
Log in to the API Publisher and create an API. In this sample default PizzaShack API is used.
Create a new API policy and upload the EntitlementMediator.j2 created previously. Set Request under the Applicable flows
Attach the new policy to all the resources as mentioned in attach policy
Save, deploy, 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. Users with webuser role will only be able to access GET resource.

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.


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

Top

User	Role
api_user	webuser
api_admin	admin