Wiki Spaces


Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack


Page tree
Skip to end of metadata
Go to start of metadata
Primary mentorHarsha Kumara
Backup mentorSuranga Kasthurirathne
GSoC studentMayank Sharma


The purpose of this project is to implement the OAuth2 support for the OpenMRS Webservices APIs. OAuth2 is welknown and popular standard in securing the webserives APIs where user can invoke services through access token without exposing their credentials. OpenMRS has two main web services projects  which are OpenMRS restful web services module[5] and OpenMRS FHIR module[1]. So the main target is to  implement the OAuth support for platform where OpenMRS act as a OAuth provider. 

This requirement is mainly coming from OpenMRS FHIR module which OpenMRS has recently undertaken a commitment to implement FHIR in order to ensure better interoperability between healthcare systems. The OpenMRS FHIR module was developed as part of these efforts. Currently, there is need to support the OAuth2 for the FHIR Module.

Specification :


  • 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

Project champions


  • Go through the OAuth specification and understand OAuth2 and it's grant types
  • Go through the available samples in web to understand the implementation(6). 
  • Develop OAuth based security module for OpenMRS 
  • Come up with set of UI mockups for application creation and authorization
  • Create a new module following Creating Modules (improve the documentation if needed)
  • Apply for a repository at and a JIRA project
  • Create tickets in JIRA for tasks to be completed during GSoC
  • Design and implement the module API layer
    • API layer need to have a validateToken method which takes incoming token to check whether it's valid or not. The service will be a spring service where FHIR Module and Web Service module call to validate the incoming token. 
  • Design and implement the module OMOD layer
  • OMOD layer should support for following endpoints (Twitter API tutorial will helpful in understanding below endpoints During the implementation we may simplify the endpoints

How FHIR and REST Module Interact

Extra credit

  • Developing a client and demonstrating how different OAuth grant types can be support from the OAuth module



  1. Work already completed under phase 01 of the FHIR module
  2. HL7 FHIR wiki
  3. OpenMRS FHIR GitHub Repo
  4. SMART enabled oauth
  5. OpenMRS REST Module
  7. TRUNK-381 - Getting issue details... STATUS
  • No labels


  1. Hi,

    I would like to discuss more about this project. I found two dead links, can you please fix these two.

  2. Hi Sashrika,

    You first link is need to be corrected as you mentioned. 

    Second link seems down. 

    I'm happy to discuss with you on the project. Please contact me if you need any clarifications on this. Ask any question regarding the project. (smile)




  3. Thanks Harsha,

    So many things to get clarified (smile) . First I'll ask some high level questions to get an understand about the project.

    As a typical scenario, I think these are the tasks that we have to complete. 

    • Develop a module to support Oauth.
    • First we can register an application/domain which is willing to consume web service using Oauth. There application will get a secret key/consumer key  pair.There the application can also register an redirect URL where the module can redirect the browser with an access token after the authentication process. 
    •  Begin the Oauth process application will redirect the browser to OpenMRS authorization server. An end user who is willing to use this module to consume web services, should first register himself/herself in this module. There he will need to login to openMRS and grant the necessary permission to the client application. 
    • After that  OpenMRS authorization server will generate an access token/authentication token and sent it to the client application. 
    • Application extracts this access token and use it to consume web services. access token can be used inside the REST HTTP headers.
    • FHIR/RESTWS Modules will extracts this access token and check the authenticity of the user whether this particular user has access to this particular web services. 

    Is this the very general workflow that need to be implemented? 

    1. Hi Sashrika,

      The tasks and the workflow that you mentioned above is correct.

      Basically we need to support for the all the grant types specified in the OAuth specification. Client should be able to get access token through any grant type. 




      1. Hi Harsha.
        Why we allow any grant type? Is that because, for the time being, we going to allow any user with a valid access token? 

        1. Hi Shashrika,

          If we support OAuth2 specification, we need to support for all the grant types. Each of the grant type has their own pros and cons. For example Implicit grant more usable in front end javascript applications as it not require application key and secret. Also it's valid for certain time period. Likewise if we support OAuth2, we need to support all the grant types. But it shouldn't be a much effort if you can implement a one grant type.

          If the token is valid, then there is no issue with accessing the APIs. Also we need to focus on OAuth2 scopes too and how we can adopt them to our implementation.




  4. Harsha,

    I added the rest web service module and tried to consume web services. 

    using http://localhost:8081/openmrs-standalone/ws/rest/conceptdatatype.

    But it throwa a exception

    message"Resource does not exist. Please check documentation for implemented resources and their paths"
    detail" at 

    Do you have any idea?
    1. I'm not quite sure why you get this exception. Message indicate that resource doesn't exist. May be you can check underline OpenMRS version to check whether it's compatible with the REST module.

      You can try FHIR module easily. 

      1. Oops. That might be the case. It says that REST module recquires 1.9.0 or 1.8.1 to run. But i have 1.11. 

  5. Harsha,

    I went through thread about this project.!topic/dev/Pwy5YqMzH0A

    So what has been the final decision now? As per my knowledge, I believe there is no need of making a Oauth provider. because eventually what the end users going to consume is OpenMRS server web services. When that server instance is down, users will not be able to consume its web services. So if we can make OpenMRS server a Oauth provider by implementing an additional module, that seams enough. So there is no need of making a Oauth provider and worrying about its availability and security issues. 
    Because when the OpenMRS server is down end users cannot get an access token/authentication code nor use the web services. Base on that, I think there is no point in making a Oauth provider , just to  add authentication to "OpenMRS web services". 

    What is your opinions?


  6. Hi Sashrika,

    It's about providing OAuth login capabilities for Which you login to jiras through your openmrs ID. So it's a separate thing. (smile). We though of adopting OAuth capabilities if it existed. So as reply suggest there is no OAuth provider implementation existed for 

    Hope I'm clear to you (smile)



    1. There i found some discussions about whether to make a Oauth provider or allowing external Oauth providers into the picture. Thats why I raised that concern (smile).

      Any way i started to going through the OAuth2.0 specifications that you have posted here. Seems like it is a good document. Earlier i went through Google Oauth provider documentation. I'll get back to you after that. 


      1. Great. Finally we come into conclusion that we need to be the OAuth provider (smile) . So we need to get this module up to support FHIR and REST webservices to expose through OAuth2. 


        1. Great! That was the doubt in my head. And I found an interesting thing in the RFC specification. 

          "The authorization server
             may be the same server as the resource server or a separate entity."

          This is the thing what we now trying to do. Thing was i haven't seen such a system where the authorization server becomes the client as well (smile)

          1. Yeap client and authorization server are two different things. Client may be a js app, mobile app , sdk or any other client app. Requirement is to provide the OAuth2 support for exposed APIs of a OpenMRS server. 

            I think the RFC says. two things. What we going to do is becoming the both service provider and the resource provider same time. Some application uses other vendors like google, yahoo and etc as external OAuth provider so you need to have account on those vendors too. 


  7. Hi Harsha, 


    I am interested in this project. I have worked with OAuth in some previous projects for accessing Google APIs, and I think it is a great mechanism of accessing resources from third party applications. I  would like to discuss in more details the specifications of this project. 



    Zakaria Amine

  8. Hi Zakaria,

    You can contact me through Also go through the OpenMRS guidelines on participating to GSoC. You will need to do couple of contributions to the platform.



  9. Thanks. I will get back to you soon. 



  10. Harsha,

    1) IETF specification says, the access tokens should be transmitted though TLS. But AFAIK OpenMRS server doesn't implement TLS. So how we going to address this? Will we need to implement TLS in OpenMRS?

    2) Shall I move this discussion to OpenMRS talk platoform? There we might be able to get the others opinions as well.


    1. TLS means that you should be able to request the token through htttps. So it's there (smile)

      1. Really, I am not aware of that (smile). Because i have only used OpenMRS using the standalone version and deploying the war file. There i never see HTTPS. I thought it only supports HTTP. 

  11. Sure let's move the discussion to OpenMRS talk (smile)

    1. Ok, I'll start a new topic there. 

  12. user-c72cb

    Hi Harsha,

    I would like to contribute in this project. Is this project done?