Technical Overview
The Broad Clinical Labs (BCL) ordering application can be used for order creation, sample intake, order tracking, and results delivery of BCL product offerings. The application allows for users to order Clinical Whole Genome Sequencing (cWGS), Clinical Blended Genome/Exome (cBGE), and other tests via the UI or API. Additional tests will be added over time.
The ordering portal is a highly-available, cloud-based application. It secures data throughout the ordering process both at rest and in transit.
API Documentation
Production: https://gpo.broadinstitute.org/redoc
Staging: https://gpo-staging.broadinstitute.org/redoc
BCL Cloud Architecture
Authentication and Authorization
Authentication
The BCL API only supports authentication through service accounts. With the exception of documentation endpoints, all incoming connections must have a valid JWT token, signed with the private key of a service account which the BCL API recognizes.
We request that our customers and partners create and manage their own service accounts, including key rotation lifecycles. BCL can integrate with any Google-provided service account.
Authorization
Once an incoming access token has been verified and its user identifier extracted, the BCL API will consult its own database to determine which resources, if any, the user is authorized to access.
Each user (service account) is associated with one or more roles. Each role is associated with one or more scopes, which provide fine-grained access to specific resources within the BCL API. Access to database records, such as orders and samples containing PHI information, is controlled by project-based scopes.
Service Account Roles
Service account roles include the following project-specific privileges:
- Create, Edit, View Orders in a Project
- Access Results in a Project
API Security
BCL API
All incoming requests to the BCL API in our deployed cloud environments first pass through Google’s Cloud Armor for security checks, then through our API which defines the specific HTTP verbs and call signatures to allow, and enforces each request is authenticated.
For each incoming request, the BCL API implementation validates the incoming JWT token to ensure that:
- The signature is valid and matches a key in a configured JWKS URI
- The audience matches our deployed environment name
- The issuer matches a configured service account
- The issued and expiration times are within a valid range relative to the current time
- Any additional claims we’ve configured to uniquely identify the service account such as the subject and email address.
Any non-compliant request is blocked before it gets to the application code.
- An HTTP response code of 502 indicates that CloudArmor identified a potential threat.
- An HTTP response code of 401 or 403 indicates that the request was not properly authenticated or the service account or actor is not authorized to perform the action.
- Any other error response code comes from the application itself and will include accompanying information about the specific error.
Appendix: Customer Security Requirements
There are some security controls that BCL is unable to enforce without your help. Some of these controls are shared between BCL and the Customer while others are fully the Customer’s responsibility. These controls are called “Customer Responsibilities” and are described in detail here.