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 while making it reasonably difficult to violate the subject's privacy.

  • By default, most 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.

Masked mode is not de-identification. Instead masked mode is a "reasonable effort" at making it difficult to determine the identity of a subject and to maintain the privacy of the subject from casual observers. Masked data should still be consider Personal Health Information under HIPAA.

Masked mode specifically does the following to Patient records:

  • Human names are converted to initials.
  • All fields other than use, type, district, state, postal code, and country are removed from all addresses.
  • All identifiers are removed other than ones labeled ANON under the http://hl7.org/fhir/v2/0203 system
  • Day of the month and times are removed from all birth dates, and month is removed from all birth dates for subjects over two years of age
  • Text narrative, telecom, photo and contact person information are removed
  • The following top level extensions are removed:
    • http://hl7.org/fhir/StructureDefinition/birthPlace
    • http://hl7.org/fhir/StructureDefinition/geolocation
    • http://hl7.org/fhir/StructureDefinition/patient-birthTime
    • http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName
    • http://standardhealthrecord.org/fhir/StructureDefinition/shr-entity-FathersName-extension
    • http://standardhealthrecord.org/fhir/StructureDefinition/shr-entity-SocialSecurityNumber-extension
    • http://standardhealthrecord.org/fhir/StructureDefinition/shr-entity-DriversLicenseNumber-extension
    • http://standardhealthrecord.org/fhir/StructureDefinition/shr-entity-PassportNumber-extension
    • http://standardhealthrecord.org/fhir/StructureDefinition/shr-demographics-FathersName-extension
    • http://standardhealthrecord.org/fhir/StructureDefinition/shr-demographics-SocialSecurityNumber-extension
    • http://standardhealthrecord.org/fhir/StructureDefinition/shr-demographics-DriversLicenseNumber-extension
    • http://standardhealthrecord.org/fhir/StructureDefinition/shr-demographics-PassportNumber-extension
  • All other data on Patient records and other record types are not altered.

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 support both simple and complex access control needs.

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 privilege 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; view, create, and edit gene sets
readData View Data allows a user to list files, view subject data, view gene sets, create gene sets, and edit gene sets they've created
readMaskedData View Masked Data Only allows a user to list files, view subject data with identifying information masked, view gene sets, create gene sets, and edit gene sets they've created
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

Resource Types

The Create Data, View Data, Update Data and Delete Data privileges allow for the access to be restricted by resource type. For example you can give a group of users the ability to view and search for demographic, survey responses and consents for research subjects and complete surveys for the subjects with the following policy:

Custom Resources Example

The following is a list of the supported resource types:

Resource Type Description
Insights (insights) aggregate data that is viewable on the Insights and Subject Search pages; many of the Subject Search filter options
Patient patient demographics Subject Search filters (e.g. name, identifier) and Subject Viewer demographics details
cohort cohort data that is viewable on the Cohorts page or Subject Search
GeneSet gene set data that is viewable on the Knowledge, Subject Search and Omics Explorer pages
Questionnaire surveys configured on the Surveys page, consent terms configured on the Consents page, and FHIR Questionnaire resources
QuestionnaireResponse survey responses completed by subjects and FHIR QuestionnaireResponse resources
Consent consent agreement completed by a subject and general FHIR Consent resources
Terminology ontology and terminology data used in Subject Search filters, Insights layouts and Subject Viewer layouts
job granting Create Data access to this resource type allows a user to run bulk actions in Subject Search such as assigning surveys
FHIR Resource Types all FHIR resource types supported by the PHC, including: Observation, Condition, Procedure, etc...

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 date timestamp for when the deletion will occur.

{
    "id": "lifeomic",
    "name": "LifeOmic Research",
    "owner": "research@email.lifeomic.com",
    "type": "ENTERPRISE",
    "status": "ACTIVE",
    "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.

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: 2020-11-13