GSoC 2018 - OAuth module enhancements and SMART apps support

@mavrk - I am inspired by the success of your previous your previous year work on this parent project. Since I am pretty new to this community, I want to get started quickly and add some unit test code coverage. Some basic questions -

  • I must learn, at least some fundamentals of OpenMRS platform, so I am planning to get an understanding of OpenMRS platform first, before touching your github repos from last year, right ? or Should I prioritize this for later ?

  • You mentioned - Android Client demonstrating Password protocol flow (Bonus Karma points, if time permits). You mean a new Android Client, like the one - I am planning to add iOS client, what do you think about it? both android and iOS weigh same priority or different?

1 Like

It’s good to see that you pointed it out. I’d recommend that you get some fundamentals of OpenMRS platform first. Go through the OpenMRS devguide if you haven’t already have. Clain some intro tickets (TRUNK, RA, etc.) from the JIRA and try to submit a pull request. Don’t forget to go through the pull request conventions before making a pull request.

NOTE : Create a new case at OpenMRS Helpdesk stating you’d like to contribute and would like edit access to Wiki and JIRA. Because of spammers, we must require this extra step before you can edit wiki pages or make any changes to JIRA tickets.

The main purpose of this bonus task is to give the community a use-case for the OAuth2 module. It can be ANY android, iOS or OWA application. All we need to show is the possibilities OAuth2 can offer to the community. And if you can make use of OAuth2 module using an iOS application then it’d be great :wink: PS : this is only a bonus task and we’ll take it up only if time permits :slight_smile:

1 Like

Thank you for the valuable insights. I am on it :slight_smile:

@mavrk - Now, my grasp over OpenMRS development architecture improved a lot. I am able to build and run OpenMRS-core, OpenMRS-WebService in my local machine. Also followed wiki pages for starters entirely. I see this ticket(RESTWS-648)is something related to this project. Right now, I am stuck what to work on, but above ticket looks doable for me. Let me know for any comments.

1 Like

@ajay let’s keep this thread only for doubts related to the OAuth module project. I am happy that you took up an issue and you are showing willingness to contribute. I’d recommend that you start a new thread for doubts related to this particular ticket, that way more people can help you. And regarding where to start on this ticket, I’d recommend that you look at spring and spring security. These two important frameworks also form the backbone of the OAuth2 module. I’d also recommend that you see

1 Like

After two weeks of study about the OAuth module and this project I have came up with the following understanding and queries :

Firstly about the OAuth module :

  • I now have idea about what is OAuth2 and how does it work. What are roles, what are the different grant types, how does the OAuth2 protocol flow, what are refresh and access tokens, how does client registration and authorization happen etc.

  • I have gone through the module related documentation and links provided. I got the basic know-how about the dependencies, how the OAuth module works and how the module interacts with the other modules.

  • Following the previous development work on the module, I got to know about what has been done and which frameworks/technologies have been used. I learnt about spring boot, spring security, hibernate and SMART.

Coming to the project related part :

Listing the project goals as -

  • 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 [Platform Release Notes 2.1.2 - Resources - OpenMRS Wiki].

  • Roles and Launch Scopes : At present, the module doesn’t support any launch scope (Patient/read, Patient/write, etc.) See SMART on FHIR 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 HL7.FHIR.UV.SMART-APP-LAUNCH\Overview - FHIR v4.0.1. 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.

My observations and queries one by one are :

  • Upgrade dependencies : I have got an idea about the dependencies. I just wanted to know that is the platform release 2.1.2 the latest one? If so, then as the module is tested with OpenMRS 2.x releases upto OpenMRS 2.2-Snapshot, do we only need to migrate the spring and hibernate dependencies? Also recently Spring 5.x being released, do we have to migrate to Spring 5.0.x? Same question with the Hibernate 5.2.x release :slight_smile:

  • Roles and launch scopes : After reading about different launch scopes, i have got the basic knowledge about what are they and how they are used. I am planning to study about how they can be implemented :slight_smile:

  • Switch to Annotations where possible : Yes, going through the code , I saw that the configuration is done using xml files. I am learning about how to configure using java files with the help of annotations.

  • EHR-launch flow : “As of now, the module can only run SMART application running standalone”. I think this means that at present, only standalone launch sequence is supported and we have to upgrade the module so as to support EHR launch sequence(As shown below). Am i right?

  • Use-case implementation : As of now i didn’t understand this goal. Any help will be appreciated :slight_smile:

  • Increase Code Coverage : Going through the code I found that many more unit tests are to be added. I am learning about how to write tests using the conventions of OpenMRS. I will try to identify them and surely progress in this section soon :slight_smile: .

I would really like to thank the community for providing such an excellent documentation. It helped me a lot. Each and every help will be appreciated :slight_smile:

@mavrk @maany @harsha89 Please have a look at this and guide me.

Thank you :slight_smile:


Hey @pkatopenmrs I am glad that you’ve done some homework on your behalf :slight_smile: Now coming to your queries,

OpenMRS 2.x platforms are based on Spring 4.x and Spring Security 4.x so by “upgrading dependencies” we mean to upgrade dependencies to the latest OpenMRS release and the Spring and Spring Security versions compatible with it.

Yes, we need to support functionality for both EHR based and standalone launch flow.

We need to give the community new use-cases for the OAuth2 module i.e. give implementations of the module which can be any Android / iOS / OWA / SMART application making use of the OAuth2 module.

1 Like

Thanks @mavrk

Keeping the points you stated, I will continue my study and understand more about the stuff.

Thanks again :slight_smile:

1 Like

Hey @mavrk I have got some queries.

About the use case implementation, i saw your final presentation for GSoC 2017 explaining the SMART app Authorization code grant type use case. I saw u creating a small demo SMART app. Just wanted to know that to implement the other use cases, whether we have to design a OWA and Android client too?? Or we have to use a existing OpenMRS OWA and Android client as stated in the expected deliverables of the project?

Also , in order to implement the EHR launch flow , I think we need to make changes to UI in order to launch the app from OpenMRS itself. Am i right?

Help will be appreciated. :slight_smile:


Prabodh :slight_smile:

You can make any client side application for the Use case demonstration. If you can add support for OAuth2 module in the OpenMRS Andriod App or OWA app then that would be a big plus. The choice is up to the student.

1 Like

Hey @mavrk , currently spring and spring security are both moved to releases 5.x. So in order to upgrade dependencies i need to get familiar with these versions and the changes. As of now i think it obviously will take time. So can i put some links,from which i am learning these, in my proposal?

Hello @pkatopenmrs, by “upgrading dependencies” we mean upgrading them to a version compatible with the current versions of Spring and Spring Security used by OpenMRS 2.x So you’ll have to upgrade to a 4.x.x version of Spring and Spring Security compatible with the Spring version used by the latest stable release of OpenMRS at the point of official start of coding in the summer. :slight_smile:

1 Like

Ok @mavrk now i understood this thing :slight_smile: . But considering this i checked the dependencies for the latest platform release that is OpenMRS 2.1.2 and found here that the versions used are Spring 4.1.4 and Hibernate 4.3.9 which are same as used the OAuth2 module right now. Does this means that right now we dont need to make any changes?

Please cross check and clarify :slight_smile:


Yup, that means that the versions remain the same. However, at the time of project submission we want the module to run against the latest version of OpenMRS at that time.

1 Like

Ok :slight_smile: Thank you for your help and instant reply :slight_smile:

1 Like

Hey @mavrk. I am failing to login to OpenMRS when including the OAuth module. The error says:

HTTP Status 404 - /openmrs-standalone/login.jsp

Can you help? :confused:

Hi @pkatopenmrs OAuth module creates a filter chain and the login link is in the filter configuration xml files. In this state, you can log-in at http://localhost:8080/openmrs-standalone/login and you’ll be presented with a basic log-in screen. One can customize this screen to have the look and feel of default OpenMRS login screen. You can do this task if you want to. Just create an issue ticket on JIRA under OAuth module and submit a pull request :slightly_smiling_face:

1 Like

thank you :slight_smile:

@mavrk last year in your project, you made a simple SMART application to test the support for SMART apps in the module right?
I saw the app at your github repo. I wanted to ask that I would also need a SMART application, to test the new functionalities added during the project, so can I use the same app?

One more thing i have to ask you is about the UI changes we need to make.

Do we need to add the SMART app related UI to the reference application homepage? Or on the administration page ?

can you please give me a idea about this? :slight_smile:

Regards :slight_smile:

Can we show like this?