Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
docs: gateway OIDC sign-in setup and local development guide (#400)
wojtyniakAQ6d852c1c5b3d
diff --git a/.env.example b/.env.exampleindex 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=truediff --git a/CLAUDE.md b/CLAUDE.mdindex 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 eachfor 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 serverThere is no separate schema, room-design, HTTP-API or MCP-surface document. Readthose from the code: `core/switch_core/db/models.py` for the schema,diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 8d17de9ee..4e1f20aff 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -31,6 +31,10 @@ hot-reload while developing: `just run` (switch-core on `:8000`) andIf you only want to see Switch running rather than develop against it, thestandalone 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 commandsRun `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 internalmodule 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.## Testingdiff --git a/docs/README.md b/docs/README.mdindex 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 isthe one users act on.diff --git a/docs/old/GATEWAY_OIDC_SETUP.md b/docs/old/GATEWAY_OIDC_SETUP.mdnew file mode 100644index 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.mdnew file mode 100644index 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 |