How services authenticate to each other

The platform is four services: the workbench you sign in to, the record store, the analysis service and BioStor. Only the workbench knows who you are; the other three know callers by key. Two kinds of credential move between them: a user API key, which identifies one account and carries its access, and a service key, which identifies one service to another. Access is decided where the data lives: the record store decides what you may read and write among records, BioStor decides for files and the analysis service decides for jobs. Use this page to explain why two people see different records, or what a service may do on your behalf.

Sessions in the workbench

Signing in creates a session on the server, referenced by a cookie in your browser. Every workbench page and API route requires it: a page opened without one redirects to the login page and returns you afterwards; an API route answers with a 401 instead. Signing out ends the session.

Each account has its own API key, held by the workbench. When the workbench needs records it forwards the signed-in user's key to the record store, so the record store applies that user's access and two people opening the same project can receive different records. Jobs are submitted to the analysis service the same way, which is why your analysis queue lists only your own jobs.

User API keys and what they carry

A user key resolves, in the record store, to the account and its user group. A missing, unknown or expired key is refused. An account in the Super User group sees every project and dataset, skips record filtering, and alone may curate the taxonomy and geography reference tables or run the system self-check. Every other account's access comes entirely from membership, described next. Keys expire; an expired key is refused rather than renewed.

Where access decisions are made

Record reads are filtered in the record store. For a non-superuser key, the readable set is the union of the projects the account belongs to, the datasets it belongs to, the projects and datasets the platform designates as public, and every project or dataset with status remote. Every list of records, however requested, is reduced to that set record by record: a record in the public registry passes outright; otherwise it passes only if one of its project or dataset codes is in the caller's readable set. This covers record retrieval, set reads, set statistics, aggregates, maps and search. Access is per record, not per marker. The workbench's sharing and access levels are how membership is granted; the record store is where it is enforced.

Record writes are checked in the record store too. The specimen and sequence loaders run with the submitting user's key and require a level that allows editing specimens on every target recordset (Project Manager, Edit All or Edit Specimens/Read Sequences on a project; Dataset Manager on a dataset). For an existing record, at least one of its current recordsets must pass. Super Users pass. See From upload to loaded record.

Jobs are owned by the submitting key. The analysis service accepts a user key or the platform's system token. A user key can submit, list and cancel its own jobs; the system token, used by the admin dashboard, sees and acts on all jobs. When the analysis service packages a job it fetches the records from the record store with the submitter's key, so a job contains only records the submitter could read at that moment. The workbench checks that you own a job before serving its report or result archive.

Files are decided in BioStor. BioStor keys carry one of four levels: public (0), manager (1), system (5) and admin (9). A key must be active, unexpired and at least manager level to write. A public object opens with any key or none; a private object opens for its owner or for a system or admin key; listings are filtered to what the key may read; there are no per-object grants. See The BioStor access model.

Service keys

Because the workbench uses its own key for BioStor, files are stored under the workbench's account and presented to you by the workbench. Your browser never receives a BioStor key: a file is served through a workbench proxy link bound to your session and signed, and BioStor answers with a time-limited signed link to the stored object.

Good to know

• The record store, not the workbench, is the authority on which records you may read or write. A workbench page can be opened by any signed-in user, but the records on it are always filtered to your access.
• Membership is granted per project or dataset and applied per record. A record in two projects is readable if you belong to either.
• Super User is a property of the account, not something granted per project.

Related

• Platform architecture and data flow
• The BioStor access model
• Sharing and access levels
• Access levels