Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

docs: gateway OIDC sign-in setup and local development guide (#400)

wojtyniakAQ6d852c1c5b3d
diff --git a/.env.example b/.env.example
index 2d8d70125..7a3bd0219 100644
--- a/.env.example
+++ b/.env.example
@@ -102,3 +102,18 @@ MATTERMOST_USER_PASSWORD=
# OAUTH_ISSUER_URL=https://your-idp.example.com/realms/switch
# OAUTH_AUDIENCE=switch
# OAUTH_VERIFY_ISSUER=true
+
+# ── Gateway OIDC login (optional — bring your own IdP for the browser login;
+# distinct from the OAUTH_* block above) ──────────────────────────────────────
+# See docs/old/GATEWAY_OIDC_SETUP.md before setting these, especially if the
+# provider is WorkOS: it needs a Connect application, not a User Management
+# client id. Issuer/client id/secret are all-or-nothing — set all three or
+# none. Quote GATEWAY_OIDC_SCOPES; it must include "openid" or no id_token is
+# issued.
+# GATEWAY_OIDC_ISSUER_URL=https://<your-idp-or-authkit-domain>
+# GATEWAY_OIDC_CLIENT_ID=<client-id>
+# GATEWAY_OIDC_CLIENT_SECRET=<client-secret>
+# GATEWAY_OIDC_SCOPES="openid profile email"
+# GATEWAY_OIDC_PROVIDER_LABEL=SSO
+# GATEWAY_OIDC_REDIRECT_URL=http://localhost:8000/gateway/auth/oidc/callback
+# GATEWAY_OIDC_REQUIRE_EMAIL_VERIFIED=true
diff --git a/CLAUDE.md b/CLAUDE.md
index c43cd5028..72a4b7029 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -233,6 +233,11 @@ Tests live in `core/tests/switch_core/` mirroring the module structure. Uses pyt
`ARCHITECTURE.md` overlap
- `docs/old/bridges/` — collaboration bridge setup: `README.md` plus one page each
for Slack, Mattermost, Discord, Teams, and Telegram
+- `docs/old/GATEWAY_OIDC_SETUP.md` — configuring the gateway's bring-your-own
+ OIDC browser sign-in (variables, redirect URI, WorkOS Connect setup)
+- `docs/old/LOCAL_DEVELOPMENT.md` — running Switch locally for development:
+ `just` recipes, which port serves what, connecting Switch Console to a
+ local server
There is no separate schema, room-design, HTTP-API or MCP-surface document. Read
those from the code: `core/switch_core/db/models.py` for the schema,
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8d17de9ee..4e1f20aff 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -31,6 +31,10 @@ hot-reload while developing: `just run` (switch-core on `:8000`) and
If you only want to see Switch running rather than develop against it, the
standalone stack in the [README](README.md#getting-started) is a shorter path.
+See [`docs/old/LOCAL_DEVELOPMENT.md`](docs/old/LOCAL_DEVELOPMENT.md) for the
+fuller account of this setup — what each port serves, and how to point
+Switch Console at your local server.
+
## Common commands
Run `just` with no arguments to list every recipe. The most-used ones:
@@ -68,6 +72,9 @@ Run `just` with no arguments to list every recipe. The most-used ones:
[`docs/old/ARCHITECTURE.md`](docs/old/ARCHITECTURE.md) describes the service's internal
module structure and the key request flows.
+[`docs/old/GATEWAY_OIDC_SETUP.md`](docs/old/GATEWAY_OIDC_SETUP.md) covers
+setting up bring-your-own OIDC sign-in for the gateway, including the WorkOS
+setup path.
## Testing
diff --git a/docs/README.md b/docs/README.md
index dd9f8acb6..e924e1fc1 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -19,7 +19,8 @@ site presents them.
## `old/`
Design and operator material written for this repository: the architecture
-overview, the agent protocol, and per-bridge setup guides. None of it is
-published, and none of it is covered by the pages under `official/` — where the
-two describe the same thing, this is the deeper account and the published page is
+overview, the agent protocol, per-bridge setup guides, gateway OIDC sign-in
+setup, and running Switch locally for development. None of it is published,
+and none of it is covered by the pages under `official/` — where the two
+describe the same thing, this is the deeper account and the published page is
the one users act on.
diff --git a/docs/old/GATEWAY_OIDC_SETUP.md b/docs/old/GATEWAY_OIDC_SETUP.md
new file mode 100644
index 000000000..8bbda6c4f
--- /dev/null
+++ b/docs/old/GATEWAY_OIDC_SETUP.md
@@ -0,0 +1,198 @@
+# Gateway OIDC sign-in setup
+
+The gateway (the operator dashboard's backend, mounted at `/gateway`) has a
+complete generic OIDC browser sign-in path — bring your own identity provider,
+no code changes. It is enabled purely by configuration
+(`core/switch_core/config.py`, `core/switch_core/gateway/oidc_routes.py`), and
+works against any standards-compliant IdP that publishes OIDC discovery
+metadata (Okta, Keycloak, Auth0, WorkOS Connect, …). This page covers the
+variables, the registration steps a provider needs from you, and one
+WorkOS-specific trap that will otherwise cost you an afternoon.
+
+OIDC login is additive: password login (`GATEWAY_ADMIN_EMAIL` /
+`GATEWAY_ADMIN_PASSWORD` and any user created under it) keeps working unless
+you explicitly turn it off with `GATEWAY_PASSWORD_LOGIN_ENABLED=false`.
+
+## The variables
+
+| Variable | Required | What it does |
+| --- | --- | --- |
+| `GATEWAY_OIDC_ISSUER_URL` | yes* | The IdP's issuer. The gateway appends `/.well-known/openid-configuration` to it and discovers the authorize, token, JWKS and (where published) userinfo endpoints from there — nothing else about the provider is configured by hand. |
+| `GATEWAY_OIDC_CLIENT_ID` | yes* | The client id registered with the IdP for this application. |
+| `GATEWAY_OIDC_CLIENT_SECRET` | yes* | The client secret for that same registration. |
+| `GATEWAY_OIDC_SCOPES` | no, but see below | Space-separated OAuth scopes requested at authorize time, e.g. `openid profile email`. |
+| `GATEWAY_OIDC_REDIRECT_URL` | no, but see below | The absolute callback URL registered with the IdP. |
+| `GATEWAY_OIDC_PROVIDER_LABEL` | no | Text shown on the login button ("Log in with `<label>`"). Defaults to "SSO" if unset. |
+| `GATEWAY_OIDC_REQUIRE_EMAIL_VERIFIED` | no | Defaults to `true`. See "What turning this off means" below. |
+
+*\*All-or-nothing.* `GATEWAY_OIDC_ISSUER_URL`, `GATEWAY_OIDC_CLIENT_ID` and
+`GATEWAY_OIDC_CLIENT_SECRET` are validated as a group at startup: set all
+three or none of them. Setting one or two without the rest fails config
+construction immediately (`Partial gateway OIDC config: set all of
+GATEWAY_OIDC_ISSUER_URL / GATEWAY_OIDC_CLIENT_ID / GATEWAY_OIDC_CLIENT_SECRET,
+or none of them.`) rather than starting up with OIDC silently disabled. OIDC
+is considered configured (`gateway_oidc_enabled`) exactly when all three are
+set; every other variable in the table is independently optional and has a
+default.
+
+### Scopes: always set this, and quote it
+
+`GATEWAY_OIDC_SCOPES` has no default — if you don't set it, the gateway asks
+authlib to request an unspecified scope, which most providers resolve to
+whatever their own default is. Set it explicitly, and **make sure it includes
+`openid`**: without that scope the token response carries no `id_token`, and
+the callback is left asking the provider's userinfo endpoint for claims
+instead — which some providers answer and some refuse.
+
+Quote the value in your env file. `GATEWAY_OIDC_SCOPES=openid profile email`
+(unquoted, with spaces) breaks `just`'s env-file parser — every recipe loads
+`.env` through it (`set dotenv-load := true` in the justfile), and it fails
+loudly: `error: failed to load environment file ... Error parsing line`, exit
+1, the recipe never runs. That protection only applies through `just`,
+though: running `uv run python -m switch_core.main` directly skips it
+entirely. Plain `uv run` doesn't read `.env` at all, so the variable is
+simply unset there; `uv run --env-file .env` reads it but only warns on the
+bad line and continues. Either way, going around `just` trades the loud
+parse error for a silent one: `GATEWAY_OIDC_SCOPES` ends up unset, and the
+provider is asked for whatever scope it defaults to instead — with nothing
+pointing back at the scope configuration if that default happens not to
+include `openid`. Write it as:
+
+```
+GATEWAY_OIDC_SCOPES="openid profile email"
+```
+
+### The redirect URL
+
+`GATEWAY_OIDC_REDIRECT_URL` is technically optional: if you leave it unset,
+the login route builds the callback URL from the incoming request
+(`request.url_for("oidc_callback")`). That only works when the gateway sees
+the same scheme and host the browser used — behind a reverse proxy or a
+Tailscale funnel it usually doesn't, so set it explicitly for anything other
+than a bare local server. Set it always if you're not sure.
+
+The real path, mounted where the gateway app lands on the root ASGI app, is
+**`/gateway/auth/oidc/callback`**. A full value looks like
+`https://switch-gateway.example.com/gateway/auth/oidc/callback` (or, for a
+local dev server hit directly on its own port,
+`http://localhost:8000/gateway/auth/oidc/callback`). It has to match the
+value registered with the IdP **character for character** — scheme, host,
+port and path — or the provider refuses the callback before Switch ever sees
+it.
+
+### What turning off email-verified enforcement means
+
+By default, a login is refused unless the IdP's token asserts
+`email_verified: true` on the claim Switch is about to trust for
+just-in-time provisioning (see below). This exists because provisioning
+binds a brand-new local account to whatever email the token carries, and an
+email address on its own proves nothing unless the IdP has confirmed the
+holder controls it. If an IdP lets a user self-assert or change their own
+address without verifying it, anyone who can complete a login can provision
+a Switch account under an email they don't own — including one a real
+colleague hasn't signed in with yet. Switch already refuses to create a
+second account over one that's already claimed (see the conflict rule
+below), so this isn't a way to take over an existing account, but it does
+let an attacker squat an unclaimed address first, and the genuine owner's
+first real login then hits that same conflict and is locked out instead of
+provisioned. Separately, some providers *never* set the claim true for
+directory-provisioned users, which would lock every one of them out
+permanently if left at the default.
+
+`GATEWAY_OIDC_REQUIRE_EMAIL_VERIFIED=false` is the escape hatch for that
+second case. Set it only when the IdP's addresses are authoritative on their
+own — a single-tenant corporate directory or HR-provisioned identity source
+— never for an IdP where a user can set their own email. Turning it off is a
+real reduction in the guarantee behind every OIDC-provisioned account's
+email address, not a cosmetic toggle.
+
+## First sign-in: what gets provisioned
+
+On the first successful login from a given IdP identity, the gateway
+provisions a user just-in-time: a local `user`-role account, no password
+hash, bound to the immutable `(issuer, subject)` pair from the token — never
+to the mutable email address. This is the behavior on `main` today
+(`core/switch_core/db/stores/user_store.py`); it may change as the identity
+model evolves, so check that file if this page has drifted.
+
+Two things worth knowing before your first login:
+
+- **It is deliberately not linked to an existing local account with the same
+ email.** If a password-authenticated account already owns that email
+ address, the OIDC login is refused with a conflict rather than silently
+ taking over the account — auto-linking by email is an account-takeover
+ vector (a token asserting someone else's email would otherwise inherit
+ their account, including a seeded admin's). There is currently no
+ self-service linking flow; a conflicting account has to be resolved by an
+ admin.
+- **Every OIDC-provisioned user gets the `user` role**, never `admin`.
+ Promote it by hand afterwards if it needs elevated access.
+
+## Setting up WorkOS as the provider
+
+This is the part that will otherwise burn an afternoon. WorkOS exposes two
+different sign-in surfaces, and only one of them is a standards-compliant
+OIDC provider that this gateway (or any generic OIDC client) can use.
+
+**The one that looks right but isn't: WorkOS User Management.**
+`https://api.workos.com/user_management/<client_id>` serves a
+`.well-known/openid-configuration` document, so it passes the first sanity
+check — discovery succeeds, the gateway registers the client without
+complaint. But the token response carries no `id_token`, and the discovery
+document publishes no `userinfo` endpoint either; profile data comes back
+through WorkOS's own proprietary User Management API instead. A generic OIDC
+client has nowhere to read claims from, and every login fails at the
+"OIDC token missing email or sub claim" check. Nothing about the discovery
+step tells you this in advance.
+
+**The one that actually works: WorkOS Connect.** The spec-compliant surface
+lives at the environment's **AuthKit domain**, `https://<slug>.authkit.app`.
+It publishes a proper `id_token` (RS256-signed), a `userinfo` endpoint, JWKS,
+and standard scope handling — this is what `GATEWAY_OIDC_ISSUER_URL` should
+point at, never the `user_management` URL above.
+
+Connect has its **own, separate client registry**, distinct from the User
+Management client id you'd otherwise reach for:
+
+1. In the WorkOS dashboard, create a **Connect OAuth application** — type
+ **OAuth**, **confidential**. This is a different object from anything in
+ the dashboard's AuthKit **Applications** list; it will not appear there,
+ and that mismatch is the single most common source of confusion when
+ setting this up. If you try to reuse the User Management client id
+ against the AuthKit domain instead, WorkOS rejects it with
+ `application_not_found` — the two registries don't share ids.
+2. Register your redirect URI (`.../gateway/auth/oidc/callback`, see above)
+ on that Connect application.
+3. Generate the application's client secret **in the dashboard**. This step
+ has no API path: the WorkOS MCP server exposes
+ `deleteApplicationCredential` but nothing to create one, and the REST
+ Applications API documents no credentials endpoint. Dashboard only.
+4. Set `GATEWAY_OIDC_ISSUER_URL` to the AuthKit domain
+ (`https://<slug>.authkit.app`), and `GATEWAY_OIDC_CLIENT_ID` /
+ `GATEWAY_OIDC_CLIENT_SECRET` to the Connect application's credentials.
+
+**Finding the AuthKit domain for an environment.** If you don't already know
+it, call the User Management authorize endpoint with the User Management
+client id and read where it redirects you — it lands on the AuthKit domain
+for that environment:
+
+```
+GET https://api.workos.com/user_management/authorize?client_id=<user_management_client_id>&response_type=code&redirect_uri=<any_uri>
+```
+
+Read the `Location` header of the redirect response; the host is your
+AuthKit domain.
+
+Recommended scopes for WorkOS Connect: `GATEWAY_OIDC_SCOPES="openid profile
+email"` (quoted, per the warning above).
+
+## Verifying it end to end
+
+1. Set the three required variables plus `GATEWAY_OIDC_SCOPES` and
+ `GATEWAY_OIDC_REDIRECT_URL`, and restart the server.
+2. `GET /gateway/auth/config` should report `oidc_enabled: true` and your
+ `oidc_provider_label` (or `null`, which the login page shows as "SSO").
+3. Visiting the login page should show a "Log in with `<label>`" button
+ alongside the password form (unless you disabled password login). Signing
+ in should land you back on `FRONTEND_BASE_URL` with a `switch_auth`
+ session cookie set.
diff --git a/docs/old/LOCAL_DEVELOPMENT.md b/docs/old/LOCAL_DEVELOPMENT.md
new file mode 100644
index 000000000..bc244e62c
--- /dev/null
+++ b/docs/old/LOCAL_DEVELOPMENT.md
@@ -0,0 +1,155 @@
+# Running Switch locally for development
+
+This covers the local-development path only: everything runs on your own
+machine, with hot-reload on the backend and the frontend. It's a different
+shape from the two paths the published docs cover —
+[`standalone`](../official/deploy/self-host.md) (single Docker Compose stack,
+built images, no host toolchain) and the Helm chart — so don't reach for
+those commands here; `just standalone-up` runs a whole different set of
+containers and none of what follows applies to it.
+
+Everything below is one recipe per `just` line, all defined in the root
+[`justfile`](../../justfile). Run `just` with no arguments any time to see
+the full list.
+
+## Prerequisites
+
+[Docker](https://docs.docker.com/get-docker/), [uv](https://docs.astral.sh/uv/),
+[just](https://github.com/casey/just) (`brew install just`), and Node for the
+gateway frontend.
+
+```bash
+just init-env # first-time setup — generate .env with random secrets
+uv sync # install Python dependencies (core/)
+just gateway-install # install gateway frontend deps (first time only)
+```
+
+`just init-env` copies `.env.example` to `.env` and fills every secret field
+that ships blank — `DB_PASSWORD`, `AGENT_REGISTRATION_TOKEN`,
+`JWT_SECRET_KEY`, `GATEWAY_ADMIN_PASSWORD`, `MATTERMOST_ADMIN_PASSWORD`,
+`MATTERMOST_USER_PASSWORD` — with a freshly generated `openssl rand -hex 24`
+value, then prints the gateway admin login it just set. The fields ship
+blank on purpose: it means no default credential (the old `admin`/`admin`)
+can ever reach a running stack by accident. The recipe refuses to touch an
+existing `.env`, so re-running it never rotates secrets out from under a
+stack that's already up — delete `.env` first if you actually want to
+regenerate everything. `just` loads `.env` automatically for every recipe
+below (`set dotenv-load := true` in the justfile), so nothing else needs to
+source it.
+
+## Starting the stack
+
+```bash
+just up # start the supporting services (Docker Compose)
+just migrate # apply database migrations
+just run # run switch-core (:8000)
+just gateway-dev # run the gateway frontend, in a separate terminal (:5173)
+```
+
+**`just up` starts the supporting services only**: PostgreSQL, Mattermost
+(seeded as the local collaboration bridge), and a one-shot `setup` container
+that provisions the Mattermost team/bot/admin accounts named by the
+`MATTERMOST_*` variables. It does **not** start switch-core and does **not**
+start the gateway frontend — you run both of those yourself, in their own
+terminals, so each gets hot-reload while you work. `just down` stops the
+stack; `just reset` also wipes its volumes (Postgres data included).
+
+`just migrate` runs `alembic upgrade head` against the Postgres started by
+`just up`. Run it once after the stack is up and again after pulling any
+change that adds a migration — `just run` does not apply migrations itself
+and will fail against a database that's behind.
+
+`just run` starts switch-core (`python -m switch_core.main`) on
+`SERVER_PORT` (`8000` by default). This one process is both the Agent Bridge
+API (where agents and the MCP server connect) and the gateway management API,
+mounted at `/gateway` on the same app — there is no separate backend process
+for the dashboard.
+
+### The part that's easy to miss: `just gateway-dev`
+
+**`just up` does not start the gateway frontend, and nothing warns you.**
+The operator dashboard you'd open in a browser is a separate Vite dev
+server, started with `just gateway-dev` (`cd gateway && npm run dev`), and it
+listens on **`:5173`**, not `:8000`. Forget to start it and there is simply
+nothing at `localhost:5173`; go to `localhost:8000` instead expecting a UI
+and you get switch-core's raw JSON API responses — it never serves the
+dashboard's static assets, in dev or otherwise. In a standalone or Helm
+deployment the dashboard is served by yet another process (the `gateway`
+image, a separate container), so this is a permanent split, not a dev-mode
+shortcut: switch-core is the API, something else is always the UI.
+
+The Vite dev server proxies every `/gateway/*` request to
+`http://127.0.0.1:8000` (see `gateway/vite.config.ts`), so from the browser's
+point of view the dashboard and its API calls share one origin
+(`localhost:5173`) even though two separate processes are actually serving
+them. That's also why cookie-based gateway auth (including OIDC login, see
+[`GATEWAY_OIDC_SETUP.md`](GATEWAY_OIDC_SETUP.md)) just works in dev without
+any CORS configuration: as far as the browser can tell, it never left
+`:5173`.
+
+## Which URL is which
+
+| URL | What's there | Started by |
+| --- | --- | --- |
+| `http://localhost:5173` | The operator dashboard (Vite dev server). Open this in a browser. | `just gateway-dev` |
+| `http://localhost:8000` | switch-core: the Agent Bridge API, the MCP server, and the gateway management API under `/gateway/*`. JSON, not a UI. | `just run` |
+| `http://localhost:8065` | Mattermost, seeded as the local collaboration bridge. | `just up` |
+| `http://localhost:5432` | PostgreSQL. | `just up` |
+
+`FRONTEND_BASE_URL` in `.env` (default `http://localhost:5173`) tells
+switch-core where to send the browser back to after a flow that leaves the
+dashboard, such as the OIDC login redirect — it should match wherever
+`just gateway-dev` is actually listening.
+
+## Connecting Switch Console to your local server
+
+Switch Console (the desktop app) talks to a Switch server over two
+addresses: a **Gateway URL** and an **API URL** — see [Add a
+server](../official/getting-started/add-a-server.md) for what each field
+means in general. They are not the same address in local dev, and getting
+either one wrong fails in a way that points somewhere else:
+
+- **API URL** is `http://localhost:8000` — switch-core directly. This is the
+ address Console writes into each connected agent's own config as the
+ endpoint it registers against and talks to (the Agent Bridge / MCP
+ surface), so it always names switch-core itself.
+- **Gateway URL** is `http://localhost:5173` — the Vite dev server, **not**
+ `:8000`. Console uses this address for everything session-cookie-based:
+ its own calls into `/gateway/*` (signing in, listing agents and rooms),
+ the **Open** button under "Full admin interface" (which opens this exact
+ URL in your browser), and the periodic check that decides whether the
+ server shows as reachable. `just gateway-dev` has to be running for any of
+ that to work — Vite's `/gateway` proxy is what makes `:5173` stand in for
+ switch-core's session-authenticated surface, the same way it does for the
+ browser dashboard above.
+
+Setting the Gateway URL to `:8000` looks reasonable, since switch-core does
+answer `/gateway/*` on that port directly, but it hits the thing this page
+already warned about: switch-core never serves the dashboard's static
+assets. The reachability check still passes — `/gateway/*` genuinely
+answers on `:8000` — so the only symptom is the **Open** button loading a
+bare JSON response instead of the admin UI; nothing on the server list looks
+wrong.
+
+The opposite mistake is quieter and easier to hit by accident: forget to
+start `just gateway-dev`, and there is nothing at `:5173` to answer the
+Gateway URL check, so Console reports the **whole server** as unreachable —
+even though switch-core (`just run`) is healthy and the API URL is
+answering fine. The symptom points at the backend; the actual cause is the
+frontend dev server not running.
+
+In Switch Console, add a server, choose **Connect to an existing server**,
+and enter `http://localhost:5173` as the Gateway URL and
+`http://localhost:8000` as the API URL — with `just gateway-dev` already
+running.
+
+## Other useful recipes
+
+| Command | What it does |
+| --- | --- |
+| `just format` / `just check` | Format with ruff / lint-check in CI mode (no changes) |
+| `just typecheck` | mypy over `core/switch_core/` and `connectors/` |
+| `just test` / `just test -k name` | Run the test suite / a single test |
+| `just test-integration` | Integration tests against a real Postgres via testcontainers |
+| `just migration "message"` | Autogenerate a new Alembic migration |
+| `just gateway-build` | Build the gateway frontend's production bundle |