FHIR OAuth Smart Apps Integration and OAuth module enhancements

Abstract

The initial work on OpenMRS OAuth module has carried out in the Implement the OAuth2 Support for Web Services APIs during the previous GSoC. The objective of this project is to migrate existing module to latest OpenMRS 2.x release and make all the OAuth grant type to work. This functionality should be demonstrated with the FHIR module. The new release also opens door to using higher versions of Spring Security OAuth2 project with the module which needs to be explored. Another major goal is to make FHIR module work with SMART applications which needs OAuth2 Authorization code grant type based authentication. So the plan is to improve our OAuth module to implement this capability and do required enhancements.

Note on current state of module : The OAuth2 module is currently configured to implement all grant types specified by the OAuth2 protocol. The module utilizes the Spring Security OAuth2 project and runs on OpenMRS 1.11.4 (max) due to restrictions of underlying API's that are incompatible with higher OpenMRS versions. We are mid-way migrating to a complete RESTful interaction between the front-end and back-end ( It is easier to make REST calls using JavaScript to fetch back-end data and render it rather than implementing custom spring data binders for current data structures used in the module). This also falls in line with the OpenMRS 2.x migration objective and is backward compatible with older versions of OpenMRS. To test the module, you can leverage OMODBypassController to register sample clients and generate client credentials while the UI-based client management functionality is made RESTful.

Project Champions

Mayank Sharma Harsha Kumara Suranga Kasthurirathne 

Goals

• What - Make the OAuth2 module more easily accessible to the implementers and developers in our community.

• Why - As we have already moved to a REST based model with the Platform 2.x and Reference Application, the OAuth2 module needs to catch up.

• How -

• Add new REST endpoints : The module is currently configured via JSP pages embedded with server side code. In order to develop various clients/ applications that seek authentication via OAuth2 module, the registration process for such applications should be possible via REST endpoints. (for instance Android/iOS apps, OWA's etc should be able to register and interact with the OAuth2 module in a pure RESTful manner). Therefore, it is required to introduce REST endpoints OAuth2 module  allow for Client Registration, Editing of client credentials and other miscellaneous configurations that are currently being done via the LegacyUI.

• Upgrade Dependencies : The OAuth2 module is currently using Spring Security and Spring Security OAuth2 v1. It works only for Platform 1.11.4 or less and hadn't been upgraded to work with higher versions. As we have moved to Java8, Spring 4.x, Hibernate 4.x with the Platform 2.0 release, the OAuth2 module needs to be migrated to the latest tech stack.  Please refer to Platform Release Notes 2.0.0#ModuleDevelopers to learn more about the migration process related to OpenMRS Platform. See [5] and [6] as well.

• Role and Permissions: At present, any OpenMRS user can register as a Client Developer. A new OpenMRS Role with relevant Permissions needs to be registered during module installation. These roles and permissions have to utilized during Client Registration (for instance, only Client Developers should be able to register clients; Only admins should be able to see list of all clients; Only)

• Switch to Annotations where possible: Annotation based configuration is more common in the new spring security releases as compared to their xml counterpart. They are easier to understand. At present Spring Security and Spring Security OAuth2 are configured purely via xml. We need to identify places where it would make sense to switch to Annotations instead. 

• Use-case implementation: Identify and Implement use-cases for different grant types. For instance, a basic SMART app can demonstrate using the OAuth2 module's Authorization Code Grant Type besides the interaction between OAuth2 and FHIR modules. Similarly, OWA module based app can demonstrate OAuth2 module's Implicit grant type while the OpenMRS Android Client can exploit the Resource Owner Password Credentials use case. 

Expected Deliverables

• An OAuth2 module compatible with the latest OpenMRS Platform and Reference Application [4] (This is a priority!)
  
• A SMART app demonstrating the Authorization Code flow (Begin after the first deliverable is complete)
  

• An OpenMRS OWA demonstrating the implicit grant type flow (Bonus Karma points, if time permits)

• Android Client demonstrating as Password protocol flow (Bonus Karma points, if time permits)

Sounds Interesting? Here's how you can get started

• Go through the OAuth specification (RFC 6749)[1] and understand OAuth2 and it's grant types.  
• Go through the available samples in web to understand the implementation[2]. 
• Go through the documentation and samples of Spring Security and Spring Security OAuth2 projects. Study the Annotation vs XML implementation options
• Go through and test the current state of OAuth Module and resources in Implement the OAuth2 Support for Web Services APIs
  • Study the data structures for Client, Client Developer.
  • Sketch a rough API specification for the REST endpoints we'd need. Here's the bare minimum (These endpoints must also take care of the permissions of the user making the requests)
    • POST /ws/oauth2/client {Client Registration Endpoint}
    • GET /ws/oauth2/client or  /ws/oauth2/client/{client_id} {List registered clients endpoint. }
    • PUT /ws/oauth2/client {Client Updataion Endpoint}
    • DELETE /ws/oauth2/client {Client Deletion Endpoint}
    • Issue New Credentials Endpoint; If the client hits the Client Updatation Endpoint keeping all request parameters (client_id and client_secret) same, we should be able to issue a new pair of client_id and client_secret!
  • Identify the API methods that need to called by these controllers. This should be easy to backtrack by studying the controller methods for the jsp files that handle client management. 
  • Take a look at how the Spring Security and Spring Security OAuth2 projects are wired up in the module. Here's the xml file
  • Going through the available documentation for the OAuth2 module will be helpful (OpenMRS OAuth2 module - for Client Developers, OpenMRS OAuth2 Module - for Implementers, OpenMRS OAuth2 Module - for Module Developers ) . Also check out the resources section of this wiki
• Take a look at authentication scheme used by SMART Apps and identify how OAuth2 module can serve as the authentication manager for such apps 
• Come up with timeline along with how each week has used to develop the module to meet with required goals. 
• Create tickets in JIRA for tasks to be completed during GSoC.

Additional Tips for Proposal

While not mandatory at all, it would be great help if you include the following in your proposals:

• Specification for the REST API mentioned above (for each endpoint, specify the request parameters, special request headers if any, expected response in case of success and error)
•  UML Sequence Diagram for a SMART app communicating with OpenMRS FHIR module after authenticating through OAuth2 module. 

Requirements

• Good Java skills
• Familiarity with J2EE web programming (e.g., JSPs)
• Go through and understand the existig work on OAuth Module in Implement the OAuth2 Support for Web Services APIs
• Ability to learn and work with OpenMRS REST APIs and FHIR Module with HAPI 
• Familiarity / willing to learn OAuth
• Soft skills to interact with the HAPI and FHIR community and OpenMRS community in order to gather requirements and technical feedback
• Learn SMART Apps

Extra Credit

• Writing research paper on Oauth and how it has used in OpenMRS to integrate with systems or any other suitable topic

Resources

1. https://tools.ietf.org/html/rfc6749 
2. http://blog.facilelogin.com/2012/08/wso2-oauth-20-playground-with-wso2.html
3. Implement the OAuth2 Support for Web Services APIs
4. UI Framework Guide : UI Framework Step By Step Tutorial
5. http://docs.spring.io/spring-security/site/migrate/current/3-to-4/html5/migrate-3-to-4-xml.html 
6. Type of changes you can anticipate for the migration to Spring 4.x : https://github.com/spring-projects/spring-security-migrate-3-to-4/compare/xml?expand=1 
7. SMART on FHIR
   1. Authorization Guide
   2. Scopes and Launch Context