Role-based access control (RBAC)

SeqsLab role-based access control (SeqsLab RBAC) allows administrators to enforce fine-grained access to datasets, tools, and jobs. Registered users may have limited read and/or write access permissions depending on their assigned roles, ensuring the secure storage and processing of potentially sensitive genomic and biomedical datasets.

Table of Contents

Overview

What is RBAC?

Role-Based Access Control (RBAC) is a security framework that restricts system access based on a user’s role within an organization. Instead of assigning permissions directly to individual users, SeqsLab groups permissions into roles that align with specific job functions.

Why RBAC?

• Security: Ensures users only access resources necessary for their job function

• Compliance: Meets regulatory requirements (HIPAA, GDPR, CLIA/CAP) for genomic and clinical data

• Simplicity: Easier to manage permissions for groups of users rather than individuals

• Auditability: Clear tracking of who can access what resources and when

• Scalability: Easy to onboard new users by assigning appropriate roles

Key Features

SeqsLab RBAC implements several critical security principles:

1. Least Privilege: Users receive only the minimum permissions needed for their tasks

2. Organization Isolation: All data is strictly isolated by organization - users cannot access resources from other organizations

3. Ownership Tracking: Resources track who created them for fine-grained access control

4. Composable Roles: Roles can inherit from other roles to build complex permission structures

5. Service Integration: Consistent RBAC across all SeqsLab services (DRS, TRS, WES, Healthcare)

Architecture

Core Components

The SeqsLab RBAC system consists of three main components:

1. Users: Individual accounts associated with an organization

2. Roles: Named collections of permissions (e.g., “Data hub writer”, “Job executor”)

3. Permissions: Specific actions on resources (e.g., “view DRS object”, “execute workflow”)

User → Assigned Roles → Permissions → Access to Resources

Permission Model

Each resource in SeqsLab defines permissions for standard CRUD operations:

• add: Create new instances

• view: Read a single instance

• list: Query/list multiple instances

• change: Update an existing instance

• delete: Remove an instance

Some services define additional custom permissions:

• writeDs/readDs: Dataset content operations (DRS)

• versions/files: Tool version management (TRS)

• requests: Run request management (WES)

Permission Evaluation Flow

When a user attempts an action, SeqsLab evaluates permissions in this order:

┌─────────────────────┐
│  User Request       │
└──────────┬──────────┘
           │
           ▼
    ┌──────────────┐
    │Authenticated?│──NO──► 401 Unauthorized
    └──────┬───────┘
           │YES
           ▼
    ┌────────────────┐
    │Has Required    │──NO──► 403 Forbidden
    │Role?           │
    └──────┬─────────┘
           │YES
           ▼
    ┌────────────────┐
    │Same            │──NO──► 404 Not Found
    │Organization?   │
    └──────┬─────────┘
           │YES
           ▼
    ┌────────────────┐
    │Owns Resource?  │──NO──► 403 Forbidden
    │(if required)   │
    └──────┬─────────┘
           │YES
           ▼
    ┌────────────────┐
    │Custom Checks?  │──NO──► 403 Forbidden
    └──────┬─────────┘
           │YES
           ▼
      ┌─────────┐
      │ ALLOWED │
      └─────────┘

Role Hierarchy

Global Roles

These roles provide organization-wide or platform-wide access:

GlobalAdministrator

• Scope: Platform-wide

• Description: Complete control over the platform and all services

• Capabilities:

  • Manage all organizations

  • Configure platform settings

  • Access all resources across organizations

  • Manage runtime options and operator pipelines

Note

This role should be reserved for platform operators and system maintainers only.

OrganizationAdministrator

• Scope: Organization-wide

• Description: Manages all aspects of services within an organization

• Inherits From: UserAdministrator, JobAdministrator, DataAdministrator, ToolAdministrator, LabelAdministrator

• Capabilities:

  • Manage users and role assignments

  • Configure organization settings

  • Access all data, tools, and jobs within organization

• Limitations: Cannot manage platform-level settings or other organizations

UserAdministrator

• Scope: Organization users

• Description: Manages user accounts and role assignments

• Capabilities:

  • Create and deactivate user accounts

  • Assign roles to users

  • Create custom roles

  • View user activity

Service-Specific Roles

SeqsLab implements specialized roles for each service. Below is a summary; detailed information is available in service-specific sections.

Data Repository Service (DRS)

Manages genomic data objects and datasets:

Role	Access Level	Description
DataHubViewer	Read-only	View DRS object metadata
DataHubWriter	Read-write	Create and manage own DRS objects
DataHubAdministrator	Admin	Manage all DRS objects in organization
DatasetViewer	Read-only	Download dataset files
DatasetWriter	Read-write	Upload dataset files
DatasetAdministrator	Admin	Manage all datasets
DataAdministrator	Full admin	Complete control over data hub and datasets

Tool Registry Service (TRS)

Manages workflow tools and containers:

Role	Access Level	Description
ToolRegistryViewer	Read-only	Browse available tools
ToolRegistryWriter	Read-write	Register new tools
ToolRegistryAdministrator	Admin	Manage all tools
ToolUser	Read-only	View and download tools for workflows
ToolSupporter	Read-write	Manage tool files
ToolVersionDeveloper	Read-write	Create and manage tool versions
ToolAdministrator	Full admin	Complete tool management

Workflow Execution Service (WES)

Executes and manages workflow runs:

Role	Access Level	Description
JobViewer	Read-only	View workflow runs and logs
JobExecutor	Read-write	Submit and manage own workflow runs
JobAdministrator	Admin	Manage all workflow runs in organization

Note

JobExecutor automatically inherits DataHubWriter and ToolUser permissions to facilitate workflow execution.

Healthcare Service

Manages clinical and genomic patient data:

Role	Workflow Stage	Description
ReporterDataEntryOperator	Data Entry	Enter patient and sample data
LaboratorySupervisor	Quality Control	Review and approve samples
BioinformaticsScientist	Analysis	Analyze variants and create interpretations
MedicalTechnologist	Data Management	Manage laboratory data uploads
MedicalDirector	Final Review	Sign off on clinical reports

Important

Healthcare roles are state-based: permissions depend on the biosample’s current workflow state (PENDING → REVIEW → ANALYSIS → COMPLETE).

Label Service

Manages resource organization tags:

Role	Access Level	Description
LabelWriter	Read-write	Create and edit labels for organizing resources
LabelAdministrator	Admin	Manage all labels in organization

User Guide: Choosing the Right Roles

Common Use Cases

Use this table to identify which roles you need based on your tasks:

I want to…	Required Role(s)	Notes
Data Management
View data object metadata	DataHubViewer	Read-only access
Download data files	DatasetViewer	Requires DataHubViewer for metadata
Upload new data	DataHubWriter + DatasetWriter	Both metadata and file permissions needed
Manage all organization data	DataAdministrator	Full administrative access
Tool Management
Browse available tools	ToolRegistryViewer	Read-only
Use tools in workflows	ToolUser	Required for job execution
Register new tools	ToolRegistryWriter
Develop tool versions	ToolVersionDeveloper
Manage all tools	ToolAdministrator
Workflow Execution
View workflow status	JobViewer	Monitor runs
Run workflows	JobExecutor	Includes data and tool access
Manage all runs	JobAdministrator	Cancel/modify any run
Clinical Workflows
Enter patient data	ReporterDataEntryOperator	Initial data entry
Review samples	LaboratorySupervisor	Quality control
Analyze genomic data	BioinformaticsScientist	Variant interpretation
Sign clinical reports	MedicalDirector	Final approval
Administration
Manage users	UserAdministrator	Create users, assign roles
Manage organization	OrganizationAdministrator	Full organization control

Common User Personas

Instead of assigning individual roles, consider these typical job profiles:

🧬 Bioinformatics Scientist

Runs analysis pipelines and interprets genomic data

Recommended Roles:

• JobExecutor (includes DataHubWriter and ToolUser)

• BioinformaticsScientist (for clinical interpretation)

• ToolVersionDeveloper (if developing custom pipelines)

Can:

• Upload reference genomes and sample data

• Submit and monitor workflow runs

• Access analysis results

• Create variant interpretations

• Develop custom analysis tools

🧪 Lab Technician

Manages sample intake and data entry

Recommended Roles:

• ReporterDataEntryOperator (patient data entry)

• MedicalTechnologist (includes DataAdministrator)

Can:

• Enter patient and biosample information

• Upload sequencing data files

• Manage laboratory data repository

• Track sample status

📋 Lab Manager/Supervisor

Oversees quality control and team operations

Recommended Roles:

• LaboratorySupervisor (QC and approval)

• OrganizationAdministrator (team management)

Can:

• Review and approve biosamples

• Monitor workflow execution

• Manage user accounts and roles

• Configure organization settings

• Audit access and activity

🩺 Medical Director

Provides clinical oversight and report sign-off

Recommended Roles:

• MedicalDirector (clinical sign-off)

• JobViewer (optional, for monitoring)

Can:

• Review variant interpretations

• Sign clinical reports

• View analysis status

• Access patient phenotype data

📊 Data Scientist

Analyzes genomic data without clinical reporting

Recommended Roles:

• JobExecutor (includes DataHubWriter and ToolUser)

• DatasetViewer (access to datasets)

Can:

• Run analysis workflows

• Access and download datasets

• Create and manage data objects

• View workflow results

How Permissions Work

Organization Isolation

Every user and resource belongs to an organization (identified by Organization ID). This creates strict boundaries:

• Users can only access resources within their organization

• Cross-organization access is never allowed

• Resources from other organizations appear as “not found” (404)

Important

Organization isolation is enforced at every layer of the system and cannot be bypassed except by GlobalAdministrator.

Ownership-Based Access

For certain operations, resource ownership determines access:

• Writer roles (e.g., DataHubWriter, ToolRegistryWriter) can modify their own resources

• Administrator roles can modify all resources in the organization

• Ownership is determined by the user who created the resource

Example:

• Alice (DataHubWriter) creates genome_sample_1.vcf → Alice can modify and delete it

• Bob (DataHubWriter) cannot modify Alice’s file

• Carol (DataHubAdministrator) can modify both Alice’s and Bob’s files

State-Based Permissions (Healthcare)

Healthcare resources use workflow states to control access:

┌─────────┐    ┌────────┐    ┌──────────┐    ┌──────────┐
│ PENDING │───►│ REVIEW │───►│ ANALYSIS │───►│ COMPLETE │
└─────────┘    └────────┘    └──────────┘    └──────────┘
     │             │               │               │
     └─────────────┴───────────────┴───────────────┘
   ReporterData   Laboratory   Bioinformatics   Medical
   EntryOperator  Supervisor   Scientist        Director

Each role can only modify biosamples in specific states:

• PENDING: ReporterDataEntryOperator enters patient data

• REVIEW: LaboratorySupervisor performs quality control

• ANALYSIS: BioinformaticsScientist analyzes variants

• COMPLETE: MedicalDirector signs final report

Role Composition

Roles can inherit permissions from other roles:

JobExecutor inherits from:
  ├─ LabelWriter (manage resource labels)
  ├─ DataHubWriter (manage DRS objects)
  └─ ToolUser (view and use tools)

This means a user with JobExecutor automatically has all permissions from LabelWriter, DataHubWriter, and ToolUser.

Cross-Service Workflows

Typical Genomic Analysis Pipeline

A complete genomic analysis involves multiple services and roles:

1. Data Upload (DRS)

• Role: DataHubWriter, DatasetWriter

• Action: Upload reference genomes and sample data

• Result: DRS objects created and registered

2. Tool Registration (TRS)

• Role: ToolRegistryWriter, ToolVersionDeveloper

• Action: Register analysis workflows and tools

• Result: Tools available in registry

3. Job Execution (WES)

• Role: JobExecutor

• Action: Submit workflow with DRS inputs and TRS tools

• Result: Analysis runs with monitored progress

4. Result Management (DRS)

• Role: DataHubWriter, DatasetWriter

• Action: Store analysis outputs as DRS objects

• Result: Results accessible for downstream analysis

5. Clinical Reporting (Healthcare) (if applicable)

• Role: BioinformaticsScientist, MedicalDirector

• Action: Create interpretations and sign reports

• Result: Clinical-grade report generated

Required Role Combinations

Common role combinations for different workflows:

Basic Genomic Analysis:

• DataHubViewer + DatasetViewer + JobViewer (read-only access)

Research Analysis:

• DataHubWriter + DatasetWriter + JobExecutor + ToolUser

Clinical Laboratory Workflow:

• ReporterDataEntryOperator + LaboratorySupervisor + BioinformaticsScientist + MedicalDirector

Platform Administration:

• OrganizationAdministrator (includes all sub-administrator roles)

Best Practices

For Administrators

1. Apply Least Privilege: Assign the minimum roles necessary for each user’s job function

2. Regular Audits: Review user roles quarterly and remove unnecessary permissions

3. Use Personas: Assign role bundles based on job titles rather than individual permissions

4. Document Exceptions: If granting elevated privileges, document the business justification

5. Monitor Access: Review access logs regularly for unusual patterns

6. Onboarding Process: Create standard role assignments for common job functions

7. Offboarding Process: Immediately revoke access when users leave the organization

For Users

1. Request Appropriate Roles: Understand your job function and request matching roles from your administrator

2. Report Access Issues: If you encounter permission errors, contact your UserAdministrator

3. Never Share Credentials: Each user must have their own account for audit purposes

4. Respect Data Boundaries: Do not attempt to access resources outside your organization

5. Follow Workflows: For healthcare, respect biosample state transitions

6. Review Permissions: Periodically verify you have the roles you need

Security Considerations

Data Protection

• ✅ All data encrypted at rest and in transit

• ✅ Comprehensive audit logging for compliance

• ✅ Automatic session timeout after inactivity

• ✅ Strong password policies enforced

• ✅ Multi-factor authentication available

Compliance

• HIPAA: Healthcare module implements HIPAA-compliant access controls for protected health information

• GDPR: Data deletion and export capabilities for user privacy rights

• SOC 2: Audit logging and access controls for security compliance

• CLIA/CAP: Clinical laboratory workflow enforcement for diagnostic testing

Threat Mitigation

Threat Mitigation

• Injection Attacks: Protection against SQL injection and command injection

• Cross-Site Request Forgery (CSRF): Standard protection enabled for all forms

• Cross-Site Scripting (XSS): Content sanitization and security policies

• Privilege Escalation: Role checks enforced at every layer

• Data Leakage: Organization isolation strictly enforced

Troubleshooting

Common Issues

“Permission Denied” Errors

Symptom: 403 Forbidden when attempting an action

Possible Causes:

1. Missing required role

2. Resource belongs to another user (ownership required)

3. Resource in wrong state (healthcare workflows)

4. Organization mismatch

Solutions:

1. Check your assigned roles with your administrator

2. Verify you own the resource or have administrator role

3. Verify biosample workflow state

4. Confirm resource belongs to your organization

“Resource Not Found” Errors

Symptom: 404 Not Found when accessing a resource you know exists

Possible Causes:

1. Resource belongs to different organization

2. Missing view/list permission

3. Resource has been deleted

Solutions:

1. Verify organization ID matches your account

2. Request appropriate viewer role

3. Contact resource owner or administrator

Cannot Modify Resources

Symptom: Can view resources but not edit them

Possible Causes:

1. Have viewer role but not writer role

2. Resource owned by another user

3. Healthcare biosample in wrong state

Solutions:

1. Request writer or administrator role

2. Ask resource owner to transfer ownership or request administrator role

3. Wait for biosample to reach appropriate state

Getting Help

Step 1: Check this documentation

• Review relevant sections above

• Check the “Common Use Cases” table

• Verify your assigned roles

Step 2: Contact your administrator

• UserAdministrator can review and modify your roles

• OrganizationAdministrator can resolve organization-level issues

Step 3: Submit a support ticket

• For platform issues: support@seqslab.net

• Include: username, organization, action attempted, error message

Role Assignment Guide

For Administrators: How to Assign Roles

1. Log in with UserAdministrator or higher privileges

2. Navigate to User Management section

3. Select the user to modify

4. Locate Roles configuration

5. Select roles from:

   • Pre-defined personas (recommended)

   • Individual roles (for custom needs)

6. Save changes

7. Notify user - they may need to log out and back in

Tip

Roles are additive. A user with multiple roles has the combined permissions of all assigned roles.

Example Role Assignments

Example 1: Research Organization

Organization: GenomicsLab Inc.

User	Job Title	Assigned Roles	Rationale
Alice	Lab Manager	OrganizationAdministrator	Manages team and resources
Bob	Bioinformatician	DataHubWriter, ToolUser, JobExecutor	Runs analyses
Carol	Research Scientist	DataHubViewer, JobViewer	Views data and results

Example 2: Clinical Laboratory

Organization: MedGen Diagnostics

User	Job Title	Assigned Roles	Rationale
Dr. Smith	Laboratory Director	MedicalDirector, OrganizationAdministrator	Signs reports, manages org
Emily	Genetic Counselor	ReporterDataEntryOperator, MedicalTechnologist	Enters data, manages uploads
Frank	Lab Supervisor	LaboratorySupervisor	QC and sample approval
Grace	Bioinformatics Scientist	BioinformaticsScientist, JobExecutor	Analyzes variants

Summary

SeqsLab RBAC provides:

✅ Comprehensive Security: Fine-grained access control across all services
✅ Organization Isolation: Strict boundaries between organizations
✅ Flexible Roles: Composable roles that match real-world job functions
✅ Compliance Ready: Meets HIPAA, GDPR, CLIA/CAP requirements
✅ Ease of Management: Persona-based role assignment for common use cases
✅ Audit Trail: Complete logging for security and compliance

Quick Start Checklist

For Administrators setting up RBAC:

• [ ] Identify job functions in your organization

• [ ] Map job functions to role personas

• [ ] Create user accounts with appropriate roles

• [ ] Document any custom role assignments

• [ ] Schedule quarterly role audits

For Users working with RBAC:

• [ ] Understand your assigned roles

• [ ] Know who your UserAdministrator is

• [ ] Request additional roles if needed

• [ ] Report permission issues promptly

• [ ] Follow security best practices

Further Reading

For detailed technical information:

• GA4GH Standards: ga4gh.org

• HL7 FHIR: hl7.org/fhir