Gateway Operator Auth Lifecycle
The gateway operator auth gate uses GitHub OAuth to authenticate operators accessing the browser-visible operator surface at https://dashboard.fro.bot/operator/*. This runbook covers initial setup, secret seeding, rotation, and rollback for the four operator auth/config secrets.
Prerequisites
Section titled “Prerequisites”- The operator listener trio (
GATEWAY_OPERATOR_BIND_HOST,GATEWAY_OPERATOR_BIND_PORT,GATEWAY_OPERATOR_PUBLIC_ORIGIN) is set in thegatewayGitHub Environment. GATEWAY_VPC_IPandDASHBOARD_VPC_IPare set in thegatewayGitHub Environment (required whenever the listener is enabled;DASHBOARD_VPC_IPis the derivedGATEWAY_OPERATOR_TRUSTED_PROXIESvalue).- The
gatewayGitHub Environment exists with a required reviewer set. - You have admin access to the GitHub account that owns the OAuth App.
GitHub OAuth App Setup
Section titled “GitHub OAuth App Setup”Create a GitHub OAuth App (not a GitHub App) in the GitHub Developer Portal. This is a separate credential from the existing gateway GitHub App (GH_APP_ID); do not conflate them.
- Go to github.com/settings/developers → OAuth Apps → New OAuth App.
- Fill in the fields:
- Application name:
fro-bot operator(or similar) - Homepage URL:
https://dashboard.fro.bot - Authorization callback URL:
https://dashboard.fro.bot/operator/auth/github/callback
- Application name:
- Click Register application.
- Copy the Client ID — this is
GATEWAY_OPERATOR_GITHUB_CLIENT_ID. - Click Generate a new client secret — copy the secret immediately. This is
GATEWAY_OPERATOR_GITHUB_CLIENT_SECRET. GitHub shows it only once.
CSRF Secret Generation
Section titled “CSRF Secret Generation”The CSRF secret must be strict base64url: no padding (=), no whitespace, no newlines. The decoded byte length must be at least 32 bytes. A 32-byte random value encoded as base64url (no padding) produces a 43-character string.
Generic generation example (verify against upstream docs before use):
# Generic example — verify against upstream docs before useopenssl rand -base64 32 | tr '+/' '-_' | tr -d '='Never commit or log the output. Seed directly via stdin pipe (see Secret Seeding below).
Allowlist Format
Section titled “Allowlist Format”The allowlist is a newline-separated list of numeric GitHub user IDs. Obtain user IDs via the GitHub API:
curl -s https://api.github.com/users/<username> | jq .idFormat:
1234567887654321# This is a comment — ignoredBlank lines and full-line # comments (after optional leading whitespace) are ignored. At least one numeric user ID must remain after filtering. Non-numeric, non-comment lines are rejected. The upstream loader is fail-closed: a missing, empty, or malformed allowlist prevents the operator web surface from starting.
Secret Seeding
Section titled “Secret Seeding”All four auth/config secrets must be seeded via stdin pipe — never via --body substitution or shell here-strings. See docs/solutions/workflow-issues/gateway-first-deploy-cascade-2026-05-20.md for the corruption risk.
printf '%s' '<client-id>' | gh secret set --env gateway GATEWAY_OPERATOR_GITHUB_CLIENT_IDprintf '%s' '<client-secret>' | gh secret set --env gateway GATEWAY_OPERATOR_GITHUB_CLIENT_SECRETprintf '%s' '<csrf-secret>' | gh secret set --env gateway GATEWAY_OPERATOR_CSRF_SECRETprintf '%s' '<allowlist>' | gh secret set --env gateway GATEWAY_OPERATOR_ALLOWLISTReplace <client-id>, <client-secret>, <csrf-secret>, and <allowlist> with the actual values. For the allowlist, use $'...' quoting or a heredoc to include newlines:
printf '%s\n%s\n' '12345678' '87654321' | gh secret set --env gateway GATEWAY_OPERATOR_ALLOWLISTOptional tuning vars
Section titled “Optional tuning vars”If you need to override the OAuth tuning defaults, seed them as secrets via the same stdin pipe pattern (they are transported as optional secrets in the workflow):
printf '%s' '/operator,/operator/runs' | gh secret set --env gateway GATEWAY_OPERATOR_OAUTH_ALLOWED_RETURN_PATHSprintf '%s' '300000' | gh secret set --env gateway GATEWAY_OPERATOR_OAUTH_STATE_TTL_MSprintf '%s' '10' | gh secret set --env gateway GATEWAY_OPERATOR_OAUTH_MAX_OUTSTANDING_ATTEMPTSLeave these unset to use upstream defaults (/operator, 600000, 5).
Deploy and Verify
Section titled “Deploy and Verify”-
Trigger a deploy:
Terminal window bunx @marcusrbrown/infra gateway deploy -
Approve the environment gate in GitHub Actions.
-
Verify gateway-side liveness using the droplet-local direct probe (run on the droplet or via SSH):
Terminal window curl -sf http://172.21.0.2:9300/operator/healthThis should return
200 {"ok":true,"contractVersion":"<semver>"}.⚠ Liveness probe warning: Do not use
https://gateway.fro.bot/operator/healthas a liveness probe — through Caddy, the operator endpoint validates forwarded headers and requiresX-Forwarded-Hostto equal thePUBLIC_ORIGINhost (dashboard.fro.bot); because Caddy forwardsHost: gateway.fro.bot, the forwarded-host mismatches and the endpoint returns400 {"error":"bad request"}by design; the gateway-net Caddy address is deliberately not a trusted proxy. The gateway-side liveness probe is the droplet-local direct probe:curl -sf http://172.21.0.2:9300/operator/health→200 {"ok":true,"contractVersion":"<semver>"}. The dashboard same-origin path is live:https://dashboard.fro.bot/operator/health→200 {"ok":true,"contractVersion":"<semver>"}is a valid external probe (dashboard Caddy → VPC10.116.0.3:9300→ gateway operator listener). The OAuth callback URL registration uses the dashboard origin — this is a GitHub OAuth App setting, not a live HTTP probe target. -
Callback URL preflight: The deploy dry-run output prints the expected callback URL:
Expected OAuth callback URL: https://dashboard.fro.bot/operator/auth/github/callbackCross-check this string against the Authorization callback URL field in the GitHub OAuth App settings (GitHub Developer Portal → OAuth Apps → your app). This portal check is manual and must be completed before enablement. Infra cannot read or validate the OAuth App callback registration via API — no public GitHub API surface exposes this field.
-
Auth gate coarse check:
GET https://gateway.fro.bot/operator/returns400 {"error":"bad request"}by design — the forwarded-header guard rejects it because the forwarded host (gateway.fro.bot) does not match thePUBLIC_ORIGINhost (dashboard.fro.bot). Do not usegateway.fro.bot/operator/as an auth probe. The auth-gate / OAuth-redirect check is meaningful through the live same-origin path:curl -sI https://dashboard.fro.bot/operator/auth/github/startreturns302to GitHub OAuth. A full browser round-trip returns the operator identity JSON{"githubUserId":<operator-id>,"login":<login>}from the callback when the GitHub user is onGATEWAY_OPERATOR_ALLOWLIST. -
Allowlist enforcement check: Attempt to complete the OAuth flow with a GitHub account that is NOT in the allowlist. Confirm the response is a coarse auth-failure (non-5xx, no route or allowlist detail leaked).
-
Session survives restart: After a successful auth, trigger a gateway restart (
docker compose restart gatewayon the droplet). Confirm the gateway log showssession restore finishedand the same cookie still returns200from/operator/session. Sessions are durable (object store, fixed seven days from sign-in) — a restart does not end them. -
VPC-scoped operator port:
docker compose pson the gateway droplet shows the operator port published only on the VPC IP (10.116.0.3:9300->9300), never on0.0.0.0/all interfaces. The port is further restricted to the dashboard droplet by aDOCKER-USERiptables rule (per-deploy) and a DigitalOcean Cloud Firewall (provisioning). Confirm publicgateway.fro.bot:9300is unreachable.
Rotation
Section titled “Rotation”Rotating the GitHub OAuth client secret
Section titled “Rotating the GitHub OAuth client secret”- Go to the GitHub OAuth App settings → Generate a new client secret.
- Copy the new secret.
- Seed the new value:
Terminal window printf '%s' '<new-client-secret>' | gh secret set --env gateway GATEWAY_OPERATOR_GITHUB_CLIENT_SECRET - Trigger a deploy:
bunx @marcusrbrown/infra gateway deploy. - Approve the environment gate.
- Verify:
curl -sf http://172.21.0.2:9300/operator/health(run on the droplet or via SSH) returns200 {"ok":true,"contractVersion":"<semver>"}. - Delete the old client secret in the GitHub OAuth App settings.
Sessions are durable — the restart triggered by the checksum change does not end operator sessions, so operators stay signed in.
Rotating the CSRF secret
Section titled “Rotating the CSRF secret”- Generate a new CSRF secret (see CSRF Secret Generation).
- Seed the new value:
Terminal window printf '%s' '<new-csrf-secret>' | gh secret set --env gateway GATEWAY_OPERATOR_CSRF_SECRET - Trigger a deploy:
bunx @marcusrbrown/infra gateway deploy. - Approve the environment gate.
- Verify:
curl -sf http://172.21.0.2:9300/operator/health(run on the droplet or via SSH) returns200 {"ok":true,"contractVersion":"<semver>"}.
Rotating this secret is also how to invalidate every stored operator session; operators sign in again afterwards.
Updating the allowlist
Section titled “Updating the allowlist”- Prepare the new allowlist (one numeric GitHub user ID per line).
- Seed the new value:
Terminal window printf '%s\n%s\n' '12345678' '87654321' | gh secret set --env gateway GATEWAY_OPERATOR_ALLOWLIST - Trigger a deploy:
bunx @marcusrbrown/infra gateway deploy. - Approve the environment gate.
- Verify: attempt the OAuth flow with a removed user — confirm auth failure.
Rollback
Section titled “Rollback”To disable operator auth/config wiring entirely:
- Remove or clear both the listener trio and the four auth/config secrets from the
gatewayGitHub Environment:- Listener trio:
GATEWAY_OPERATOR_BIND_HOST,GATEWAY_OPERATOR_BIND_PORT,GATEWAY_OPERATOR_PUBLIC_ORIGIN - Auth/config secrets:
GATEWAY_OPERATOR_GITHUB_CLIENT_ID,GATEWAY_OPERATOR_GITHUB_CLIENT_SECRET,GATEWAY_OPERATOR_CSRF_SECRET,GATEWAY_OPERATOR_ALLOWLIST
- Listener trio:
- Trigger a deploy:
bunx @marcusrbrown/infra gateway deploy. - Approve the environment gate.
- The deploy detects the operator listener is disabled, skips all operator auth/config wiring, and runs
docker compose up --remove-orphans. - The gateway restarts with the operator listener disabled and serves no operator sessions. Session records stay in the object store; to invalidate them, rotate
GATEWAY_OPERATOR_CSRF_SECRETor deleteoperator-web/sessions/*. - Verify:
bunx @marcusrbrown/infra gateway statusshows all services healthy.
Note: Listener trio present + auth/config secrets absent is not a valid state — the deploy fails before any SSH. The only supported rollback is to clear both the listener trio and the four auth/config secrets together. This disables the operator listener entirely; the gateway continues to serve all other routes normally.
Secret File Mapping
Section titled “Secret File Mapping”The four auth/config secrets are materialized as files on the droplet under /opt/gateway/deploy/secrets/. Each file is owned root:root with mode 0600. Secret bytes enter via SSH stdin only — never via argv.
| Host file (kebab-case) | Compose mount (snake_case) | Container env var (_FILE) |
|---|---|---|
gateway-operator-github-client-id |
/run/secrets/gateway_operator_github_client_id |
GATEWAY_OPERATOR_GITHUB_CLIENT_ID_FILE |
gateway-operator-github-client-secret |
/run/secrets/gateway_operator_github_client_secret |
GATEWAY_OPERATOR_GITHUB_CLIENT_SECRET_FILE |
gateway-operator-csrf-secret |
/run/secrets/gateway_operator_csrf_secret |
GATEWAY_OPERATOR_CSRF_SECRET_FILE |
gateway-operator-allowlist |
/run/secrets/gateway_operator_allowlist |
GATEWAY_OPERATOR_ALLOWLIST_FILE |
The secrets checksum at /opt/gateway/.secrets-checksum includes these files when operator auth is enabled. Rotation of any auth/config secret changes the checksum, triggering --force-recreate on the next deploy.