Skip to content

Overview

LifeOmic is a software-as-a-service (SaaS) platform hosted on Amazon Web Services (AWS). LifeOmic uses a multi-tenant architecture (see diagram below), to offer near-infinite resource capacity when using the platform through the Application Programming Interface APIs.

Multitenant Architecture

In multi-tenant architecture, customer data is logically partitioned and segregated by software into the database via a Unique Account Identifier (Unique Identifier) associated with every piece of data.

Access to an account’s data is restricted to permissions granted to users.

Billing and usage tracking is rolled up by account.

This is a standard pattern used by cloud infrastructure and SaaS providers.

Account (organization) and User Entity Relationship Diagram

Entities

Terms

  • Person - A Person is a human being who uses the platform (e.g. a researcher, clinician, administrator, or patient).

  • User - Users represent people who are using the platform and provide authentication, demographic, and contact information. Users are not owned by accounts, and a single user may have access to multiple accounts via group membership.

  • Account - An account is the top level organizational structure for the platform. Typically each organization would have a single account. Accounts store the billing/payment method for an organization and are used by the platform to bill for usage.

  • Group - Groups live inside an account and are the primary mechanism of binding a user to an account and giving the user access to data in the account.

  • Policy - ABAC (Attribute Based Access Control) policies control what groups have access to what projects in an account. Policies live inside an account.

  • Project - Projects form an organizational structure under an account and also provide a finer grained breakdown of usage for internal accounting inside an organization. Projects are the typical granularity for access control. Projects are also used to aggregate storage costs up to an account. In our APIs, "dataset" is synonymous for "project".

  • Cohort - Cohorts are basically a saved search. They provide a way to pull in data from multiple projects and subsets of projects. Typically, cohorts do not result in data copies or extra storage costs (except for ephemeral data used for analysis).

  • Data - Data are all the various pieces of data about patients that are stored in the platform. Data can be just about anything. Some examples: Patient, Observation, Condition, Procedure, Medication, Image, ClinicalReport, BAM File, VCF File, etc... Data is stored inside a project within an account.

  • Patient - A Patient resource is a type of data that stores the demographic information for a Person as a research subject, patient, customer or employee in a project within an account.

User and Patient Mapping

The Precision Health Cloud has two representations of people:

  • Users - these are people who can log into the PHC and interact with it: employees, partners, or customers/subjects/patients.
  • Patients (aka Subjects) - these are people whose health data is tracked by the PHC. A Patient resources does not, by itself, give a person any access to the PHC.

A User can be mapped to a Patient (via an invitation, see below) so that you can have a person who both signs into the PHC and has their health data stored in the PHC. When a User is mapped to a Patient this grants the User access to the data for the Patient via an ABAC policy associated with the Subjects group. The Subject Access policy and Subjects group are created automatically by the PHC. When a User is mapped to a Patient the User record also provides a way to send notifications to the person via email (using the email address on the User record) or push notifications (via the LIFE Extend mobile application).

User records are created automatically when someone signs up for the PHC, and can be associated with an account via an invitation. The two types of invitations are:

  • Account Invitation - This simply adds a User to a Group when the person accepts the invitation. The User has whatever access is granted to the group via an ABAC policy.
  • Project Invitation - This works like an Account Invitation but also maps the User record to a Patient record in a particular Project. The group for Project Invitations is always the Subjects group.

For both types of invitations the person being invited will receive an email directing them to signup or login and accept the invitation. See groups for a step-by-step guide to inviting users.

Masked Mode

Masked Mode allows users to review genotype and phenotype data for patients/subjects without jeopardizing the patient's privacy.

  • By default, viewing patient data with personally identifiable information is masked from view.
  • Masked Mode can be toggled on with icon and off with icon using the eye button in the top right corner of the screen. Masked Mode Gif
  • The ABAC privilege named Read Masked Data can be used to force a set of users into masked mode.

Access Control

Access Control refers to the ability to control who can interact with a resource within the platform. The LifeOmic platform uses Attribute Based Access Control (ABAC) to assign different attributes and dictate what information users have access to in cases requiring complex Access Control.

For example, if you have a user who wants to perform some operation (e.g. download) on a resource (e.g. a file) in some environment. The user, resource and environment all have attributes (i.e. key/value pairs), and there are policies that control the privileges (i.e. what operations the user can perform) given the attributes.

More information on ABAC can be found in sections 1 and 2 of NIST's Guide to Attribute Based Access Control.

Click here for a step-by-step guide for setting up user privileges.

Invitations

Users may be invited to groups in one or multiple organizational accounts on the LifeOmic platform by an individual with the Access Admin ABAC privilege (see ABAC policy chart below) for the given project.

These invitations must be accepted by the invited user before they are active.

See Inviting Users to a Group for more details.

ABAC Privileges

ABAC Privilege Privilege Name Description
accessAdmin Administer Access allows a user to create, update, and delete groups and policies
accountAdmin Administer Account allows a user to update and delete the account, manage auth clients, and configure clinical trial matching.
apiKeyUser Manage API Keys allows a user to create and revoke their API keys for account access
billingAdmin Administer Billing allows a user to manage billing and usage
createData Create Data allows a user to add new subject data and files
deleteData Delete Data allows a user to delete subject data and files
developApps Develop Apps allows a user to develop and release custom built apps
downloadFile Download File allows a user to download file based data
engagementAdmin Administer Engagement Flows allows a user to configure and add subjects to engagement flows
layoutAdmin Administer Layouts allows a user to create, update, and delete subject viewer layouts
projectAdmin Administer Projects allows a user to create, update, and delete projects
readData View Data allows a user to list files and view subject data
readMaskedData View Masked Data Only allows a user to list files and view subject data with identifying information masked
ruleAdmin Administer Rules allows a user to create, update, and delete rules
updateData Update Data allows a user to alter existing subject data and files

Account Deletion

The LifeOmic Core API exposes an endpoint for deleting an account and all data associated with the account. This operation can only be requested by a user that has the accountAdmin ABAC action for the given account. The account data will not be deleted until after a 14 day grace period. The account API resource will be updated to indicate the pending deletion (see below) along with a date timestamp for when the deletion will occur.

{
    "id": "lifeomic",
    "name": "LifeOmic Research",
    "owner": "research@email.lifeomic.com",
    "type": "ENTERPRISE",
    "status": "PENDING_DELETION",
    "deletionDate": "2018-07-02T19:36:00.683Z"
}

During the 14 day grace period, a user will be able to continue accessing data from the account, and can also remove the pending deletion from the account. Applications like the PHC web app will display warnings for accounts that are pending deletion by showing the time remaining in the 14 day period.

After the 14 day grace period, the following is a list of all known account related data that will get deleted as part of this operation:

  • Files, projects
  • FHIR resources
  • Invitations
  • Account, Custom Auth Clients, ABAC policies
  • Variant Sets, Read group Sets, Expression data sets
  • Analytics data
  • ML data

Project Deletion

The LifeOmic Core API exposes an endpoint for deleting a project and all data associated with the project. This operation can only be requested by a user that has the projectAdmin ABAC action for the given project. The project data will not be deleted until after a 14 day grace period. The project API resource will be updated to indicate the pending deletion along with a date timestamp for when the deletion will occur.

{
    "id": "uuid",
    "name": "Germline Sequencing",
    "description": "Indexed VCF and BAM files from a sequencing project.",
    "status": "PENDING_DELETION",
    "deletionDate": "2018-07-02T19:36:00.683Z"
}

During the 14 day grace period, a user will be able to continue accessing data from the project, and can also remove the pending deletion from the project. Applications like the PHC web app will display warnings for projects that are pending deletion by showing the time remaining in the 14 day period.

The following is a list of all known project related data that will get deleted as part of this operation:

  • Files
  • FHIR resources
  • Variant Sets, Read group Sets, Expression data sets
  • Analytics data
  • ML data

The delete project API will provide an override that will forgo the 14 day grace period, and all project related data will be deleted as soon as technically possible.

User Deletion

The LifeOmic Core API exposes an endpoint for deleting a user. This operation can only be requested by the same user. If the user is pending deletion, clients can decode the access token and check for the deletion_date claim to see if the user is pending deletion and display the appropriate warnings to the user and allow them to remove the pending deletion.

{
    "sub": "uuid",
    "cognito:groups": ["us-east-uuid_Google"],
    "token_use": "access",
    "scope": "phone openid profile email",
    "auth_time": 1527763897,
    "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_uuid",
    "exp": 1527767497,
    "iat": 1527763897,
    "version": 2,
    "jti": "f4766f73-b376-48de-b6e3-38857d63uuid",
    "client_id": "id",
    "username": "Google_username",
    "deletion_date": 1527763897
}

After the 14 day grace period, the following is a list of all known user related data that will get deleted as part of this operation:

  • User group memberships
  • User profile in Cognito
  • LIFE data

Notifications

For each of the delete scenarios, email notifications will be sent at the following times:

  • When the account/project/user delete request was initiated.
  • A few days before the account/project/user will be deleted.
  • After the account/project/user has been deleted.

For deleted accounts and projects, emails will be sent to the address specified in the owner field of the account resource. Users will be emailed directly for user deletions.


Last update: July 10, 2020