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.
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
andFHIR.write
.
- Examples are
-
Cognito holds each app's clientId, allowed OAuth scopes, and so on. 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¶
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.
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¶
-
Customer contacts LifeOmic indicating they'd like to create an app
-
LifeOmic employee provisions app via our
oauth-apps-manager
, with status set to "developing" -
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
. -
The customer develops their app, using the app metadata (for example, clientId)
-
When ready, customer requests LifeOmic switch app from "developing" to "live"
-
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¶
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 (such as whitelisting of IP addresses), or integrate with other back-end systems as needed.
Staging, Security, and Legal Considerations¶
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.