zuplo 6.70.53 → 6.70.55

package/docs/mcp-gateway/auth/configuring-okta.mdx

@@ -0,0 +1,199 @@
+---
+title: "Configuring Okta"
+sidebar_label: "Okta"
+description:
+  Configure Okta to back the MCP Gateway's downstream OAuth using the
+  mcp-okta-oauth-inbound policy. Covers Okta application setup and wiring the
+  policy in your gateway project.
+---
+
+The MCP Gateway can use Okta as the identity provider behind its downstream
+OAuth flow. The `mcp-okta-oauth-inbound` policy is an Okta-friendly wrapper
+around the generic `mcp-oauth-inbound` policy: provide your Okta domain, a
+client ID, and a client secret, and the policy derives the OIDC issuer, JWKS
+URL, and authorize and token URLs for you.
+
+This guide walks through the Okta admin console setup, then wires the policy
+into a gateway project. Read the [authentication overview](./overview.mdx) first
+for the two-layer model and the role each policy plays.
+
+The wrapper supports both Okta's **org authorization server** (the default) and
+**custom authorization servers**. Custom authorization servers give you control
+over scopes and audiences; the org server is fine for the gateway's
+identity-only use of Okta.
+
+## Set up Okta
+
+The MCP Gateway acts as an OAuth 2.1 authorization server in front of Okta. Okta
+handles browser login and identity; the gateway issues its own access tokens
+that bind to MCP routes. The Okta application you create represents the
+**gateway's identity** against Okta, not the MCP client.
+
+### Create an OIDC application
+
+1. In the Okta Admin Console, open **Applications → Applications** and click
+   **Create App Integration**.
+2. Choose **OIDC - OpenID Connect** as the sign-in method and **Web
+   Application** as the application type. Click **Next**.
+3. Give the integration a name (for example, `Zuplo MCP Gateway`).
+4. Under **Grant types**, leave **Authorization Code** checked. The gateway does
+   not need refresh tokens from Okta — it uses Okta only for browser identity,
+   not as a long-running token source.
+5. Set **Sign-in redirect URIs** to your gateway's
+   `https://<gateway-host>/oauth/callback`. Add
+   `http://localhost:9000/oauth/callback` for local development with
+   `zuplo dev`.
+6. Under **Assignments**, restrict access to the groups or users who should be
+   able to authenticate against the gateway.
+7. Click **Save**.
+
+Note the **Client ID** and **Client Secret** from the application's **General**
+tab. You'll wire these into the policy in the next section.
+
+### Optional: pick a custom authorization server
+
+By default the policy uses the Okta org authorization server, which is enough
+for gateway browser identity. If you already operate a custom authorization
+server, open **Security → API → Authorization Servers** in the Okta admin
+console and note the server's **name** (such as `default` or `customer-portal`).
+You'll pass that name as the `authorizationServerId` option.
+
+## Wire the policy into the gateway
+
+Add the policy to `config/policies.json`:
+
+```json
+{
+  "name": "okta-managed-oauth",
+  "policyType": "mcp-okta-oauth-inbound",
+  "handler": {
+    "module": "$import(@zuplo/runtime/mcp-gateway)",
+    "export": "McpOktaOAuthInboundPolicy",
+    "options": {
+      "oktaDomain": "$env(OKTA_DOMAIN)",
+      "clientId": "$env(OKTA_CLIENT_ID)",
+      "clientSecret": "$env(OKTA_CLIENT_SECRET)"
+    }
+  }
+}
+```
+
+:::caution
+
+`oktaDomain` is a **bare hostname** like `acme.okta.com` or
+`acme.oktapreview.com`. Don't include `https://`, a trailing slash, or an
+`/oauth2/...` path.
+
+:::
+
+Set the three environment variables in your project's environment configuration.
+`OKTA_DOMAIN` goes in plain config; the secret values belong in the project
+secret store.
+
+To use a custom authorization server, add `authorizationServerId`:
+
+```json
+{
+  "options": {
+    "oktaDomain": "$env(OKTA_DOMAIN)",
+    "authorizationServerId": "default",
+    "clientId": "$env(OKTA_CLIENT_ID)",
+    "clientSecret": "$env(OKTA_CLIENT_SECRET)"
+  }
+}
+```
+
+Attach the policy to each MCP route in `config/routes.oas.json`:
+
+```jsonc
+{
+  "paths": {
+    "/mcp/linear-v1": {
+      "get,post": {
+        "operationId": "linear-mcp-server",
+        "x-zuplo-route": {
+          "corsPolicy": "none",
+          "handler": {
+            "module": "$import(@zuplo/runtime/mcp-gateway)",
+            "export": "McpProxyHandler",
+            "options": {
+              "rewritePattern": "https://mcp.linear.app/mcp",
+            },
+          },
+          "policies": {
+            "inbound": ["okta-managed-oauth", "mcp-token-exchange-linear"],
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Register the gateway plugin in `modules/zuplo.runtime.ts`:
+
+```ts
+import { RuntimeExtensions } from "@zuplo/runtime";
+import { McpGatewayPlugin } from "@zuplo/runtime/mcp-gateway";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(new McpGatewayPlugin());
+}
+```
+
+One MCP OAuth policy serves every MCP route in the project — attach the same
+policy by name to each route.
+
+## Full options reference
+
+| Option                                    | Required | Default                | Notes                                                                                 |
+| ----------------------------------------- | -------- | ---------------------- | ------------------------------------------------------------------------------------- |
+| `oktaDomain`                              | yes      | —                      | Bare hostname (`acme.okta.com`). No scheme.                                           |
+| `authorizationServerId`                   | no       | unset (org server)     | Name of an Okta custom authorization server, e.g. `default`.                          |
+| `clientId`                                | yes      | —                      | Okta application client ID.                                                           |
+| `clientSecret`                            | yes      | —                      | Okta application client secret. Use `$env(...)`.                                      |
+| `scope`                                   | no       | `openid profile email` | OIDC scopes requested during browser login.                                           |
+| `gateway.accessTokenTtlSeconds`           | no       | `900`                  | Gateway-issued access token lifetime.                                                 |
+| `gateway.refreshTokenTtlSeconds`          | no       | long-lived             | Gateway-issued refresh token lifetime. Override only if you need to shorten sessions. |
+| `gateway.cimdEnabled`                     | no       | `true`                 | Advertise CIMD support in AS metadata.                                                |
+| `browserLoginOverrides.sessionTtlSeconds` | no       | `28800`                | Browser session cookie lifetime (8 hours).                                            |
+| `browserLoginOverrides.stateTtlSeconds`   | no       | `900`                  | Browser-login state record lifetime.                                                  |
+| `browserLoginOverrides.remoteTimeoutMs`   | no       | `10000`                | Outbound timeout to Okta (token exchange, JWKS fetch).                                |
+
+## Test the configuration
+
+The fastest sanity check is to connect an MCP client:
+
+1. Open Claude Desktop, Cursor, Claude Code, or another OAuth-aware MCP client.
+2. Add a remote MCP server pointing at one of your `/mcp/{slug}` routes on the
+   gateway.
+3. The client should redirect you to Okta's login page. After login, the
+   gateway's consent screen renders. Approve it.
+4. The client receives an access token and can call `tools/list`.
+
+If something fails partway through, walk the flow manually using the
+[manual OAuth testing guide](./manual-oauth-testing.mdx) — it exercises every
+endpoint with `curl` so you can see the raw responses.
+
+## Common issues
+
+- **"Invalid Okta domain" at boot.** `oktaDomain` includes a scheme prefix,
+  trailing slash, or path. Use `acme.okta.com`.
+- **Browser login redirects but the callback fails.** The
+  `https://<gateway-host>/oauth/callback` URL isn't on the application's
+  **Sign-in redirect URIs** allow-list in Okta.
+- **`invalid_audience` from the gateway's token endpoint.** The MCP client is
+  reusing a token bound to a different route. Each gateway-issued token binds to
+  one MCP route.
+- **MCP client can't discover the AS.** Confirm the `mcp-okta-oauth-inbound`
+  policy is attached to the route in `routes.oas.json` and the
+  `McpGatewayPlugin` is registered in `modules/zuplo.runtime.ts`. The internal
+  OAuth endpoints register only when both are present.
+
+## Related
+
+- [Authentication overview](./overview.mdx)
+- [Configuring Auth0](./configuring-auth0.mdx) — the most-used wrapper
+- [Configuring a generic OIDC provider](./configuring-generic-oidc.mdx) — for
+  IdPs without a first-class wrapper.
+- [Per-user OAuth to upstream MCP servers](./upstream-oauth.mdx)

package/docs/mcp-gateway/auth/configuring-onelogin.mdx

@@ -0,0 +1,122 @@
+---
+title: "Configuring OneLogin"
+sidebar_label: "OneLogin"
+description:
+  Configure OneLogin to back the MCP Gateway's downstream OAuth using the
+  mcp-onelogin-oauth-inbound policy. Covers OIDC app setup and wiring the policy
+  in your gateway project.
+---
+
+The MCP Gateway can use OneLogin as the identity provider behind its downstream
+OAuth flow. The `mcp-onelogin-oauth-inbound` policy is a OneLogin-friendly
+wrapper around the generic `mcp-oauth-inbound` policy: provide your OneLogin
+account subdomain, a client ID, and a client secret, and the policy derives the
+OIDC v2 issuer, JWKS URL, and authorize and token URLs for you.
+
+This guide walks through the OneLogin admin portal setup, then wires the policy
+into a gateway project. Read the [authentication overview](./overview.mdx) first
+for the two-layer OAuth model.
+
+## Set up OneLogin
+
+The MCP Gateway acts as an OAuth 2.1 authorization server in front of OneLogin.
+OneLogin handles browser login; the gateway issues its own access tokens that
+bind to MCP routes.
+
+### Create an OIDC application
+
+1. In the OneLogin admin portal, open **Applications → Applications** and click
+   **Add App**.
+2. Search for **OpenID Connect (OIDC)** and pick the matching app.
+3. Give the application a display name (for example, `Zuplo MCP Gateway`) and
+   click **Save**.
+4. Open the application's **Configuration** tab.
+5. Set **Redirect URIs** to `https://<gateway-host>/oauth/callback`. Add
+   `http://localhost:9000/oauth/callback` for local development.
+6. Set **Login Url** to your gateway origin (`https://<gateway-host>`).
+7. Save.
+
+### Configure SSO settings
+
+1. Open the application's **SSO** tab.
+2. Set **Token Endpoint Authentication Method** to **POST**.
+3. Note the **Client ID** and **Client Secret** shown on the page.
+
+### Assign users
+
+Under the application's **Access** tab, assign the roles or users that should be
+able to authenticate through the gateway.
+
+### Find your OneLogin subdomain
+
+Your OneLogin subdomain is the prefix of your admin portal URL. If the portal is
+at `https://acme.onelogin.com`, the subdomain is `acme`. The wrapper takes only
+the subdomain — no `https://`, no `.onelogin.com`, no path.
+
+## Wire the policy into the gateway
+
+Add the policy to `config/policies.json`:
+
+```json
+{
+  "name": "onelogin-managed-oauth",
+  "policyType": "mcp-onelogin-oauth-inbound",
+  "handler": {
+    "module": "$import(@zuplo/runtime/mcp-gateway)",
+    "export": "McpOneLoginOAuthInboundPolicy",
+    "options": {
+      "oneLoginSubdomain": "$env(ONELOGIN_SUBDOMAIN)",
+      "clientId": "$env(ONELOGIN_CLIENT_ID)",
+      "clientSecret": "$env(ONELOGIN_CLIENT_SECRET)"
+    }
+  }
+}
+```
+
+Attach the policy to each MCP route in `config/routes.oas.json` and register the
+gateway plugin in `modules/zuplo.runtime.ts` (see
+[Configuring Auth0](./configuring-auth0.mdx#wire-the-policy-into-the-gateway)
+for the route and plugin patterns — they're identical across all wrappers).
+
+## What the wrapper derives
+
+Given `oneLoginSubdomain: "acme"`:
+
+| Generic field           | Derived value                            |
+| ----------------------- | ---------------------------------------- |
+| `oidc.issuer`           | `https://acme.onelogin.com/oidc/2`       |
+| `oidc.jwksUrl`          | `https://acme.onelogin.com/oidc/2/certs` |
+| `browserLogin.url`      | `https://acme.onelogin.com/oidc/2/auth`  |
+| `browserLogin.tokenUrl` | `https://acme.onelogin.com/oidc/2/token` |
+
+These endpoint shapes follow OneLogin's OIDC provider configuration document at
+`https://{oneLoginSubdomain}.onelogin.com/oidc/2/.well-known/openid-configuration`.
+
+## Test the configuration
+
+The fastest sanity check is to connect an MCP client:
+
+1. Open Claude Desktop, Cursor, Claude Code, or another OAuth-aware MCP client.
+2. Add a remote MCP server pointing at one of your `/mcp/{slug}` routes.
+3. The client should redirect you to the OneLogin sign-in page. After login, the
+   gateway's consent screen renders. Approve it.
+4. The client receives an access token and can call `tools/list`.
+
+If something fails partway through, walk the flow manually using the
+[manual OAuth testing guide](./manual-oauth-testing.mdx) — it exercises every
+endpoint with `curl` so you can see the raw responses.
+
+## Common issues
+
+- **`oneLoginSubdomain` rejected at boot.** The value includes `https://`,
+  `.onelogin.com`, or a trailing path. Pass only the subdomain (`acme`).
+- **`invalid_request: redirect_uri`.** The redirect URI on the OIDC application
+  doesn't match `https://<gateway-host>/oauth/callback`.
+- **`invalid_client` from the token endpoint.** **Token Endpoint Authentication
+  Method** isn't set to **POST** on the application's SSO tab.
+
+## Related
+
+- [Authentication overview](./overview.mdx)
+- [Configuring a generic OIDC provider](./configuring-generic-oidc.mdx)
+- [Per-user OAuth to upstream MCP servers](./upstream-oauth.mdx)

package/docs/mcp-gateway/auth/configuring-ping.mdx

@@ -0,0 +1,157 @@
+---
+title: "Configuring PingOne"
+sidebar_label: "PingOne"
+description:
+  Configure PingOne to back the MCP Gateway's downstream OAuth using the
+  mcp-ping-oauth-inbound policy. Covers application setup and wiring the policy
+  in your gateway project.
+---
+
+The MCP Gateway can use PingOne as the identity provider behind its downstream
+OAuth flow. The `mcp-ping-oauth-inbound` policy is a PingOne-friendly wrapper
+around the generic `mcp-oauth-inbound` policy: provide a PingOne environment ID
+(or a custom domain), a client ID, and a client secret, and the policy derives
+the OIDC issuer, JWKS URL, and authorize and token URLs for you.
+
+This guide walks through the PingOne admin console setup, then wires the policy
+into a gateway project. Read the [authentication overview](./overview.mdx) first
+for the two-layer OAuth model.
+
+:::note
+
+This policy is for **PingOne cloud**. For **PingFederate** deployments — which
+can customize issuer hosts, issuer paths, and endpoint paths — use the generic
+[`mcp-oauth-inbound` policy](./configuring-generic-oidc.mdx) instead.
+
+:::
+
+## Set up PingOne
+
+The MCP Gateway acts as an OAuth 2.1 authorization server in front of PingOne.
+PingOne handles browser login; the gateway issues its own access tokens that
+bind to MCP routes.
+
+### Create an OIDC application
+
+1. In the PingOne admin console, switch to the environment the gateway should
+   use, then open **Applications → Applications**.
+2. Click **+ Add Application**, name it (for example, `Zuplo MCP Gateway`),
+   choose **OIDC Web App** as the application type, and click **Save**.
+3. Open the application's **Configuration** tab.
+4. Set **Redirect URIs** to `https://<gateway-host>/oauth/callback`. Add
+   `http://localhost:9000/oauth/callback` for local development.
+5. Set **Grant Types** to **Authorization Code**.
+6. Save.
+
+### Note the credentials
+
+Open the application's **Profile** tab. Copy the **Client ID** and **Client
+Secret**.
+
+### Find your environment ID and region
+
+Open **Settings → Environment** in the PingOne admin console. Copy the
+**Environment ID** (a UUID like `11111111-1111-4111-8111-111111111111`). Note
+the **Geography** of the environment — North America, Canada, Europe, Singapore,
+Australia, or Asia-Pacific. You'll pass these to the policy.
+
+### Optional: custom domain
+
+If your PingOne environment uses a custom domain (configured under **Settings →
+Domains**), copy the bare host (such as `login.example.com`) and use it instead
+of `environmentId` + `region`. The wrapper switches to the custom-domain
+endpoint shape when `customDomain` is set.
+
+## Wire the policy into the gateway
+
+Add the policy to `config/policies.json`:
+
+```json
+{
+  "name": "ping-managed-oauth",
+  "policyType": "mcp-ping-oauth-inbound",
+  "handler": {
+    "module": "$import(@zuplo/runtime/mcp-gateway)",
+    "export": "McpPingOAuthInboundPolicy",
+    "options": {
+      "environmentId": "$env(PING_ENVIRONMENT_ID)",
+      "region": "north-america",
+      "clientId": "$env(PING_CLIENT_ID)",
+      "clientSecret": "$env(PING_CLIENT_SECRET)"
+    }
+  }
+}
+```
+
+For a custom domain:
+
+```json
+{
+  "options": {
+    "customDomain": "$env(PING_CUSTOM_DOMAIN)",
+    "clientId": "$env(PING_CLIENT_ID)",
+    "clientSecret": "$env(PING_CLIENT_SECRET)"
+  }
+}
+```
+
+Attach the policy to each MCP route in `config/routes.oas.json` and register the
+gateway plugin in `modules/zuplo.runtime.ts` (see
+[Configuring Auth0](./configuring-auth0.mdx#wire-the-policy-into-the-gateway)
+for the route and plugin patterns — they're identical across all wrappers).
+
+## Available regions
+
+| `region` value  | PingOne auth host            |
+| --------------- | ---------------------------- |
+| `north-america` | `auth.pingone.com` (default) |
+| `canada`        | `auth.pingone.ca`            |
+| `europe`        | `auth.pingone.eu`            |
+| `singapore`     | `auth.pingone.sg`            |
+| `australia`     | `auth.pingone.com.au`        |
+| `asia-pacific`  | `auth.pingone.asia`          |
+
+## What the wrapper derives
+
+For the default region (`north-america`) and environment ID `ENV_ID`:
+
+| Generic field           | Derived value                                    |
+| ----------------------- | ------------------------------------------------ |
+| `oidc.issuer`           | `https://auth.pingone.com/{ENV_ID}/as`           |
+| `oidc.jwksUrl`          | `https://auth.pingone.com/{ENV_ID}/as/jwks`      |
+| `browserLogin.url`      | `https://auth.pingone.com/{ENV_ID}/as/authorize` |
+| `browserLogin.tokenUrl` | `https://auth.pingone.com/{ENV_ID}/as/token`     |
+
+With `customDomain` set, the host changes to your custom domain and the
+`{environmentId}` segment is removed.
+
+## Test the configuration
+
+The fastest sanity check is to connect an MCP client:
+
+1. Open Claude Desktop, Cursor, Claude Code, or another OAuth-aware MCP client.
+2. Add a remote MCP server pointing at one of your `/mcp/{slug}` routes.
+3. The client should redirect you to the PingOne sign-in page. After login, the
+   gateway's consent screen renders. Approve it.
+4. The client receives an access token and can call `tools/list`.
+
+If something fails partway through, walk the flow manually using the
+[manual OAuth testing guide](./manual-oauth-testing.mdx) — it exercises every
+endpoint with `curl` so you can see the raw responses.
+
+## Common issues
+
+- **`environmentId` rejected at boot.** The wrapper expects a UUID. Don't pass
+  the issuer URL, the auth domain, or the client ID.
+- **Browser login lands on a PingOne error page.** The redirect URI on the
+  application doesn't match `https://<gateway-host>/oauth/callback`.
+- **`invalid_client`.** The application is set to **Public** instead of
+  **Confidential**. Confidential is required so the gateway can authenticate
+  with the client secret.
+
+## Related
+
+- [Authentication overview](./overview.mdx)
+- [Configuring a generic OIDC provider](./configuring-generic-oidc.mdx) — use
+  this for PingFederate.
+- [Per-user OAuth to upstream MCP servers](./upstream-oauth.mdx)

package/docs/mcp-gateway/auth/configuring-workos.mdx

@@ -0,0 +1,117 @@
+---
+title: "Configuring WorkOS"
+sidebar_label: "WorkOS"
+description:
+  Configure WorkOS to back the MCP Gateway's downstream OAuth using the
+  mcp-workos-oauth-inbound policy. Covers AuthKit setup and wiring the policy in
+  your gateway project.
+---
+
+The MCP Gateway can use [WorkOS](https://workos.com/) as the identity provider
+behind its downstream OAuth flow. The `mcp-workos-oauth-inbound` policy is a
+WorkOS-friendly wrapper around the generic `mcp-oauth-inbound` policy: provide a
+WorkOS client ID and client secret and the policy derives the OIDC issuer, JWKS
+URL, and authorize and token URLs from the client ID.
+
+This guide walks through the WorkOS dashboard setup, then wires the policy into
+a gateway project. Read the [authentication overview](./overview.mdx) first for
+the two-layer OAuth model.
+
+## Set up WorkOS
+
+The MCP Gateway acts as an OAuth 2.1 authorization server in front of WorkOS
+AuthKit. WorkOS handles browser login; the gateway issues its own access tokens
+that bind to MCP routes.
+
+### Configure AuthKit
+
+1. In the WorkOS Dashboard, switch to the environment you want the gateway to
+   use, then open **Authentication → AuthKit**.
+2. If AuthKit isn't enabled yet, complete the AuthKit setup flow first — enable
+   email and password sign-in or any social connections your users need.
+
+### Add the redirect URI
+
+1. Open **Redirects** in the WorkOS Dashboard.
+2. Add `https://<gateway-host>/oauth/callback` as an allowed redirect URI. Add
+   `http://localhost:9000/oauth/callback` for local development with
+   `zuplo dev`.
+3. Save.
+
+### Note the API credentials
+
+Open **API Keys** in the WorkOS Dashboard. Copy the **Client ID** and the **API
+Key** (= client secret) for the environment you're using.
+
+## Wire the policy into the gateway
+
+Add the policy to `config/policies.json`:
+
+```json
+{
+  "name": "workos-managed-oauth",
+  "policyType": "mcp-workos-oauth-inbound",
+  "handler": {
+    "module": "$import(@zuplo/runtime/mcp-gateway)",
+    "export": "McpWorkosOAuthInboundPolicy",
+    "options": {
+      "clientId": "$env(WORKOS_CLIENT_ID)",
+      "clientSecret": "$env(WORKOS_CLIENT_SECRET)"
+    }
+  }
+}
+```
+
+Set the two environment variables in your project's environment configuration.
+The secret values belong in the project secret store.
+
+Attach the policy to each MCP route in `config/routes.oas.json` and register the
+gateway plugin in `modules/zuplo.runtime.ts` (see
+[Configuring Auth0](./configuring-auth0.mdx#wire-the-policy-into-the-gateway)
+for the route and plugin patterns — they're identical across all wrappers).
+
+## What the wrapper derives
+
+WorkOS keys its OIDC issuer by the client ID. Given a `clientId` like
+`client_01KC6057N3C66XJAXZ65YHAC72`, the wrapper derives:
+
+| Generic field           | Derived value                                         |
+| ----------------------- | ----------------------------------------------------- |
+| `oidc.issuer`           | `https://api.workos.com/user_management/{clientId}`   |
+| `oidc.jwksUrl`          | `https://api.workos.com/sso/jwks/{clientId}`          |
+| `browserLogin.url`      | `https://api.workos.com/user_management/authorize`    |
+| `browserLogin.tokenUrl` | `https://api.workos.com/user_management/authenticate` |
+
+These endpoint shapes come from WorkOS OIDC discovery at
+`https://api.workos.com/user_management/{clientId}/.well-known/openid-configuration`.
+
+## Test the configuration
+
+The fastest sanity check is to connect an MCP client:
+
+1. Open Claude Desktop, Cursor, Claude Code, or another OAuth-aware MCP client.
+2. Add a remote MCP server pointing at one of your `/mcp/{slug}` routes.
+3. The client should redirect you to the WorkOS AuthKit sign-in page. After
+   login, the gateway's consent screen renders. Approve it.
+4. The client receives an access token and can call `tools/list`.
+
+If something fails partway through, walk the flow manually using the
+[manual OAuth testing guide](./manual-oauth-testing.mdx) — it exercises every
+endpoint with `curl` so you can see the raw responses.
+
+## Common issues
+
+- **`Invalid redirect URI`.** The redirect URI on **Redirects** in the WorkOS
+  Dashboard doesn't match `https://<gateway-host>/oauth/callback` exactly.
+- **`invalid_client`.** The client secret value doesn't match. WorkOS shows the
+  secret only once after creation — regenerate it from **API Keys** if you've
+  lost it.
+- **JWKS fetch fails.** The client ID doesn't match the API key's environment.
+  Make sure both `clientId` and `clientSecret` come from the same WorkOS
+  environment.
+
+## Related
+
+- [Authentication overview](./overview.mdx)
+- [Configuring a generic OIDC provider](./configuring-generic-oidc.mdx)
+- [Per-user OAuth to upstream MCP servers](./upstream-oauth.mdx)