Custom Web Apps

LifeOmic provides the ability to build your own custom web app that uses PHC platform APIs. An app must be initially provisioned by a LifeOmic team member. Customers can contact LifeOmic to get started with a custom web app.

High-level Architecture

Below is a peek into our internal architecture, showing both how custom apps are provisioned as well as how their use is regulated.

Custom Apps Architecture

Starting from the top left of the diagram:

  • oauth-apps-manager creates the Cognito client and app metadata. Creating an app requires the following items:

    • Account
    • Title
    • Description
    • Icon URL
    • URL
    • Status ("developing" or "live")
    • Allowed OAuth Scopes
    • Accounts allowed to use this app
    • Callback URL
    • Logout URL

  • oauth-apps-service manages these apps' metadata via DynamoDB.

  • provision-cognito defines the OAuth scopes for our entire system.

    • Examples are FHIR.read and FHIR.write.

  • Cognito holds each app's clientId, allowed OAuth scopes, etc. It handles both user authentication and scopes validation.

  • The token received from Cognito contains the granted OAuth scopes, which informs the policy generated by our lambda-authorizer.

  • API Gateway enforces app scoping by only allowing requests to the policy-specified HTTP endpoints / verbs.

OAuth Authorization Code Grant Flow

Custom Apps Auth Flow

The accessToken expires after 1 hour, and the refreshToken can be used for 24 hours. After 24 hours, the user must re-authenticate. When authentication is needed, on the first /authorize request in the diagram, our Auth Server will send the browser/user to a login form instead of granting the authorization code. Once the user successfully authenticates, the Auth Server will resume where we left off in the diagram (generate auth code, 302 to redirect_uri).

Custom app usage does not allow a user to do any more than their ABAC permissions allow. Custom apps have additional security checkpoints, as shown via the failed request attempts in the diagram above. Specifically, a custom app:

  • can only be used by those with the developApps ABAC permission while in "developing" status

  • is limited to certain API endpoints based on OAuth scopes

  • can only be used by specified accounts

Once a request has made it past these validations, the requesting user's ABAC permissions are still verified.

Custom Apps Request Security

Note: the LifeOmic-Account header is required for all custom app API requests, even if the endpoint does not specifically require it.

Developer Experience

High-level Steps

  1. Customer contacts LifeOmic indicating they'd like to create an app

  2. LifeOmic employee provisions app via our oauth-apps-manager, with status set to "developing"

  3. During deploy, the app generates a Cognito app within our prod user pool, and stores the appId against this app record via oauth-apps-service.

  4. The customer develops their app, using the app metadata (e.g. clientId)

  5. When ready, customer requests LifeOmic switch app from "developing" to "live"

  6. Users within groups for this account will now be able to use the app

ABAC

In order to access the app while in "developing" status, developers will need to have the developApps ABAC privilege.

App Tools Library

A simple javascript npm package called @lifeomic/app-tools is publicly available, which currently assists with authentication.

App Example

https://github.com/lifeomic/example-phc-app - provides an example reference PHC web application repository.

Hosting

The web app's static assets (html, js, css, images) will be hosted outside of the PHC. This means purchasing a domain and setting up a web server or CDN to host the content will need to be taken care of beforehand. This allows for custom apps to enforce custom security (e.g. whitelisting of IP addresses), or integrate with other back-end systems as needed.

It is important to note that developing and using a custom app has all the same restrictions and legal terms as hitting the PHC APIs directly.

Once a custom app has a status of live and users are using it to access and potentially manipulate data, the same security and legal terms apply as hitting the PHC APIs directly. Because this is also true when an app has the status of developing and the developer is using it, a staging account is strongly recommended.

Staging Changes

If there is a desire to stage changes across separate app environments, a new PHC account should be created. For example, if a custom app needs to be tested in a staging environment at https://staging.customer.com and users actively use it at https://production.customer.com, a new PHC account can be created in addition to the production account, which can be setup with the staging app up for testing. As noted below, another advantage of this approach is to ingest and work with mock data.

Last update: February 1, 2020