OAuth2 Module - for Implementors
- Sanatt Abrol
- Prabodh Kotasthane
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 2.0.1 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.
The module also supports SMART's EHR Launch Flow through which SMART apps can be launched from OpenMRS.
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 :
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 |
11 | oauth2_smart_app | maintains smartId and launchUrl of SMART clients |
12 | oauth2_smart_app_launch | maintains launch value generated and verified during EHR launch sequence |
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 REST controller). This will be changing soon. Only users with proper roles and permissions (client_developer) will be allowed to register
Manage Clients
The admins of OpenMRS instance will be see a list of all registered clients.
To manage clients using REST Controller see this