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.
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-managercreates the Cognito client and app metadata. Creating an app requires the following items:
- Icon URL
- Status ("developing" or "live")
- Allowed OAuth Scopes
- Accounts allowed to use this app
- Callback URL
- Logout URL
oauth-apps-servicemanages these apps' metadata via DynamoDB.
provision-cognitodefines the OAuth scopes for our entire system.
- Examples are
- 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
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
developAppsABAC 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.
LifeOmic-Account header is required for all custom app API requests, even if the endpoint does not specifically require it.
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
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
In order to access the app while in "developing" status, developers will need to have the
developApps ABAC privilege.
App Tools Library¶
lifeomic/example-phc-app - provides an example reference PHC web application repository.
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.
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.