Skip to content

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.


  • The operator listener trio (GATEWAY_OPERATOR_BIND_HOST, GATEWAY_OPERATOR_BIND_PORT, GATEWAY_OPERATOR_PUBLIC_ORIGIN) is set in the gateway GitHub Environment.
  • GATEWAY_VPC_IP and DASHBOARD_VPC_IP are set in the gateway GitHub Environment (required whenever the listener is enabled; DASHBOARD_VPC_IP is the derived GATEWAY_OPERATOR_TRUSTED_PROXIES value).
  • The gateway GitHub Environment exists with a required reviewer set.
  • You have admin access to the GitHub account that owns the OAuth App.

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.

  1. Go to github.com/settings/developers → OAuth Apps → New OAuth App.
  2. 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
  3. Click Register application.
  4. Copy the Client ID — this is GATEWAY_OPERATOR_GITHUB_CLIENT_ID.
  5. Click Generate a new client secret — copy the secret immediately. This is GATEWAY_OPERATOR_GITHUB_CLIENT_SECRET. GitHub shows it only once.

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):

Terminal window
# Generic example — verify against upstream docs before use
openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

Never commit or log the output. Seed directly via stdin pipe (see Secret Seeding below).


The allowlist is a newline-separated list of numeric GitHub user IDs. Obtain user IDs via the GitHub API:

Terminal window
curl -s https://api.github.com/users/<username> | jq .id

Format:

12345678
87654321
# This is a comment — ignored

Blank 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.


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.

Terminal window
printf '%s' '<client-id>' | gh secret set --env gateway GATEWAY_OPERATOR_GITHUB_CLIENT_ID
printf '%s' '<client-secret>' | gh secret set --env gateway GATEWAY_OPERATOR_GITHUB_CLIENT_SECRET
printf '%s' '<csrf-secret>' | gh secret set --env gateway GATEWAY_OPERATOR_CSRF_SECRET
printf '%s' '<allowlist>' | gh secret set --env gateway GATEWAY_OPERATOR_ALLOWLIST

Replace <client-id>, <client-secret>, <csrf-secret>, and <allowlist> with the actual values. For the allowlist, use $'...' quoting or a heredoc to include newlines:

Terminal window
printf '%s\n%s\n' '12345678' '87654321' | gh secret set --env gateway GATEWAY_OPERATOR_ALLOWLIST

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):

Terminal window
printf '%s' '/operator,/operator/runs' | gh secret set --env gateway GATEWAY_OPERATOR_OAUTH_ALLOWED_RETURN_PATHS
printf '%s' '300000' | gh secret set --env gateway GATEWAY_OPERATOR_OAUTH_STATE_TTL_MS
printf '%s' '10' | gh secret set --env gateway GATEWAY_OPERATOR_OAUTH_MAX_OUTSTANDING_ATTEMPTS

Leave these unset to use upstream defaults (/operator, 600000, 5).


  1. Trigger a deploy:

    Terminal window
    bunx @marcusrbrown/infra gateway deploy
  2. Approve the environment gate in GitHub Actions.

  3. 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/health

    This should return 200 {"ok":true,"contractVersion":"<semver>"}.

    ⚠ Liveness probe warning: Do not use https://gateway.fro.bot/operator/health as a liveness probe — through Caddy, the operator endpoint validates forwarded headers and requires X-Forwarded-Host to equal the PUBLIC_ORIGIN host (dashboard.fro.bot); because Caddy forwards Host: gateway.fro.bot, the forwarded-host mismatches and the endpoint returns 400 {"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 → VPC 10.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.

  4. Callback URL preflight: The deploy dry-run output prints the expected callback URL:

    Expected OAuth callback URL: https://dashboard.fro.bot/operator/auth/github/callback

    Cross-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.

  5. Auth gate coarse check: GET https://gateway.fro.bot/operator/ returns 400 {"error":"bad request"} by design — the forwarded-header guard rejects it because the forwarded host (gateway.fro.bot) does not match the PUBLIC_ORIGIN host (dashboard.fro.bot). Do not use gateway.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/start returns 302 to 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 on GATEWAY_OPERATOR_ALLOWLIST.

  6. 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).

  7. Session survives restart: After a successful auth, trigger a gateway restart (docker compose restart gateway on the droplet). Confirm the gateway log shows session restore finished and the same cookie still returns 200 from /operator/session. Sessions are durable (object store, fixed seven days from sign-in) — a restart does not end them.

  8. VPC-scoped operator port: docker compose ps on the gateway droplet shows the operator port published only on the VPC IP (10.116.0.3:9300->9300), never on 0.0.0.0/all interfaces. The port is further restricted to the dashboard droplet by a DOCKER-USER iptables rule (per-deploy) and a DigitalOcean Cloud Firewall (provisioning). Confirm public gateway.fro.bot:9300 is unreachable.


  1. Go to the GitHub OAuth App settings → Generate a new client secret.
  2. Copy the new secret.
  3. Seed the new value:
    Terminal window
    printf '%s' '<new-client-secret>' | gh secret set --env gateway GATEWAY_OPERATOR_GITHUB_CLIENT_SECRET
  4. Trigger a deploy: bunx @marcusrbrown/infra gateway deploy.
  5. Approve the environment gate.
  6. Verify: curl -sf http://172.21.0.2:9300/operator/health (run on the droplet or via SSH) returns 200 {"ok":true,"contractVersion":"<semver>"}.
  7. 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.

  1. Generate a new CSRF secret (see CSRF Secret Generation).
  2. Seed the new value:
    Terminal window
    printf '%s' '<new-csrf-secret>' | gh secret set --env gateway GATEWAY_OPERATOR_CSRF_SECRET
  3. Trigger a deploy: bunx @marcusrbrown/infra gateway deploy.
  4. Approve the environment gate.
  5. Verify: curl -sf http://172.21.0.2:9300/operator/health (run on the droplet or via SSH) returns 200 {"ok":true,"contractVersion":"<semver>"}.

Rotating this secret is also how to invalidate every stored operator session; operators sign in again afterwards.

  1. Prepare the new allowlist (one numeric GitHub user ID per line).
  2. Seed the new value:
    Terminal window
    printf '%s\n%s\n' '12345678' '87654321' | gh secret set --env gateway GATEWAY_OPERATOR_ALLOWLIST
  3. Trigger a deploy: bunx @marcusrbrown/infra gateway deploy.
  4. Approve the environment gate.
  5. Verify: attempt the OAuth flow with a removed user — confirm auth failure.

To disable operator auth/config wiring entirely:

  1. Remove or clear both the listener trio and the four auth/config secrets from the gateway GitHub 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
  2. Trigger a deploy: bunx @marcusrbrown/infra gateway deploy.
  3. Approve the environment gate.
  4. The deploy detects the operator listener is disabled, skips all operator auth/config wiring, and runs docker compose up --remove-orphans.
  5. 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_SECRET or delete operator-web/sessions/*.
  6. Verify: bunx @marcusrbrown/infra gateway status shows 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.


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.