"Entitlement Service" - XACML PDP as a web service

Being part of WSO2 middleware platform, XACML PDP (Policy Decision Point) functionality in Identity Server is exposed as a web service called 'Entitlement Service' whose implementation can be found here.

Describing XACML reference architecture and XACML policy language is out of the scope of this post and you can refer to my previous post to get an overall idea about an example solution based on XACML.

A PEP (Policy Enforcement Point) can consume the EntitlementService through a SOAP based client and invoke its "getDecision" method to obtain the authorization decision for a given XACML authorization request. Such a PEP exists in WSO2 ESB as a mediator called EntitlementMediator.

In this post, I will take you through a simple java client which acts as a PEP.

1) First of all, lets look at the communication flow between a PEP and PDP of IS with SOAP based implementation:

In the above diagram, in addition to the Entitlement Service, there is also AuthenticationAdmin service comes into play in between client and the EntitlementService.

What does it do?

It authenticates the clients against the user store before the client is capable of invoking an AdminService. Any request coming to the back end server is hit by the Authentication Handler (which is an axis2 handler) and if that request is for an AdminService, handler checks whether the request is authenticated.

Now comes the question, what is an AdminService?

Well.. In WSO2 Carbon, we have a concept called AdminService whose charaterisitcs are as follows:

• Can only be invoked by an authenticated user in the system.
• Exposed over secure transport.

Entitlement Service is exposed as an AdminService since it exposes the functionality of obtaining authorization decision and since it communicates security sensitive information.

You can read more about carbon authentication framework from here.

2) Before looking at the PEP client code, lets setup the PDP of IS with a sample XACML policy.

Start the identity server->login to management console->access Entitlement -> Administration -> Add New Entitlement Policy

WSO2 Identity Server has a rich XACML UI editor through which you can configure XACML policies easily.

Our XACML policy will enforce following rule: Read access to the resource called 'ABCResource' is only allowed to users belonged to admin role and all the other request to this rersource will be denied.

Please follow the following screen shots to compose the policy through UI editor (If the images are not clear, please click on them to view the enlarged version).

i). Here we define policy name, rule combining algorithm and the policy target.

ii). Next we define the two rules with 'Permit' effect for admin users and 'Deny' effect for all other requests.

iii) We can evaluate the XACML policy by sending a mock XACML request from the 'TryIt' tool provided by the Identity Server as shown below.

In the above request, a user in role 'eng' is trying to read the resource 'ABCResource' which should result in deny effect when evalated against the defined XACML policy.

iv). You can also obtain the exact XACML request created by the above 'TryIt' tool by selecting "Create Request" which you can observe as below.

3) Java client as PEP
You can download the source code of the SOAP based client which can act as a PEP and consume Entitlement Service - PDP of IS, to obtain the authorization decisions.
(Here I have only illustrated how to consume PDP, you can continue implementing a complete PEP who tracks access requests from users, composes XACML requests for those resource access requests, gets them authorized by PDP and responds to users accordingly.)

Lets go through the important code segments of the client code.
(Please note that I have trimmed off some of the code segments for the sake of brevity. Please use full source code in the above link.)

public class EntitlementClient {

    private static String serverUrl = "https://localhost:9443/services/";
    //some code goes here

    //sample XACML request captured from TryIt tool of IdentityServer. 
    private static String sampleRequest = "
                                            //actual request is removed for brevity
                                          ";

    public static void main(String[] args) {

        try {

            //set trust store properties required in SSL communication.
            System.setProperty("javax.net.ssl.trustStore",
                               "/home/hasini/WSO2/wso2is-3.2.0/repository/resources/security/wso2carbon.jks");
            System.setProperty("javax.net.ssl.trustStorePassword", "wso2carbon");
            
            //initialize authentication admin stub
            EntitlementClient remoteEntitlementClient = new EntitlementClient();

            //login using authentication admin stub providing valid credentials
            remoteEntitlementClient.login("admin", "admin");

            //initialize entitlement service stub with obtained auth cookie
            remoteEntitlementClient.initEntitlementClient();

            //invoke EntitlementService by passing the XACML request and obtain the authorization decision
            String decision = entitlementServiceClient.getDecision(sampleRequest);
            //print the authorization decision
            System.out.println(decision);

line07: hard coded XACML request which will be given as input when invoking Entitlement Service. This can be obtained from TryIt tool as described in section 2.iv

line16,18: Being AdminServices, AuthenticationAdmin and Entitlement Service are exposed over HTTPS. So here we need to set SSL system properties. Please change them to suit your environment.

line21-30: You can understand by relating the comments in the code with the communication flow illustrated in secion 1.

Setting up and running the client:

In order to run the client, please make sure you have included the two paths: "[IS_home]/lib/api" and "[IS_home]/repository/components/plugins" into your classpath.

So what?

I hope you got an idea about how PDP in IS is exposed and how to write a custom PEP to consume it and about the communication flow between the two.

In fact this is written to build up the foundation for another post I am going to write in the near future. Stay tuned.. and Have a nice day..!!

Fine grained authorization to RESTful services with XACML - Part I

XACML - extensible access control markup language, provides an flexible, fine grained and scalable way of achieving policy based access control.

WSO2 carbon product platform provides a fine grained access management solution with Policy Based Access Control (PBAC) based on XACML.

In this post, I will walk you through a sample scenario on how to build up a solution to control access to a RESTful service with XACML using WSO2 product stack. 

You can find an article on access management with XACML for a SOAP based service from here. We have some additional steps to perform in order to get XACML authorization working for RESTful services.

Scenario:

We have a RESTful back-end service which exposes methods to manage student entries with HTTP verbs: GET,  POST, PUT and DELETE. We need to allow access to perform POST, PUT and DELETE operations of the service only to admin users (since those methods do modifications in the system) and allow access to GET method to all the other users.

Architecture:

One key aspect of PBAC solutions based on XACML is the reference architecture which defines key components involve in access management according to their responsibility. Following are the logical components present in our setup:

1.PAP - Policy Administration Point - WSO2 Identity Server - this is where XACML authorization policies are governed.

2.PEP - (Policy Enforcement Point) - WSO2 ESB - this is where users' requests to services are intercepted and the access is allowed or denied according to the decision given by the PDP.

3.PDP - (Policy Decision Point) - WSO2 Identity Server - this is where authorization decision is taken by evaluating the XACML authorization request sent by PEP, against a matching  XACML policy found in PAP.

4. PIP - Policy Information Point - User store of WSO2 Identity Server - this is from where required attributes of the user who is trying to access the resource will be read by PDP in order to take the authorization decision.

Although there are four logical components listed above, we will have only two physical components in our access management solution since WSO2 Identity Server will play the roles of PAP, PDP and PIP as shown below.

                                       Image 1: Solution Architecture

Setting up the scenario & the solution:

1. Hosting the back-end service: 

• You can obtain the source and archive of the REST service from here. If you want to learn more about RESTful services in Axis2, this article is a good reference.
• We will host this back-end service in WSO2 App Server. (You can also host it in axis2 webapp deployed in Apache Tomcat as well.) Download and run the App Server.
• Upload RestService.aar to the app server by logging into its management console through the browser (https://localhost:9443/carbon/). You may need to wait for few minutes to see the service in the services list after uploading. 
• Click on the RestService and obtain its url. e.g: http://localhost:9766/services/RestService

                        Image 2: Hosting the service in Application Server.

2. Setting up WSO2 Identity Server (IS):
This plays the roles of PAP,PDP and PIP in our solution as mentioned above.

• Download Identity Server, change its Ports.Offset to 1 in carbon.xml found in [IS_HOME]/repository/conf and run the server.
• Login to management console (https://localhost:9444/carbon/) as admin.
• Create a user called 'hasini' who will be belonged to 'everyone' role by default. And give 'login' permission to 'everyone' role.
• Now download and import this XACML policy into IS through Entitlement->Administration->Import New Entitlement Policy as shown below. Once imported, 'enable' the policy from the icon in front of the policy name.

                                Image 3: Policy administration in Identity Server


3. Setting up WSO2 ESB as PEP:

• Download ESB and change its port offset to 2, as we did with IS above.
• We need to use the user store of IS, as the central user store of ESB as well. Therefore change user-mgt.xml of ESB which is found in [ESB_HOME] /repository/conf to point to the user store of IS by setting the following property:

ldap://localhost:10390

• Give 'login' permission to 'everyone' role.
• Now we need to configure a secured proxy service with entitlement mediator in its 'in sequence' in order to intercept and authorize REST requests sent to our back-end service.
• Obtain the proxy service configuration from here and add it to the ESB configuration through Manage->Service Bus->Source View as shown below.

                                   Image 4: Configuring ESB proxy service

Remarks On Proxy Service:

Please note the following configuration of the proxy service as shown abovev which authenticates the user, obtains the authorization decision by communicating with IS and allows/denies the access to back end service.

1. Proxy service is secured with User Name Token so that only the authenticated users will be able to access it.
2. Endpoint is set to the back-end RESTful service.
3. In sequence has three property mediators which are configured to specifically handle RESTful invocations.
4. There is an entitlement mediator which communicates with EntitlementService in IS for obtaining authorization decisions.
5. Header mediator removes the security header before sending the request to back-end service.

Running the client:

Let us have a look at our sample client code  (which you can download from here) which invokes the RESTful back end service which is secured by ESB proxy service. 

Here I need to highlight the REST way of invoking the proxy service when it is secured with User Name Token security policy.

//login as admin
            HttpTransportProperties.Authenticator authenticator = new HttpTransportProperties.Authenticator();
            authenticator.setUsername("admin");
            authenticator.setPassword("admin");
            //enable REST when invoking the service
            stub._getServiceClient().getOptions().setProperty(HTTPConstants.AUTHENTICATE, authenticator);
            stub._getServiceClient().getOptions().setProperty(Constants.Configuration.ENABLE_REST, Constants.VALUE_TRUE);

Following is how we perform the subsequent operations on the service stub.

//create student by admin
            System.out.println("Creating student by admin...");
            Student student = new Student();
            student.setName("Will");
            student.setAge(32);
            student.setSubjects(new String[]{"maths", "science"});
            stub.add(student);

            stub._getServiceClient().cleanupTransport();

            //login as non admin user.
            authenticator.setUsername("hasini");
            authenticator.setPassword("hasini");

            stub._getServiceClient().getOptions().setProperty(HTTPConstants.AUTHENTICATE, authenticator);
            stub._getServiceClient().getOptions().setProperty(Constants.Configuration.ENABLE_REST, Constants.VALUE_TRUE);

            //get student by non admin user
            System.out.println("Getting student by non admin user..");
            StudentName studentName = new StudentName();
            studentName.setName("Will");
            Student result = stub.get(studentName);
            System.out.println("Student's age="+result.getAge()+" successfully read by non admin user..");

            //update student by non admin user
            System.out.println("Updating student by non admin user..");
            result.setAge(40);
            result.setSubjects(new String[]{"english", "history"});
            stub.update(result);

As you can see, we perform add student operation as admin user and get student and update student operations as a non admin user. According to the scenario we mentioned at the very beginning, only the first two operations should be successful and the third operations should be denied.
Since the first and the third operation are asynchronous, we can not observer whether operation was allowed or denied from client side. To observe that, you need to enable debug level log for entitlement mediator in ESB.

Steps for running the client:

• Add the following folders to the class path of the sample: [ESB_HOME]/repository/components/plugins, [ESB_HOME]/lib/api
• Change the keystore path in line 40 of TestRestServiceStub to the wso2carbon.jks keystore of ESB which is in [ESB_HOME]/repository/resources/security

When you run the client, you will observe that add student operation and get student operation will pass and the update student operation will be denied (please refer to ESB logs) based on  the user who invokes the operation and the defined XACML policy.

In this way, you can achieve fine grained access control with PBAC solutions with XACML. Although this sample incorporates users' role as the attribute to define access control rules, you can use other attributes as well and manage access to your enterprise resources in a fine grained manner.

I believe you got an overall idea of how to build up an access management solution with XACML using WSO2 products stack.

What's Next...

In Pat-II of this, I will take you through the XACML policy used in this sample and the XACML requests sent to PDP in order to discuss how authorization decisions are taken.

Thanks for reading this post and have a good day...!

Policy based access control-part 1

This is going to be my first post on this subject. I got interested in it after attending to an informative webinar on Policy based access control with XACML. I am also an amateur in this field and hope to post rich content in the future.

Identity management of organizations has been evolving over the past years. First the  authentication for different applications were managed separately. Then it became centralized identity management where many applications in the organization authenticated users from a central user store such as LDAP store. Requirement of allowing or restricting different users to access different resources based on organizational and business rules was also earlier achieved by project based solutions such as Role Based Access Control  .and Access Control Lists. Those mechanisms lack the interoperability and flexibility.

Policy based access control (PBAC) can be used instead which allows access rules to be defined as policies and easily updated as the rules change. When the organizations grow larger and when there are many large scale distributed applications accessing resources it is better to have these policies managed at a central location in order to preserve consistency and grant access to users from there. Policy based access control  with XACML is increasingly becoming popular as solution to address such requirements.

It is important to note that XACML is a flexible and powerful  authorization policy expression language, but not a policy model or concept of its own. PBAC solutions based on XACML has mainly three parts as follows:

1. Reference Architecture
2. Request/ Response protocol
3. Policy Language.

I plan to discuss about each of the above in detail in my future posts on the subject.