Under the hood
Security model
How GOAT keeps each customer to their own rows.
This page is for security reviewers.
The boundaries
These controls keep one customer from another, and each one holds even if another fails.
| Control | What it does |
|---|---|
| The tenant comes from a signed token | Your backend names the tenant when it asks for a viewer token, with an API key. GOAT signs the tenant id into the token. Nothing a viewer's browser sends can change it. |
| Viewers run saved charts only | A viewer's request names a saved chart and the page's filter choices. GOAT builds the query on the server from the chart's saved definition. A request carrying a query of its own is refused (403 POINTER_ONLY). The one embed token that may carry its own query is the tenant-author token. |
| The tenant filter is added on the server | A dataset's tenant key is the column naming the customer each row belongs to. For every query on a dataset with a tenant key, GOAT adds a filter on that column for the token's tenant. The id is passed as a query parameter, never written into the SQL. A token with no tenant matches no rows. |
| Access is checked on every request | Each request checks that the tenant is registered and active, that the dashboard is published, and that the tenant has access to it. |
Datasets with no tenant key
A dataset with no tenant key is shared by default, so every tenant's charts read all its rows. An Author can turn sharing off, and embedded charts on it are then refused (403 RLS_REQUIRED). The rows behind a chart on such a dataset, and their download, are a stricter case. Sharing that is on only because nobody changed it does not serve them; an Author must turn the dataset's sharing on deliberately first. Use a dataset with no tenant key only for data that belongs to no customer.
Viewer tokens
| Property | Value |
|---|---|
| Signature | HMAC with SHA-256 (HS256). Any other algorithm is refused before the signature is checked. Signatures are compared in constant time. |
| Lifetime | One hour by default, at most 24 hours. A token whose lifetime claims more is refused, so even a misused signing key yields tokens of at most a day. |
| Contents | The install, the tenant id, an optional id for your user, an optional time zone and theme, and actions turned off. Never row values, filters, or anything that widens what the token reaches. |
| Audience | The install's own project. A token from another install is refused. |
| Revocation | GOAT cannot revoke one token. Suspending a tenant stops its tokens within a minute, and every other token stops working when its lifetime ends. |
The id you pass for your user is for your records. GOAT never uses it to decide access.
Signing keys
The signing keys are the versions of one secret in Secret Manager, Google Cloud's store for secrets: goat-embed-keyring. New tokens are signed with the newest enabled version; tokens signed with any enabled version are accepted. To rotate:
- Add a new version to the secret. New tokens use it within five minutes, with no redeploy.
- Wait at least 24 hours, the longest a token can live.
- Disable the old version. Within five minutes, tokens signed with it fail.
If a signing key leaks, disable its version at once instead of waiting. Every token signed with it fails within five minutes, and open embedded dashboards get new tokens from your backend.
GOAT's service account can read this secret and no other in the project. An install with no keyring refuses to start.
Tenant-author tokens
GOAT's server can also issue a second kind of embed token, for your customers' own authors. The embed script cannot use it yet, but the server accepts it today, and its holder can run queries it writes itself. It needs both an Admin's Embedded authoring switch on a collection and an API key with the mintAuthor scope. See Tenant-author tokens for what it can do and what keeps it in bounds.
API keys
An API key is stored only as a SHA-256 hash and shown once, when it is created. A key is limited to its scopes: asking for viewer tokens (mint), asking for tenant-author tokens (mintAuthor), or sending data (ingest). A key with no scope can ask for viewer tokens and nothing else. No API key can reach the tenant, grant, or settings parts of the API. Revoking a key stops it at once; tokens it already got last until they expire.
The token request is not open to browsers. It sends no cross-origin headers, and a page cannot send the API key header. Call it from your server.
Operators
Operators are the people who sign in to the GOAT app, as Admins or Authors; an Admin can do everything an Author can. They sign in through Identity Platform, Google Cloud's sign-in service, in your project. Every request carries their Identity Platform token.
- A sign-in lasts at most 12 hours from when the person signed in. Refreshing the token does not extend it.
- An account can require a second factor, from an authenticator app.
- Operators see every tenant's rows unless they choose one tenant with Preview as. Each operator query on a dataset with a tenant key that runs with no tenant filter writes a log entry in Cloud Logging.
- Columns classified PII or Sensitive are left out of the rows behind a chart for everyone but Admins and Authors.
Defense in depth
These help, but do not keep customers apart on their own:
| Control | What it does | Why it is not a boundary |
|---|---|---|
| Allowed sites | An Admin can list, through the settings API, the exact sites (https://app.example.com) allowed to show embedded dashboards. A request from a page elsewhere is refused (403 ORIGIN_DENIED). With no list set, any site is allowed. | A program outside a browser can claim any site. |
| Turning actions off in the token | Drill down, Show the rows, and Download CSV can be turned off per token. | Rows that reach a browser can be copied. |
| Classifying columns | Marking a column PII or Sensitive keeps it out of viewers' rows, and asks for confirmation before filters and drills use it. | It shapes what is offered; the tenant filter is what limits rows. |
Cross-origin requests
The routes an embedded dashboard calls allow cross-origin requests from any page, without cookies. Viewers authenticate with the token alone. The embed script itself can be loaded by any page.
What GOAT's service account can reach
Its grants are listed in Architecture on Google Cloud. A reviewer should weigh these:
- It can update any Identity Platform user in the project, to set operators' roles. Whoever controls GOAT's service account could therefore take over any account in that Identity Platform.
- It can read metadata across the whole project: every dataset's names, columns, view and routine definitions, and access lists, though no table rows.
- It can create, change, and run any scheduled BigQuery data transfer (a Data Transfer Service config) in the project, and make a transfer run with GOAT's own account and its access. A transfer left behind by someone who controlled the account keeps running as GOAT after that access ends. After a suspected compromise, list every transfer config in the project and delete any that you or GOAT did not create.
- It can change the
goatdataset's access list.
It can read no rows of your own datasets and no files in your buckets unless you grant it, one at a time. Cloud Run has no public access grant; GOAT's own checks decide every request.
What is recorded
Each chart query writes a record to the goat_telemetry BigQuery dataset in your project, kept 400 days: the chart, the dataset, the tenant id, how it was answered, and the bytes it billed. Your user's id is never written as is; a salted, one-way hash of it stands in.
Each read of the rows behind a chart writes a log entry in Cloud Logging, naming the tenant, the columns, and how many rows, never the values.
Every BigQuery job GOAT runs carries labels naming what it was for, and for viewers, the tenant.
Things to know
- By default, a dashboard's first publish gives every tenant access to it. A dashboard starts at its collection's default level, which is Visible for a new collection, so tenants with access can open it once it is published. To publish to no one at first, set the dashboard's level to None before publishing (see Choose who can see it), or have an Admin set
publishAutoGrantto"none"in the install settings. - Changes to access reach viewers within a minute, not at once. That covers unpublishing, removing access, suspending a tenant, and changing the allowed sites. GOAT caches the records behind embedded dashboards for up to 60 seconds.
- With automatic registration on, any well-formed tenant id your backend sends is registered and gets a token. Your backend alone then decides which tenant a viewer is. See Tenants and access.
- A deleted tenant loses its grants. With automatic registration on, it is registered again at its next token request. To cut a customer off, suspend it.