PCGL File Manager

The PCGL File Manager is a fork of Overture Song with extensions to accomodate the unique authorization system and data model used in the Pan-Canadian Genome Library.

Song functions as a file catalog system, tracking files and managing their metadata. To manage file transfers to and from object storage Song interacts with its required companion application, Score.

Song is part of Overture, a collection of open-source software microservices used to create platforms for researchers to organize and share genomics data.

PCGL Code Extensions

AuthZ Integration

The Keycloak-based OAuth2 security is replaces with a PCGL AuthZ service. This is activated via the pcglauthz Spring profile.

Key added files (all in song-server/src/main/java/bio/overture/song/server/security/authz/):

• AuthZAuthenticationFilter: Servlet filter that intercepts requests and authenticates via either a user Bearer token or service-to-service token (X-Service-Token / X-Service-Id headers)
• AuthZRestClient: HTTP client that calls the external PCGL AuthZ service to validate tokens and retrieve user claims
• AuthZAuthorizationService: Determines permissions from AuthZUserClaims (admin check, study read/edit access)
• AuthZUserClaims: User identity model with editable_studies, readable_studies, and data_admin flag
• PCGLAuthZConfig: Config class bound to auth.server.authz.* properties (host, serviceId, serviceUUID)

Authorization model: Instead of Keycloak OAuth2 scopes, PCGL uses study-level lists (editable_studies, readable_studies) fetched from the AuthZ service. A data_admin flag grants full access.

Service-to-service auth: Services authenticate using X-Service-Token and X-Service-Id headers (rather than Bearer tokens), verified against the AuthZ service.

Configuration (in application.yml, pcglauthz profile):

auth:
  server:
    provider: pcglauthz
    authz:
      host: https://authz.example.com
      service-id: SERVICE-LABEL
      service-uuid: 00000000-0000-0000-0000-000000000000

Documentation

Technical resources for those working with or contributing to the project live in the /docs folder of this repository, and are also published, fully rendered, on our official documentation site.

• Song Overview
• Setting up the Development Environment
• Reference Docs

Development Environment

• Java 11 (OpenJDK)
• Maven 3.5+ (or use provided wrapper)
• VS Code or preferred Java IDE
• Docker Container platform

Support & Contributions

• For support, feature requests, and bug reports, please see our Support Guide.

• For detailed information on how to contribute to this project, please see our Contributing Guide.

Related Software

The Overture Platform includes the following Overture Components:

Software	Description
Score	Transfer data to and from any cloud-based storage system
Song	Catalog and manage metadata associated to file data spread across cloud storage systems
Maestro	Organizing your distributed data into a centralized Elasticsearch index
Arranger	A search API with reusable search UI components
Stage	A React-based web portal scaffolding
Lyric	A model-agnostic, tabular data submission system
Lectern	Schema Manager, designed to validate, store, and manage collections of data dictionaries.

Funding Acknowledgement

Overture is supported by grant #U24CA253529 from the National Cancer Institute at the US National Institutes of Health, and additional funding from Genome Canada, the Canada Foundation for Innovation, the Canadian Institutes of Health Research, Canarie, and the Ontario Institute for Cancer Research.

Powered by