Article about Access Control and Data Governance overview

docs/access-control/authorisation.md

@@ -0,0 +1,29 @@
+# Authorisation via an Access Token
+
+## Overview
+
+* To access ODM APIs, users must provide an authorization token.
+* The token defines which data can be retrieved and which operations are permitted (e.g.,
+view-only vs. edit).
+
+## Genestack API Token
+
+* Personal access tokens provide permanent API access to a user’s data.
+* Features:
+    * A user can create multiple tokens.
+    * Tokens can be revoked at any time.
+    * Tokens are requested in the user profile or by clicking “Generate API Token” on
+    the starting page.
+* Use the header: `Genestack-Api-Token`.
+
+## Identity Provider Access Token
+
+* ODM also supports access tokens from an identity provider (e.g., Azure AD).
+* Use the header: `Authorization`.
+* Additional configuration is required to enable identity provider token usage.
+
+## Important Notes
+
+* If both tokens are provided, the identity provider access token takes precedence.
+* For security and consistency, enterprise deployments should prefer identity provider
+tokens where possible.

docs/access-control/governance.md

@@ -0,0 +1,40 @@
+# Data Governance
+
+The Open Data Manager (ODM) platform indexes both data and metadata to support efficient
+search and exploration.
+
+## Metadata
+
+* A structured representation of metadata is stored in ODM’s internal MySQL database.
+* This acts as a partial copy of metadata, ensuring fast performance for:
+
+    * Search
+    * Filtering
+    * Data exploration
+
+## Raw Data
+
+* Raw files (e.g., images, BAM files) are not copied into ODM.
+Instead, ODM stores pointers to the files in their existing storage locations.
+
+## Processed and Indexed Data
+
+* Processed data is stored in a columnar database, enabling it to be indexed and
+searchable within ODM.
+
+## Attachments
+
+* When data files are imported via the GUI or attached to a study (e.g., supplementary
+documents), they must be uploaded into the platform’s S3 bucket.
+* This creates a copy of the file in ODM, ensuring accessibility through the user interface.
+
+## Current Limitation
+
+* ODM currently supports a single S3 bucket for attachments.
+
+| Type          | Example                                                                                                       | Details                                                                                          | Copy                                                  | Configurability                                                |
+|---------------|---------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|-------------------------------------------------------|----------------------------------------------------------------|
+| Attachments   | .pdf, .ppt, .h5 – can be anything                                                                             | ODM indexes basic file metadata (name, date, type, file contents for archives like .zip and .h5) | Copy is always stored in ODM. We use ODM’s S3 bucket. | Can configure to use the customer’s S3 bucket.                 |
+| Metadata      | E.g. .tsv metadata files (e.g. <https://s3.amazonaws.com/bio-test-data/odm/Test_1000g/Test_1000g.samples.tsv>). | ODM captures and indexes study, sample, library/prep and other metadata.                         | Copy is always stored in ODM’s databases.             | No region separation made, use permissions to control access.  |
+| Raw Data      | E.g. .fastq, .bam., images, and so on – if it’s not an attachment and not indexed data.                       | ODM stores and indexes the pointer to the file and nothing else.                                 | No copy is made anywhere.                             |                                                                |
+| Indexed Data  | E.g., tabular data, VCFs, etc.                                                                                | ODM indexes most of the data by storing a compressed partial copy of the data columns.           | Copy is made.                                         | No configurability.                                            |

docs/access-control/groups.md

@@ -0,0 +1,57 @@
+# Groups
+
+## Purpose of Groups
+
+* Groups are used in ODM to simplify collaboration and data sharing.
+* Groups can represent locations, departments, or project teams, ensuring data is shared only with the relevant people.
+* Users see only the groups they are members of, unless they hold the **Manage groups** permission.
+
+Suggested groups structure:
+
+![Group Structure](groups-structure.png)
+
+The list of all groups you are a member of can be browsed on the Groups page. A user with
+Manage groups permission can browse and manage all groups available in the system.
+
+## Creating Groups
+
+* Groups can be created in two ways:
+    * **Manually** in the ODM graphical user interface.
+    * **Automatically** via the SCIM API for integration with identity providers.
+
+* Prerequisites: None. Any user can create a group and invite other members.
+
+## Default Groups
+
+Upon installation, ODM creates two default groups (these should not be removed):
+
+* **All users**: all users are automatically added to this group.
+* **Curator**: a special group that grants edit permissions to members.
+
+## Group Roles
+
+* **Group members**: can access all data shared with their group and can share data
+with the group.
+* **Group admins**: can add or remove members and assign roles within their group.
+Admin rights do not extend to other groups.
+* **Special permission**: a user with **Manage groups** can manage all groups in the
+system, even if they are not a member.
+
+Once a user is added to a group, they immediately have access to all studies shared with the
+group. Removing a user from a group will revoke their access to all studies shared with the group.
+
+### Curator Group
+
+* Membership in the **Curator group** grants edit permissions.
+* Curators can import new studies, edit metadata, and track changes through version
+history.
+* Non-curators are considered **researchers**: they can browse and download but cannot
+contribute.
+
+If a user is not a member of the Curator they are considered as researchers and are able just to
+browse available studies and retrieve data, but not contribute to it.
+
+| Role       | Member of Curator group? | Role                                              |
+|------------|--------------------------|---------------------------------------------------|
+| Researcher | No                       | Browse, Search, Download                          |
+| Curator    | Yes                      | All of the above + **Import Data, Edit Metadata** |

docs/access-control/permissions.md

@@ -0,0 +1,17 @@
+# Permissions
+
+## Overview
+
+* Once a user is created, permissions can be assigned in the **Users and Permissions** section.
+* To grant or revoke permissions, a user must have the **Manage organization** permission.
+* The system superuser account `root@genestack.com` is created by default with full management rights.
+
+## Permission Types
+
+| Permission          | Actions                                                                                                               | Recommendation                                                                              |
+|---------------------|-----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
+| Manage organization | - Manage permissions <br/> - Manage study ownership <br/> - Create and deactivate users <br/> - Change user passwords | This is a **powerful system-level permission**. Grant only to a few trusted administrators. |
+| Set up templates    | - Create new templates <br/> - Alter existing templates                                                               | Changes affect **all users**. Should be assigned only to responsible **Data Owners**.       |
+| Configure facets    | Set desired list and order of facets in the Study Browser                                                             | Changes affect **all users**. Should be assigned only to responsible **Data Owners**.       |
+| Manage groups       | Access and manage all groups, even without admin/membership rights                                                    | Use primarily for integration purposes.                                                     |
+| Access all data     | Access to all studies in the system, even if not shared                                                               | Use only for integration or administrative purposes.                                        |

docs/access-control/scim.md

@@ -0,0 +1,31 @@
+# Access Management via SCIM APIs
+
+## Overview
+
+* ODM provides RESTful APIs for user and group management, based on the SCIM 2.0
+provisioning standard.
+* These APIs allow seamless integration with identity providers (such as Active Directory),
+enabling automated and synchronized access management.
+
+## Benefits
+
+* Establishes one central entry point for access control, reducing duplication and errors.
+Ensures reliable and efficient user lifecycle management across the organisation.
+* Recommended for all customers whose identity providers support SCIM 2.0.
+
+## Workflow with Active Directory
+
+* ODM’s SCIM endpoints allow Active Directory (AD) to be the authoritative system for user
+management.
+* Administrators manage users in AD, where they can:
+    * Create users and groups.
+    * Add or remove users from groups.
+    * Deactivate users.
+* Changes are automatically propagated to ODM on a scheduled sync configured in AD.
+
+## Flexibility
+
+* In addition to AD-provisioned groups, ODM also supports locally created groups for project-specific sharing needs.
+* Example: a temporary project group can be created in ODM and used to share studies with a restricted set of users.
+
+For more detail, see [Enterprise applications SCIM provisioning](https://genestack.github.io/admin-docs/latest/home/single-sign-on/scim/azure/#configure-user-and-group-provisioning).

docs/access-control/security.md

@@ -0,0 +1,21 @@
+# ODM Platform Security
+
+Genestack operates an ISO27001:2022 certified Information Security Management System
+(ISMS), with operational security controls in place which are strictly adhered to, in order to
+underpin the development of Genestack products, how Genestack delivers its services to its clients, and
+how Genestack operates and protects the Genestack production environment in support of its clients.
+
+The key documents and frameworks in-place to support Genestacks ISO27001:2022 ISMS are as
+follows:
+
+| **Document Name**                                  | **Purpose**                                                                                                                                                                                                                                                                                   | **Owner**               | **Last Updated** |
+|----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|------------------|
+| ISO27001 Certificate                               | Validates Genestack’s ISMS and information security compliance.                                                                                                                                                                                                                               | Chief Executive Officer | 16 July 2025     |
+| ODM High Level Design                              | ODM platform high level design document, covering all aspects of design including security management.                                                                                                                                                                                        | Head of Engineering     | 13 October 2025  |
+| ODM Security Requirements                          | Describes the detailed security control requirements applied to the ODM platform.                                                                                                                                                                                                             | Head of Engineering     | 14 October 2025  |
+| Information Security Policy                        | Defines Genestack’s high level security objectives.                                                                                                                                                                                                                                           | Chief Executive Officer | 12 May 2025      |
+| Operational Security Policy                        | Defines the policy for the operational security controls that underpin the development of Genestack products, how Genestack delivers its services to its clients, and how Genestack operates and protects the Genestack production environment in support of its clients.                     | Head of Engineering     | 13 October 2025  |
+| Cloud Service Provider Policy                      | Defines cloud-specific control requirements aligned with ISO/IEC 27017:2025 (‘ISO27017’), supporting secure service delivery and data protection.                                                                                                                                             | Head of Engineering     | 14 October 2025  |
+| Terms of Reference for the Security Working Group  | Defines how all aspects of Genestack’s ISO27001 Information Security Management System are managed, governed and audited on a perpetual basis.                                                                                                                                                | Head of Engineering     | 6 May 2025       |
+| Software Development Life Cycle Policy             | Establishes a policy for a Software Development Lifecycle (SDLC) framework and related software application development methodologies and tools that are essential components in the management, development and delivery of software applications to support Genestack needs and services.   | Head of Engineering     | 6 May 2025       |
+| Access Control Policy                              | Addresses the security requirements for all user login accounts on Genestack information assets by Genestack staff.                                                                                                                                                                           | Head of Engineering     | 3 February 2025  |

docs/access-control/sharing.md

@@ -0,0 +1,25 @@
+# Data Sharing
+
+## Study Ownership
+
+* By default, the study owner is the user who imports the study into ODM.
+* Owners have full control over sharing and access management for their studies.
+
+## Sharing a Study
+
+* Owners can share studies only with groups they are members of.
+* Once shared with a group, the study becomes available to all members of that group.
+* A study can be shared with multiple groups.
+* The list of groups that have access to a study is visible in the “More Info” section.
+
+## Revoking Access
+
+* Study owners can revoke access to a study at any time.
+
+## Transferring Ownership
+
+* If a study owner becomes unavailable, administrators can assign a new owner.
+* Ownership transfers are:
+    * Permission-aware (only permitted roles can transfer).
+    * Fully auditable (tracked in the system).
+* The current owner may also initiate a transfer voluntarily.

docs/access-control/users.md

@@ -0,0 +1,37 @@
+# Users
+
+## Creation
+
+* With **Single Sign-On (SSO)** configured, new users are created automatically upon their first login.
+* Detailed instructions for identity provider integration are available in the
+[Open Data Manager Administrator Documentation](https://genestack.github.io/admin-docs/latest/home/single-sign-on/sso/).
+
+## Default Access
+
+Newly created users have **immediate access** to studies shared with everyone in the organisation.
+
+## Group Membership
+
+To gain additional rights, users must be added to groups:
+
+* **View group-specific studies** (beyond those shared with all users).
+* **Contribute to data** (import new data or curate existing data).
+
+## Lifecycle Management
+
+* Once created, a user **cannot be deleted** from the system.
+* Users can, however, be **deactivated** to remove their access.
+
+## Technical Users
+
+* On a fresh **installation** of ODM, a small number of **technical user accounts** are created automatically.
+* These accounts support **integration, automated testing, and system configuration**.
+They are not intended for day-to-day user activity.
+* Passwords for technical users can be changed at any time for security reasons.
+
+| User                           | State        | Role                                               |
+|--------------------------------|--------------|----------------------------------------------------|
+| <root@genestack.com>           | Active       | Superadmin                                         |
+| <public@genestack.com>         | Active       | Loading public data, ontologies, setting templates |
+| <tester_curator@genestack.com> | Deactivated  | Automated testing upon installation                |
+| <tester_user@genestack.com>    | Deactivated  | Automated testing upon installation                |

mkdocs.yml

@@ -19,6 +19,15 @@ nav:
       - Guides:
             - Advanced User Guide:
                 - user-guide/index.md
+            - Access Control:
+                - Users: access-control/users.md
+                - Permissions: access-control/permissions.md
+                - Groups: access-control/groups.md
+                - Access Management via SCIM APIs: access-control/scim.md
+                - Data Sharing: access-control/sharing.md
+                - Authorisation via an Access Token: access-control/authorisation.md
+                - Data Governance: access-control/governance.md
+                - Platform Security: access-control/security.md
       - About Genestack: https://genestack.com/
     - Advanced Guide:
         - user-guide/index.md
@@ -39,7 +48,15 @@ nav:
         - Getting a Genestack API token: user-guide/doc-odm-user-guide/getting-a-genestack-api-token.md
         - Getting Access Token (Azure): user-guide/doc-odm-user-guide/getting-access-token-azure.md
         - Supported File Formats: user-guide/doc-odm-user-guide/supported-formats.md
-
+    - Access Control:
+        - Users: access-control/users.md
+        - Permissions: access-control/permissions.md
+        - Groups: access-control/groups.md
+        - Access Management via SCIM APIs: access-control/scim.md
+        - Data Sharing: access-control/sharing.md
+        - Authorisation via an Access Token: access-control/authorisation.md
+        - Data Governance: access-control/governance.md
+        - Platform Security: access-control/security.md
     - Tools:
         - odm-sdk:
             - Installation: tools/odm-sdk/installation.md