Authentication
JBrowse fetches data files directly, so a file behind authentication needs
JBrowse to present the credentials. Add an entry to the top-level
internetAccounts array with the domains its token applies to: a hostname, or
a URL prefix to scope it to part of a server. The first account whose domains
matches a URL wins, so order specific ones first. If you control the server
holding the data, read the next section before configuring any of this.
Serving JBrowse and its data behind one login
JBrowse has no server and no user accounts. It is static files running in a
browser, reading your data files over HTTP, so whatever serves the files decides
who sees a track. When you control that server, the simpler setup puts JBrowse
and its data files on one site behind the login the site already has. The
browser then sends the login with every data request by itself, so the config
needs no internetAccounts entry and holds no credentials.
Putting JBrowse Web behind a login has recipes for HTTP Basic auth,
institutional single sign-on, AWS Cognito, Google IAP and Firebase
Authentication.
Alternatives to a shared login
In rough order of simplicity:
- No server at all. JBrowse Desktop reads files off your own machine, so nothing is published.
- Expiring links. S3 presigned URLs or CloudFront signed cookies are simple to set up, but a link stops working when its signature expires, taking any saved session or share link with it.
internetAccounts(the rest of this page), for data you do not control: Dropbox, Google Drive, an OAuth-protected API, a portal that issues tokens. JBrowse only forwards a credential the user already has and grants no access on its own.
Data on a different origin than the app also needs
CORS, including
the auth header in Access-Control-Allow-Headers. For JBrowse to offer its HTTP
Basic prompt, the server's 401 response must itself carry those CORS headers,
send WWW-Authenticate: Basic, and list WWW-Authenticate in
Access-Control-Expose-Headers.
Internet accounts
An internet account is an entry in the top-level internetAccounts array that
specifies how to obtain a token and which URLs to attach it to. With this one in
place, opening a track served from data.mylab.org prompts for a username and
password once, then reuses them for the session; nothing on the track config
changes:
{
"internetAccounts": [
{
"type": "HTTPBasicInternetAccount",
"internetAccountId": "myLab",
"name": "My lab server",
"domains": ["data.mylab.org"]
}
]
}| Type | Use for |
|---|---|
| HTTPBasicInternetAccount | A server behind HTTP Basic auth (username + password) |
| OAuthInternetAccount | Any OAuth 2.0 provider, configured with your own endpoints |
| DropboxOAuthInternetAccount | Dropbox, with the endpoints pre-filled |
| GoogleDriveOAuthInternetAccount | Google Drive, with the endpoints pre-filled |
| ExternalTokenInternetAccount | A token the user pastes in, or that your portal hands over |
Every type shares the BaseInternetAccount slots:
internetAccountId, name, description, domains, and the
authHeader/tokenType pair naming the request header the token goes in. HTTP
Basic adds
validateWithHEAD,
a HEAD request that checks the credentials before using them.
How an account is matched to a URL
JBrowse picks an account for a file in two steps.
First, the location's own internetAccountId. A file location can name its
account outright, beside uri, which picks that account ahead of the domains
walk below when more than one account covers the URL. This is also what the Add
Track form's account picker writes:
Goes in the tracks array of config.json. See Tracks.
{
"type": "AlignmentsTrack",
"trackId": "private_bam",
"name": "Private alignments",
"assemblyNames": ["hg38"],
"adapter": {
"type": "BamAdapter",
"bamLocation": {
"uri": "https://data.mylab.org/x.bam",
"locationType": "UriLocation",
"internetAccountId": "myLab"
},
"index": {
"location": {
"uri": "https://data.mylab.org/x.bam.bai",
"locationType": "UriLocation",
"internetAccountId": "myLab"
}
}
}
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track-json '{
"type": "AlignmentsTrack",
"trackId": "private_bam",
"name": "Private alignments",
"assemblyNames": ["hg38"],
"adapter": {
"type": "BamAdapter",
"bamLocation": {
"uri": "https://data.mylab.org/x.bam",
"locationType": "UriLocation",
"internetAccountId": "myLab"
},
"index": {
"location": {
"uri": "https://data.mylab.org/x.bam.bai",
"locationType": "UriLocation",
"internetAccountId": "myLab"
}
}
}
}'In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track..., choose Add track from pasted JSON, and paste:
{
"type": "AlignmentsTrack",
"trackId": "private_bam",
"name": "Private alignments",
"assemblyNames": ["hg38"],
"adapter": {
"type": "BamAdapter",
"bamLocation": {
"uri": "https://data.mylab.org/x.bam",
"locationType": "UriLocation",
"internetAccountId": "myLab"
},
"index": {
"location": {
"uri": "https://data.mylab.org/x.bam.bai",
"locationType": "UriLocation",
"internetAccountId": "myLab"
}
}
}
}- The named account still has to be scoped for the URL. Naming chooses
between accounts; it does not widen the one it names. When the named account's
domainsdo not cover the URL, JBrowse logs which account and which URL to the console and falls back to thedomainswalk, so the file is read with whichever account covers it, or unauthenticated. - Files on the app's own origin are the exception. An account named on a
location that resolves to the origin serving JBrowse is used whatever its
domainssay, since a config written with relative paths ("uri": "data/x.bam") has no host to write there. A relative path resolves against the config file's own URL, so in a config loaded from another origin (?config=https://other.org/config.json) it resolves to that origin and this exception does not apply. A link cannot move a same-origin file anywhere but the server already serving the page. - An id the config does not declare is split at its first
-, and is honoured only when the part before it is an account type, no account'sdomainscover the file, and the file is one of two kinds. A file on the app's own origin takes such an id when the rest names no http(s) origin (HTTPBasicInternetAccount-myserveron a relative path). A file elsewhere takes only the id naming its own origin (HTTPBasicInternetAccount-https://data.mylab.org, the form JBrowse mints when a server answers 401), and that account then covers the whole origin: scheme, host and port. Any other undeclared id is ignored, and the file is read as if its location named no account.
Otherwise, the domains walk. JBrowse goes through internetAccounts in
order and picks the first whose domains matches, so put the most specific
accounts first. An entry is one of two shapes, told apart by whether it contains
a /:
-
A hostname,
data.mylab.orgorlocalhost:8080to pin a port, matches that host and its subdomains on a dot boundary:dropbox.comcoverswww.dropbox.combut notevil-dropbox.com. A leading dot (.mylab.org) means the same thing. -
A URL prefix,
data.mylab.org/readsorhttps://data.mylab.org/reads/, matches to a path-segment boundary, so/readsdoes not match/readsets. This scopes an account to a path, so one server can use different credentials for different directories:{ "internetAccounts": [ { "type": "HTTPBasicInternetAccount", "internetAccountId": "publicData", "name": "Public data", "domains": ["data.mylab.org/public"] }, { "type": "HTTPBasicInternetAccount", "internetAccountId": "privateData", "name": "Private data", "domains": ["data.mylab.org/private"] } ] }
The query string and the fragment are never consulted under either shape, so a
URL that merely mentions one of your domains in a parameter does not match. An
account with an empty domains list matches no URL by itself. It still applies
to a same-origin file whose location names it; for any other file, including one
the user assigns in the Add Track form, list the file's host in domains.
A domains entry names a whole host or a path, so domains: ["dropbox"] does
not match dropbox.com; write dropbox.com. Off the app's own origin, a
location's internetAccountId only chooses among accounts whose domains
already cover the URL, or names the origin account for that URL's own origin.
Both rules matter because jbrowse-web builds tracks from sessionTracks in the
URL, and a crafted link could otherwise aim a user's token at a server of its
choosing. An account that authenticates an off-origin file needs that file's
host in its domains.
OAuth
Dropbox and Google Drive have their endpoints built in and need only a
clientId registered with the provider. Any other provider uses the generic
OAuthInternetAccount with its endpoints supplied:
{
"internetAccounts": [
{
"type": "DropboxOAuthInternetAccount",
"internetAccountId": "dropboxOAuth",
"name": "Dropbox",
"clientId": "your-dropbox-client-id"
},
{
"type": "OAuthInternetAccount",
"internetAccountId": "myOAuth",
"name": "Institutional login",
"domains": ["data.myinstitution.org"],
"clientId": "your-client-id",
"authEndpoint": "https://auth.myinstitution.org/oauth/authorize",
"tokenEndpoint": "https://auth.myinstitution.org/oauth/token",
"needsPKCE": true
}
]
}JBrowse is a static app with nowhere to keep a client secret, so use the
authorization-code flow with
needsPKCE, the flow
designed for public clients, and register your JBrowse instance's URL as a
redirect URI with the provider. OAuthInternetAccount lists
scopes, responseType and the rest.
Google Drive and Dropbox file pickers
On the web, both accounts can add a button under the share-link box in the Add Track form that opens the provider's own file picker.
Google Drive shows Browse Google Drive once
apiKey and
appId are set.
With the picker, the account can ask for the drive.file scope, which reads
only the files a user picks. Google classes drive.file as non-sensitive, so
the app can be published without the review and security assessment Google
requires for the restricted drive.readonly scope. In exchange, a pasted share
link or a shared session opens a file only after that reader has picked it
themselves.
{
"internetAccounts": [
{
"type": "GoogleDriveOAuthInternetAccount",
"internetAccountId": "googleDriveOAuth",
"name": "Google Drive",
"clientId": "your-client-id.apps.googleusercontent.com",
"scopes": "https://www.googleapis.com/auth/drive.file",
"apiKey": "your-browser-api-key",
"appId": "your-cloud-project-number"
}
]
}In the Google Cloud project that owns the client:
- Enable the Google Picker API.
- Make the OAuth client a web application, and list as a redirect URI every page
address JBrowse is opened at, origin and path:
https://example.org/jb/andhttps://example.org/jb/index.htmlare two entries. - Create a browser API key restricted to your site and to the Picker API. Google designs a browser key to sit in page source, so it is the one key that belongs in config.json.
- On the consent screen, add the
drive.filescope and publish the app. While it is in testing, only listed test users can sign in, and their grants expire after seven days. appIdis the project number, the digits that start the client ID.
Google deletes an OAuth client that has gone six months without a sign-in, and emails the project owner 30 days before.
Dropbox shows Browse Dropbox once
chooser is on. It
opens the Dropbox Chooser with the account's clientId as its app key, and
works only for a site listed under "Chooser / Saver / Embedder domains" in the
Dropbox app console. For a file with no shared link, the Chooser makes one with
the user's default link settings.
JBrowse Desktop shows neither button. There, open the files from the folder the Google Drive or Dropbox desktop app keeps in sync.
External token
When a portal already holds a token, or the user can paste one in,
ExternalTokenInternetAccount asks
for the token and runs no auth flow. authHeader names the request header it
goes in, which also covers plain API-key headers:
{
"type": "ExternalTokenInternetAccount",
"internetAccountId": "externalToken",
"name": "Access token",
"domains": ["data.mylab.org"],
"authHeader": "X-Api-Key"
}Where tokens are stored
An access token is stored in the browser's sessionStorage, keyed by
internetAccountId, so closing the tab discards it. An OAuth refresh token is
kept in localStorage, so it outlives the tab and a new tab renews the access
token from it without a login window. Neither is written into a saved or shared
session: sharing a session shares the view, and the recipient is prompted for
credentials.
Private files in S3
An object in a private bucket has no credential JBrowse can send in a header, so none of the account types above reach it.
Presigned URLs
aws s3 presign turns a private object into a URL containing the signature,
which needs no internetAccounts entry. Sign the data file and its index
separately, since each is a separate object:
aws s3 presign s3://mybucket/sample.bam --expires-in 604800
aws s3 presign s3://mybucket/sample.bam.bai --expires-in 604800The signed data URL and the signed index URL go in the track, spelled out; the
uri shorthand cannot hold
them:
Goes in the tracks array of config.json. See Tracks.
{
"type": "AlignmentsTrack",
"trackId": "private_sample",
"name": "Sample from a private bucket",
"assemblyNames": ["hg38"],
"adapter": {
"type": "BamAdapter",
"bamLocation": {
"uri": "https://mybucket.s3.amazonaws.com/sample.bam?X-Amz-Algorithm=..."
},
"index": {
"location": {
"uri": "https://mybucket.s3.amazonaws.com/sample.bam.bai?X-Amz-Algorithm=..."
}
}
}
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track-json '{
"type": "AlignmentsTrack",
"trackId": "private_sample",
"name": "Sample from a private bucket",
"assemblyNames": ["hg38"],
"adapter": {
"type": "BamAdapter",
"bamLocation": {
"uri": "https://mybucket.s3.amazonaws.com/sample.bam?X-Amz-Algorithm=..."
},
"index": {
"location": {
"uri": "https://mybucket.s3.amazonaws.com/sample.bam.bai?X-Amz-Algorithm=..."
}
}
}
}'In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track..., choose Add track from pasted JSON, and paste:
{
"type": "AlignmentsTrack",
"trackId": "private_sample",
"name": "Sample from a private bucket",
"assemblyNames": ["hg38"],
"adapter": {
"type": "BamAdapter",
"bamLocation": {
"uri": "https://mybucket.s3.amazonaws.com/sample.bam?X-Amz-Algorithm=..."
},
"index": {
"location": {
"uri": "https://mybucket.s3.amazonaws.com/sample.bam.bai?X-Amz-Algorithm=..."
}
}
}
}Range requests work, because Range is not a header a presigned URL signs.
- Name the index yourself. The
urishorthand appends.baiafter the signature parameters, which the bucket rejects. - Choose the file type yourself. A signed URL ends in signature parameters,
not
.bam, so the Add track form guesses nothing; pick the type in the form or write the adaptertypeas above. - The link expires. Seven days is the maximum, and a URL signed with temporary credentials expires with the session that signed it. Any saved session or share link holding one stops working then.
An internet account that signs at fetch time
For access that does not expire, keep the permanent unsigned URL in the config
and have a plugin internet account sign each request, since no built-in type
covers S3. A state model extending BaseInternetAccountModel overrides
getFetcher and either computes a SigV4 signature in the browser over the URL,
method and range header, or asks your own backend to presign the URL and
fetches what comes back. Three rules either way:
- Only a temporary credential reaches the browser (a Cognito identity pool,
AssumeRoleWithWebIdentity, or your app's own session token that authorizes the presign call): config.json is public and a static app has nowhere to keep a long-lived key.validateTokenrenews it before it lapses. - Swap the URL inside the fetcher, never in the location. The range cache
keys on the URL the filehandle was constructed with, so a stable unsigned URL
keeps it intact;
GoogleDriveOAuthModelis the in-tree precedent. Cache presigned URLs per object with their expiry, so a chunk fetch never signs a URL. - Treat a
403as a possibly-stale signature and retry once after refreshing, since a credential can lapse between two chunk fetches.
The credential travels to the RPC workers over the existing pre-authorization
path as an opaque token, so neither shape needs extra code. Bucket CORS has to
allow the headers the signature covers (Authorization, Range, x-amz-date,
x-amz-content-sha256); see Serving data files.
CloudFront signed cookies need no JBrowse code, since your app renews the cookie and the browser attaches it, but only for data on the same origin as the app: JBrowse's data requests do not opt into sending credentials cross-origin.
An embedded component can skip both routes: the host app asks its own backend for a signed URL pair and builds the track config from the result. Mint the URLs on each page load, never into a saved session, and sign them for longer than a viewing session lasts, since a URL resolved before the component mounts cannot renew itself.
CORS
Authenticated requests are still cross-origin requests, so the data server must
allow the Authorization header (or whatever authHeader names) in
Access-Control-Allow-Headers. The token travels in that header, not a cookie,
so the server need not allow credentials, and Access-Control-Allow-Origin: *
works. See Serving data files.
See also
- Config guide: config.json format
- Config guide: Configuring tracks
- Reference: BaseInternetAccount config docs