OAuth module enhancements and SMART apps support

Owned by Sanatt Abrol
Last updated: Aug 14, 2018
4 min read

Primary mentor

Sanatt Abrol

Backup mentor

Harsha Kumara

Assigned to

Prabodh Kotasthane

Interested People

Final Project Talk Thread : https://talk.openmrs.org/t/gsoc-2018-oauth-module-enhancements-and-smart-apps-support-final-presentation/19472

Project Report : https://pkatgithub.github.io/GSoC-2018-Final-Evaluations/

Abstract

The OAuth2 module is functional with all grant types working against OpenMRS 2.x releases with work done in FHIR OAuth Smart Apps Integration . The objective of this project is to enhance the OAuth2 module by writing unit tests to increase code coverage, migrate from an XML based configuration to an Annotation based configuration wherever possible, upgrade Spring, Spring Security, Jackson and Hibernate dependencies to make sure the module works against the latest OpenMRS release. Another major goal is to fully integrate EHR-launch flow for the SMART applications. This functionality must be tested out against the FHIR module with SMART applications from the SMART App Gallery . Also, the module needs to add support for SMART app "launch scopes".

Note on the current state of module : The module is tried and tested against all OpenMRS 2.x releases upto OpenMRS 2.2-Snapshot. All grant types work and SMART applications run against the module with the manual-launch flow. REST controller to create and manage OAuth2 clients is integrated and works as intended.

Project Champions

Sanatt Abrol Mayank Sharma Harsha Kumara 

Goals

  • Upgrade Dependencies : Upgrade all the Spring, Spring Security, Hibernate, Jackson dependencies so that the module works against the latest OpenMRS release. 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 see the Platform Release notes [https://openmrs.atlassian.net/wiki/display/RES/Platform+Release+Notes+2.1.2].
  • Roles and Launch Scopes : At present, the module doesn't support any launch scope (Patient/read, Patient/write, etc.) See http://docs.smarthealthit.org/authorization/scopes-and-launch-context/. Implementing these launch scopes will make sure that the module works in accordance to the SMART Healthcare IT guidelines.
  • 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.
  • EHR-launch flow : As of now, the module can only run SMART application running standalone. See http://www.hl7.org/fhir/smart-app-launch/. To properly utilize the power of SMART apps, EHR-launch flow must be integrated in the module with all necessary UI additions.
  • 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.
  • Increase Code Coverage : Write unit tests for the untested code and increase code coverage. Follow OpenMRS Unit Tests Conventions and also add raw test data.

Expected Deliverables

  • An OAuth2 module compatible with the latest OpenMRS Platform and Reference Application (This is a priority!)
  • EHR-launch flow implemented in the module with all the necessary UI additions (Begin after the first deliverable is complete)

  • Increased overall test coverage.

  • Support for SMART scopes and launch context.

  • 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 cool. How can you get started?

  • Go through the OAuth specification (RFC 6749) and understand OAuth2 and it's grant types.
  • Go through the OAuth2 module and all child pages to see what work is already done.
  • Go through the project report  https://mavrk.github.io/GSOC-2017-final/ from last year's GSoC.
  • Run the module on your machine and test it's functionality. 
  • Study the data structures for Client and ClientDevelopers in OAuth2,'
  • Go through the Client REST Controller and study all the REST Endpoints properly.
  • Take a look at how the Spring Security and Spring Security OAuth2 projects are wired up in the module.
  • 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:

  • UI for the module with a list of all SMART applications with the feature to launch them directly from the EHR.
  • UML Sequence Diagram for a SMART app communicating with OpenMRS FHIR module after authenticating through OAuth2 module. (Both standalone-launch and EHR-launch flow). 
  • Use-case diagram for all the involved actors.

Requirements

  • Good Java skills
  • Familiarity with J2EE web programming (e.g., JSPs)
  • 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

Resources