Login and home pages in OWAs

I just peeked at the code being written for https://issues.openmrs.org/browse/OWA-71 and I want to propose a completely different direction, which may be a bit more work up front, but is a better and more sustainable approach going forwards.

(The current PR involves hardcoding specific knowledge about the Add on Manager OWA into the OWA module, which is bad style.)

We should allow OWAs to, within the OpenMRS-specific part of their manifest file, indicate that they provide a login screen that applies to the entire application. E.g. something like this:

"activities": {
    "openmrs": {
        "href": "*",
        "login": "/owa/addonmanager/index.html#/login"

The OWA module would know which OWAs provide a login screen, and if any does, it would redirect there. (It can still fall back to the current behavior of /login.htm?redirect=" + url if no OWA provides a login page.)

If more than one OWA provides a login screen, then we’d have a global property to indicate which one is preferred (or arbitrarily pick the first one if this isn’t set).

I think we’d also want similar behavior for an OWA-provided “home page”, i.e. the screen that the login page sends you to if no redirect url is specified.

/cc @dkayiwa @elbertbiggs360


PS- I had assumed this ticket was part of the effort to do a new login/home OWA for the refapp, but now I’m thinking it’s actually just for the OWA manager work.

Given that I think it’s even more important that we have a forward-looking design.

Also, now that I think of it, I would expect the OWA module to try to take over the login.htm and index.htm screens, so this refapp code would go away, and instead we’d just have a new OWA included in the refapp that indicates it takes the login and home pages.

(This would also make it easier for someone else to build on top of the refapp and modify its login screen.)

Does “entire application” mean the OWA’s “application”? Or the OpenMRS instance?

I"m not excited about setting a precedent of OWAs creating their own login screen and competing for which one a user sees. Web apps should, in general, assume authentication will be provided by the Platform. I really don’t want to end up in a place where many OWAs have their own login screen.

How about if we make the platform’s login URL configurable?

  • We create an OWA with a RESTful login screen that is as good or better than most, so most folks will be happy to just use what comes out of the box. This could eventually grow to be skinnable (i.e., easy to adapt for local branding).

  • We support a loginURL setting in the Platform that, by default, points to the login OWA, but could be changed if someone wants to take over the login page. The platform would add the ?redirect= parameter to the value of loginURL.

In effect, we encourage people writing OWAs to assume a login screen will be provided – i.e., discourage developers from creating an login screen for each OWA – by making the login screen decision in the platform instead of in an OWA. In the event that someone wants to override the default login screen, they can configure the platform to use their OWA’s login URL.


We can create a Login OWA that handles the login functionality and eventually grows to be skinnable as @burke suggests

Then we can add support for the loginURL setting pointing to the OWA by default.

In addition to what @darius is suggesting, we can also add a manifest configuration that checks if the OWA provides login functionality and set the provided login value to the loginURL so that the OWA effectively takes control.

The main argument in favour of that manifest setting is to automate the loginURL update option.

It however may easily create conflict if a user installs an OWA that overrides the loginURL and the user had no intention of changing it

I agree with what @burke states, that their is need for an OWA with a RESTful login, which after logging in can utilize a redirect to the specific URL that was initially requested or to a default URL for the case of their being no initial request.

But basing on this logic that ensures that a user has to be authenticated before an OWA can be loaded would allow for what @darius pointed out, where by a check of whether the OWA contains a login link would also determine if the OWA can be loaded and by default the login OWA would contain it.

And what about the decoration of OWA pages? Headers, footers, breadcrumbs, and links to switch between locales (and the client-side code behind it)? All this should also be available to all OWAs as well as the login page would.

I agree that most OWAs should not create their own login screens, and I meant to say explicitly that the addon manager owa should not provide its own, but rather we put this in a “platform login owa”. Your OWA should only provide a login screen if it has some special need to do this, i.e. it’s the OWA that’s defining the entire application.

Let me give some of my background thinking here:

  1. In principle, the login screen is a concern of the Application, not the Platform. We claim that our platform is generic for all use cases, so therefore it won’t naturally have the right login screen for any particular class of OpenMRS application.
  2. In practice, the major projects I have been involved with over the years have all needed their own new login screen for legitimate reasons: Mirebalais (eventually RefApp) needed to add “login location”; Bahmni needed it to be built in AngularJS; Ebola needed a “team-based login”.
  3. I want to enable someone to build a completely new OpenMRS application with purely the Platform + OWAs + (optionally) modules.
  4. I want the Reference Application to become more extensible so that it can properly be the basis of a different distribution.

So I would expect the platform to define and include a simple login screen that’s sufficient to give access to the bundled administrative console (e.g. addon manager). This can be the “platform login owa”

And I would expect the Refapp to define and include a fancier login screen (including “login location”, and more skinning options). This can be the owa we recently discussed on a design call that would include the refapp’s login and home screens.

If I were rebuilding the ebola tablet application today I would want to take the platform, and add a new login OWA that overrides the others.

So, I’m fine if the version of this code we write first is to have a loginUrl setting (and perhaps a homeUrl also).

But in the longer run, we should allow Platform + OWAs to define an entirely new application, so we need OWAs to be able to indicate they want to own the login process. (Right now you’d need to have a module to be able to do this in its activator. I think we want to provide OWAs a similar mechanism.) Or alternately if we follow Bahmni more in the direction of having separate application + configuration, then it’s fine for this to continue to live in the config.

(And having written all this I guess we might need a way for OWAs to indicate precedence, e.g. platform has precedence=1, refapp has precedence=10, ebola would give precedence=100.)

This is one of the things I’m trying to avoid. I consider this pattern of precedence/weighting among unrelated peers to be an anti-pattern prone to problems over time. The selection of which login is used should be explicit and predictable and not an ill-defined competition between who made their precedence highest.

I’d favor either having predefined preferences of platform, refapp, and application with the behavior of duplicates undefined or create separate mechanisms for overriding platform login vs refapp login, obviating the need for a precedence setting.

Stepping back, the underlying issue is that we don’t have a standard way to provide configuration to OpenMRS in the form of a file/folder.

I want to be able to package OpenMRS Platform, plus some files (OWAs, OMODs, and config files), and have this distribution start up correctly with the correct UI the very first time. At present you can do this using OMODs (since they have Java activators, etc), but you can’t do it with just OWAs, which is why I was proposing an (admittedly-brittle) approach of signaling by the OWA.

The problem with what has been described so far is that

make the platform’s login URL configurable

…means to have a global property. And that requires SQL, a REST call, or a manual step to configure on your server. Practically, it would be a pain to build a docker image for this distro.

I’d be satisfied with the solution of (1) this is controlled by a global property, and (2) create a ticket in openmrs-core to support setting GP values based on a file at startup, to eventually address my goal.

Maybe now is the time to get the initialiser module, https://github.com/mekomsolutions/openmrs-module-initializer, into play

A configuration where a user can add a file into an OWA that can be used for configuration

Discussed on today’s design forum: http://notes.openmrs.org/2018-02-28-Design-Forum

@dkayiwa is responsible for next steps (mainly, organizing that work for various Andela teams)

1 Like

We briefly peeked at this again on today’s design call. Status update:

  1. openmrs-core takes ownership of “(WEBAPP)/login” and “(WEBAPP)/” or “(WEBAPP)/index” urls => STILL NEEDS A TICKET; @dkayiwa to create

  2. OWA module should redirect to the platform’s /login page (instead of the current /login.htm) => DONE at https://github.com/openmrs/openmrs-module-owa/commit/196b315d4c70c5511a4850a39b53cff5e3883024

  3. Create a new very simple “Platform UI” OWA for the platform => DONE at https://github.com/openmrs/openmrs-owa-platformui

  4. Create a login + homepage OWA for the RefApp => TO DO Code should go in https://github.com/openmrs/openmrs-owa-referenceappui but this is not done yet

  5. Release notes would need to explain how to preserve the legacy UI look and feel after upgrade => TO DO

1 Like