[GSoC 2016] REST implementation for WSO2 IS Entitlement Service

Hi all,

This post is to document the process followed, decisions taken and implementations done in implementing the REST service for WSO2 Identity Server's Entitlement Service. This was done as a GSoC project. If you are nto familiar with the WSO2 Identity Server, please first refer to my previous post which would answer most your questions.

Abbreviations

IS                      -  Identity Server
XACML           -  eXtensible Access Control Markup Language
REST                -  Representational state transfer
JSON                -  JavaScript Object Notation


Requirements of the service

1. Allow RESTful access to 5 service methods (Already implemented in SOAP service)
2. Allow XML XACML requests to be processed and responses to be given
3. Allow XML web requests to be processed and responses to be given
4. Allow JSON XACML requests to be processed and responses to be given
5. Allow JSON web requests to be processed and responses to be given
6. Exceptions should be handled globally and necessary responses should be given in a centralized manner
7. Comply fully with the REST profile for XACML 3.0
8. Provide swagger definitions for extra methods that are not specified in the REST profile

Implementation Decisions

1. REST Framework - Apache CXF

       Apache CXF is a framework that allows easy deploying of REST Services. The key reasons for using Apache CXF for this implementation are

1. Apache CXF already used with other REST Services (ex: SCIM inbound provisioning service). So libraries are already bundled with IS
2. JAXB provides inherent support for marshaling and unmarshaling Java Beans to and from XML
3. Additional libraries can be used to easily support JSON
4. Exception mappers allow centralized exception handling

2. Jackson for JSON support

Jackson is a JAX-RS provider for JSON, and it's already used within IS.

3. Implementing JSON profile for XACML 3.0 defined here

4. Using exception mapper to centralize the exception handling of the service and providing customized error messages from the service.

Final Implementation Design

Figure 1

Rough Class Diagram on critical components

Figure 2

Steps

1) Branching from SCIM inbound provisioning service implementation

Since the the above project is already implemented and functioning within IS, a copy of that was used as a starting point for the REST implementation of Entitlement Service. The following classes and packages were derived as it is from the SCIM implementation

packages
i) auth
ii) impl

classes
i) AuthenticationFilter
ii) AbstractResource
iii) ClearThreadLocalInterpretor

2) Removing SCIM related dependencies

All SCIM related dependencies were removed from the project. Since Authentication is not centralized within IS (and will be in future), the following authenticators were hardcoded.

i) BasicAuth
ii) OAuth

3) Restructure project paths and doing necessary changes to cxf-servlet.xml and web.xml

4) Adding JSON marshaling and unmarshaling to and from Java Bean support using Jackon

Currently Jackson 2.5.4 is added as an external library to the project. And the Jackson Json Provider was registered as a provider for the service. For which the following lines we added in cxf-servlet.xml

5) Define a new DecisionResource class which would handle the service endpoint requests

DecisionResource will extend AbstractResource. Accordingly the necessary service methods were then added (Refer Figure 2).

6) For methods getDecision and getDecisionByAttributes Request/Response converters were needed

By default Balana engine does not posses the capabilities to evaluate JSON XACML requests nor provide JSON XACML response. Hence 2 new classes were added to provide support.

i) JSONRequestParser : Converts JSON XACML request to Balana ResponseCtx object
ii) JSONResponseWriter : Converts Balanda ResponseCtx object to JSON XACML Response

7) For the rest of the web service requests, necessary Request/Reponse models were defined. Such defined models were

i) getHome : HomeResponseModel

ii) getDecisionByAttributtes / getBooleanDecision: DecisionRequestModel

iii) getEntitledAttributes :EntitledAttributesRequestModel, EntitledAttributesResponseModel

iv) getAllEntitlements : AllEntitlementRequestModel, AllEntitlementResponseModel

8) These models allow better Request/Response structures from the service

9) Custom Exception Mapper (EntitlementExceptionMapper) was added

This act as an intermediate to all exceptions occurred during the service method executions as well as JAX binding executions. Exception will not be handled inside the service methods, but rather will be thrown out to be caught be the exception mapper. Hence through which the exception handling procedure can be centralized. Custom error codes and messages were introduced. (Will be stated in a latter section)

10) Finally, the webapp is created to a war file and deployed to the IS webapps directory

It can be accessible by https://localhost:9443/wso2-entitlement/entitlement/Decision?_wadl

11) Implementing Swagger for populating service methods

Swagger is a framework that easily provide a globally understandable representation to the RESTful APIs. Since our REST service contained methods that were not defined by the XACML REST profile, swagger need to be used to populate the methods definitions of those additional methods and of the overall API itself. Swagger product a json/yaml file that nicely describes the service methods, input parameters and return values to any client that consumes it.

12) Writing integration tests for the service using testNg and Jetty 

Once all done, the integration tests were written. Used jetty module that comes with Apache CXF to fire up a web client and send and retrieve responses from the service. The full procedure is at http://manzzup.blogspot.com/2016/08/writing-integration-tests-for-apache.html



Code

The complete code can be found at
https://github.com/ManZzup/identity-framework/tree/master/components/entitlement/org.wso2.carbon.identity.entitlement.endpoint

Github Commits
https://github.com/ManZzup/identity-framework/commits/master?author=manzzup

Public JIRA Ticket
https://wso2.org/jira/browse/IDENTITY-4985


References

1) XACML 3.0 REST Profile 

2) XACML 3.0 JSON Profile