OpenMRS OAuth2 Module - for Implementers

Quick Introduction

The OpenMRS OAuth2 Module converts any OpenMRS installation into an OAuth Provider. It is based on the OAuth2 protocol and uses Spring Security and Spring Security OAuth2.

Currently, the module has been tested to work on OpenMRS 1.11.x and it protects FHIR resources by default. However, it is easy to extend the module to protect any other resource on any OpenMRS installation. See the section for Module Developers to know how.

Installation

The OAuth2 module is installed like any other module but we have to keep in mind that the order of installation for  the OAuth2 module and modules that expose protected resources. It may be important to install the OAuth2 module before any other module resources are to be protected by the OAuth2 module. If the protected module has defined servlet filters in its config.xml, then it becomes mandatory that the OAuth2 module should be installed before the protected module. 

To explain this, we need to understand that Spring Security is implemented a Filter Chain that intercepts requests to the protected resources, authenticates the request and then forwards the user to the protected resource. Therefore, it makes sense that the filter chain of spring security should sit before the filters of the protected modules, otherwise spring security would fail to properly authenticate the incoming request. This fact is also mentioned in the documentation of spring security project.

When modules are installed in OpenMRS,  the filters are loaded in the order of installation. Therefore make sure that there are so such conflicts when installing the OAuth2 module and OAuth2 module's filters (spring security filter chain) are loaded before filters of protected modules.

Database Structure

Upon successful installation the following tables will be added to the database :

S.no

Table Name

Description

S.no

Table Name

Description

1

oauth2_client

stores basic information about registered clients

2

oauth2_client_authorities

stores the granted authorities for registered clients (ROLE_CLIENT for now)

3

oauth2_client_grant_types

stores authorization grant types for registered clients

4

oauth2_client_redirect_uri

stores redirect_uri's for registered clients

5

oauth2_client_resource_ids

stores the permitted resource id's for registered clients

6

oauth2_client_scopes

stores the scope for registered clients

7

oauth_access_token

stores access_tokens for each client. will be deprecated

8

oauth_client_token

stores access tokens

9

oauth_code

maintains authorization code

10

oauth_refresh_token

maintains refresh tokens

Manage Client Developers

Client Developers are those users of an OpenMRS installation that develop OAuth2 clients i.e applications that use OpenMRS's web services protected by the OAuth2 module. At present, all users are allowed to register OAuth2 clients (via the dashboard). This will be changing soon. Only users with proper roles and permissions (client_developer) will be allowed to register clients.

The Admins of the OpenMRS instance will be able to disable any clients using their dashboard. 

Manage Clients 

The admins of OpenMRS instance will be see a list of all registered clients