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.

  • 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 Eye On and off with icon Eye Off using the eye button in the top right corner of the screen. Masked Mode Gif
    • The ABAC policy named readMaskedData 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 database. 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 subject (e.g. a user) who wants to perform some operation (e.g. download) on an object (e.g. a file) in some environment. The subject, object and environment all have attributes (i.e. key/value pairs), and there are policies that control the privileges (i.e. what operations the subject 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.

Groups

Administrators can invite/add users to one or more groups.

Invitations

Users may be invited to groups in one or multiple organizational accounts on the LifeOmic platform by an individual with accessAdmin ABAC action (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 policies

ABAC Identifier Policy Name Description
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
downloadFile Download File allows a user to download file based data
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
updateData Update Data allows a user to alter existing subject data and files
layoutAdmin Administer Layouts allows a user to create, update, and delete subject viewer layouts
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.
billingAdmin Administer Billing allows a user to manage billing and usage
projectAdmin Administer Projects allows a user to create, update, and delete projects
apiKeyUser Manage API Keys allows a user to create and revoke their API keys for account access
developApps Develop Apps allows a user to develop and release custom built apps
eduContentAdmin Manage education content allows a user to manage education content published to users

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: January 31, 2020