zuplo 7.8.0 → 7.8.1

package/docs/articles/accounts/enterprise-sso.mdx

@@ -48,6 +48,11 @@ This will open the Auth0 configuration window where you can make changes to your
 connection settings. This is useful if you need to rotate certificates or client
 secrets or if you need to add or remove domains.
 
+Client secrets and signing certificates expire, and an expired credential blocks
+sign-in for everyone on the connection. See
+[Renew SSO Credentials](./renew-sso-credentials.mdx) for how to rotate a
+credential, monitor expiry dates, and recover if a credential already expired.
+
 ### Disable Single Sign On
 
 If you need to disable SSO completely, contact Zuplo support for assistance.

package/docs/articles/accounts/renew-sso-credentials.mdx

@@ -0,0 +1,142 @@
+---
+title: Renew SSO Credentials
+sidebar_label: Renew SSO Credentials
+---
+
+<EnterpriseFeature name="Single Sign On" />
+
+Your SSO connection authenticates Zuplo to your identity provider with a
+credential that you create and own:
+
+- An OIDC or OAuth2 **client secret**, for connections that use OpenID Connect.
+- A **SAML signing certificate**, for connections that use SAML.
+
+Both kinds expire. When one expires, the identity provider stops accepting the
+sign-in request, and everyone who signs in to Zuplo through that connection is
+locked out until you replace the credential.
+
+Renewing the credential is your responsibility. Zuplo can't create a credential
+in your identity provider or extend the expiry date of an existing one.
+
+## Nothing reminds you automatically
+
+Most identity providers notify you about a narrower set of credentials than
+administrators expect:
+
+- **Microsoft Entra ID** sends automatic expiry email for SAML signing
+  certificates on enterprise applications. It doesn't send email about client
+  secrets on app registrations.
+- **Auth0**, which Zuplo uses to broker enterprise SSO, sends email about an
+  expiring SAML certificate on a connection. It doesn't send email about an
+  expiring OIDC client secret.
+
+If your connection uses a client secret, assume that no one notifies you. Record
+the expiry date when you create the secret and set your own reminder.
+
+## What an expired credential looks like
+
+Sign-in fails for every user on the connection, and the failure happens at your
+identity provider before the user returns to Zuplo. With Microsoft Entra ID, the
+error names the app registration:
+
+```
+The provided client secret keys for app '<app-id>' are expired.
+```
+
+Other providers word it differently. Look for `invalid_client` from an OIDC
+provider, or a message about an expired or untrusted certificate from a SAML
+provider.
+
+Two signals point at credential expiry rather than a configuration change:
+sign-in worked until a specific date, and the failure affects every user on the
+connection at once.
+
+## Renew a credential before it expires
+
+While you can still sign in to Zuplo, rotate the credential yourself:
+
+<Stepper>
+
+1. In your identity provider, create a new client secret or signing certificate
+   for the application that Zuplo connects to. Keep the old credential active
+   until the new one works.
+1. Open
+   [**Account Settings → Security**](https://portal.zuplo.com/+/account/settings/security)
+   in the Zuplo Portal and click "Edit Connection" in the "Single Sign On (SSO)"
+   section. See [Edit Single Sign On](./enterprise-sso.mdx#edit-single-sign-on)
+   for details.
+1. Enter the new client secret or upload the new certificate, then save the
+   connection.
+1. Sign out and sign back in to Zuplo to confirm the connection works.
+1. Remove the old credential from your identity provider.
+
+</Stepper>
+
+## Recover from a credential that has already expired
+
+:::caution
+
+If your account requires enterprise SSO, an expired credential locks out every
+user, including administrators. Nobody can reach **Account Settings → Security**
+to fix the connection, so this case isn't self-serve.
+
+:::
+
+<Stepper>
+
+1. In your identity provider, create a new client secret or signing certificate
+   for the application that Zuplo connects to.
+1. Email [support@zuplo.com](mailto:support@zuplo.com) and tell them that your
+   SSO credential expired. Zuplo can issue a self-service SSO link that lets you
+   update the connection without signing in to the Zuplo Portal.
+1. Open the link, enter the new credential, and save the connection. Make sure
+   the connection is still enabled.
+1. Sign in to Zuplo to confirm that the connection works.
+1. Remove the old credential from your identity provider.
+
+</Stepper>
+
+## Stay ahead of the next expiry
+
+- **Set a calendar reminder** for 30 days before the expiry date, on a shared
+  team calendar rather than one person's. Credential lifetimes outlast staff
+  changes.
+- **Choose a shorter lifetime**, such as six or twelve months, instead of the
+  longest one your provider offers. Frequent rotation keeps the procedure
+  familiar and documented, and a two-year secret usually expires long after
+  everyone who set it up has forgotten it exists.
+- **Prefer a certificate credential over a client secret** when your provider
+  supports it. Microsoft Entra ID treats certificates as the more secure
+  credential type for app registrations.
+- **Rotate with an overlap.** Most providers let you hold two active credentials
+  at once, so you can add the new one, switch Zuplo over, verify sign-in, and
+  then delete the old one without downtime.
+- **Monitor expiry dates** with the tools your provider gives you. The next
+  section links to them.
+
+## Provider documentation
+
+Each provider manages and monitors its own credentials. Use their documentation
+for the exact steps.
+
+**Microsoft Entra ID**
+
+- [Add and manage app credentials](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials)
+  — add a client secret or certificate to an app registration.
+- [Renew expiring application credentials recommendation](https://learn.microsoft.com/en-us/entra/identity/monitoring-health/recommendation-renew-expiring-application-credential)
+  — flags app-registration credentials that expire within the next 30 days.
+  Requires a Microsoft Entra Workload ID license.
+- [Export app registrations with expiring secrets and certificates](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/scripts/powershell-export-apps-with-expiring-secrets)
+  — a PowerShell sample that reports expiring credentials across your tenant.
+
+**Okta**
+
+- [Manage secrets and keys for OIDC app client authentication](https://help.okta.com/oie/en-us/content/topics/apps/oauth-client-cred-mgmt.htm)
+- [Manage signing certificates](https://help.okta.com/en-us/content/topics/apps/manage-signing-certificates.htm)
+
+**Google Workspace**
+
+- [Maintain SAML certificates](https://support.google.com/a/answer/7394709)
+
+For any other identity provider, look for the credential management page of the
+application you created for Zuplo.

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

@@ -68,6 +68,11 @@ On the same **Settings** tab:
    (plus `http://localhost:9000` for local dev).
 3. Save changes.
 
+For local development, use the same hostname in your MCP client URL, **Allowed
+Callback URLs**, and **Allowed Web Origins**. If your client uses `127.0.0.1`,
+replace `localhost` with `127.0.0.1` in both Auth0 settings. See
+[Local development](../code-config/local-development.mdx#use-one-loopback-origin-everywhere).
+
 ### Optional: Set an audience
 
 If you want Auth0 to issue identity-bound API access tokens (for example, to
@@ -112,6 +117,9 @@ Set the three environment variables in your Zuplo project's environment
 configuration. `AUTH0_DOMAIN` is the bare hostname; the secret values belong in
 the project secret store.
 
+Use the same variable names in your environment settings and the `$env(...)`
+references in `policies.json`.
+
 Attach the policy to each MCP route in `config/routes.oas.json`:
 
 ```jsonc

package/docs/mcp-gateway/auth/configuring-generic-oidc.mdx

@@ -55,7 +55,9 @@ at the same place:
    client", "confidential client" — terminology varies).
 2. Set the **redirect URI** to `https://<gateway-host>/__zuplo/oauth/callback`.
    Add `http://localhost:9000/__zuplo/oauth/callback` for local development with
-   `zuplo dev`.
+   `zuplo dev`. If your MCP client uses `127.0.0.1`, use that hostname in the
+   redirect URI too. See
+   [Local development](../code-config/local-development.mdx#use-one-loopback-origin-everywhere).
 3. Note the **client ID** and **client secret**.
 4. Restrict the application to the users or groups who should be able to
    authenticate against the gateway.
@@ -128,20 +130,20 @@ export function runtimeInit(runtime: RuntimeExtensions) {
 }
 ```
 
-One MCP OAuth policy serves every MCP route in the project. The gateway rejects
-projects that declare more than one MCP OAuth policy.
+Attach the same MCP OAuth policy to every MCP route. Attaching different OAuth
+policies causes a configuration error.
 
 ## Local development shortcut
 
-For local development without round-tripping a real IdP, set `browserLogin.url`
-to the loopback dev-login endpoint:
+To test locally without an identity provider, set `browserLogin.url` to the
+dev-login endpoint:
 
 ```json
 {
   "options": {
     "oidc": {
-      "issuer": "http://localhost:9000/",
-      "jwksUrl": "http://localhost:9000/dev/jwks"
+      "issuer": "http://127.0.0.1:9000",
+      "jwksUrl": "http://127.0.0.1:9000/jwks"
     },
     "browserLogin": {
       "url": "http://127.0.0.1:9000/__zuplo/oauth/dev-login"
@@ -154,6 +156,10 @@ When `browserLogin.url` points at `/__zuplo/oauth/dev-login`, you don't need
 `tokenUrl`, `clientId`, or `clientSecret`. The endpoint is only served on
 loopback origins; production deployments cannot reach it.
 
+The policy requires `oidc.issuer` and `oidc.jwksUrl`, but dev-login doesn't use
+them. These values are placeholders; the gateway doesn't serve `/jwks`. Use
+`127.0.0.1` in your MCP client URL to match this example.
+
 See the [local development guide](../code-config/local-development.mdx) for the
 rest of the local setup.
 

package/docs/mcp-gateway/auth/overview.mdx

@@ -160,10 +160,10 @@ connect-required error is returned — the proxy forwards transparently.
 
 ## Identity providers
 
-The gateway ships a generic OIDC policy plus first-class wrappers for the
-identity providers most teams use. You configure exactly one of these policies
-per project — the gateway rejects projects that declare more than one MCP OAuth
-policy.
+Use a provider-specific policy from the table, or the generic
+`mcp-oauth-inbound` policy for other OIDC providers. Attach the same policy to
+every MCP route in the project. Attaching different MCP OAuth policies causes a
+configuration error.
 
 Each wrapper has the same shape: it takes a small set of provider-specific
 fields (a domain, a tenant ID, a subdomain, and so on) plus `clientId` and

package/docs/mcp-gateway/auth/upstream-oauth.mdx

@@ -89,6 +89,18 @@ can request tokens. The `clientRegistration` option controls how:
   manages OAuth client lifecycle centrally, the upstream provider requires an
   approved client, or one OAuth client should be shared across multiple routes.
 
+Manual mode needs a redirect URI registered with the upstream provider. Register
+this URI, where `<connection-id>` is the connection's `id`:
+
+```text
+https://<gateway-host>/__zuplo/auth/connections/<connection-id>/callback
+```
+
+This is different from `/__zuplo/oauth/callback`, which is the callback for the
+identity provider that signs users in to the gateway itself. See
+[Upstream connection endpoints](../reference.mdx#upstream-connection-endpoints)
+in the MCP Gateway reference.
+
 Both modes are first-class. CIMD documents are accessible to the upstream
 provider over HTTPS — the upstream fetches them as part of its OAuth
 registration flow. The CIMD URL includes the `authProfileId` query parameter so

package/docs/mcp-gateway/code-config/local-development.mdx

@@ -2,61 +2,53 @@
 title: "Local development"
 sidebar_label: "Local development"
 description:
-  Run the Zuplo MCP Gateway locally with zuplo dev, bypass your identity
-  provider with the loopback /__zuplo/oauth/dev-login shortcut, wire up an MCP
-  client against 127.0.0.1, and recover cleanly from the known workerd restart
-  quirk.
+  Run the MCP Gateway locally, test OAuth without an identity provider, and
+  configure local callback URLs and environment variables for your MCP clients.
 ---
 
-The MCP Gateway runs the same way locally as any Zuplo project — `zuplo dev`,
-port `9000`, hot reload on file changes. A few details are specific to the
-gateway: the gateway prefers `127.0.0.1` over `localhost`, OAuth login can be
-short-circuited entirely in dev, and the local `workerd` worker needs a full
-restart after some MCP client connect attempts.
+Use `zuplo dev` to run the MCP Gateway locally on port `9000` with hot reload.
+For local testing, you can sign in without setting up an identity provider.
 
 ## Start the gateway
 
-From the project root:
+Start the development server from the project root:
 
 ```bash
 zuplo dev
 ```
 
-The gateway listens at `http://127.0.0.1:9000`. Each MCP route in
-`routes.oas.json` becomes reachable at that origin — for example
-`http://127.0.0.1:9000/mcp/linear-v1`.
+If the project has the standard `dev` script, `npm run dev` runs the same
+command.
 
-## Prefer `127.0.0.1` over `localhost`
+The gateway listens on port `9000`. Each MCP route in `routes.oas.json` becomes
+reachable there — for example `http://127.0.0.1:9000/mcp/linear-v1`.
 
-OAuth metadata, callback URLs, and the in-dev login shortcut all key off the
-request origin. Other loopback aliases (`localhost`, `::1`, `[::1]`) can cause
-subtle OAuth issues in local dev.
+## Use one loopback origin everywhere
 
-When configuring an MCP client locally, use `127.0.0.1`:
+Use either `http://localhost:9000` or `http://127.0.0.1:9000` consistently for
+local gateway URLs. The gateway treats them as different origins.
 
-```jsonc
-// Good
-"url": "http://127.0.0.1:9000/mcp/linear-v1"
+Use the same hostname in these settings:
 
-// Avoid in local dev — works for most things, breaks subtly for OAuth
-"url": "http://localhost:9000/mcp/linear-v1"
-```
+- The gateway URL in your MCP client configuration.
+- `browserLogin.url` when using the local dev-login endpoint.
+- The gateway callback and allowed-origin URLs registered with your identity
+  provider, when testing with one.
 
-The same applies to any callback or redirect URI you configure with an identity
-provider for local testing.
+Mixing hostnames can cause `oauth_callback_mismatch` during local login or a
+callback URL error from your identity provider. The examples on this page use
+`127.0.0.1`.
 
 ## Bypass your IdP with `/__zuplo/oauth/dev-login`
 
-Setting up a real OIDC provider for local development is friction — you'd have
-to register a localhost callback, manage test users, and so on. The gateway
-exposes a loopback-only shortcut that skips the IdP round-trip entirely and
-signs you in as a fixed `dev-browser-user` subject.
+The local `/__zuplo/oauth/dev-login` endpoint signs you in as `dev-browser-user`
+without an identity provider.
 
 To use it, set `browserLogin.url` to the dev-login URL when configuring the
 OAuth policy:
 
 ```jsonc
-// config/policies.json — using the generic mcp-oauth-inbound policy
+// config/policies.json
 {
   "name": "dev-oauth",
   "policyType": "mcp-oauth-inbound",
@@ -64,9 +56,10 @@ OAuth policy:
     "module": "$import(@zuplo/runtime/mcp-gateway)",
     "export": "McpOAuthInboundPolicy",
     "options": {
+      // Required placeholders for local dev-login.
       "oidc": {
         "issuer": "http://127.0.0.1:9000",
-        "jwksUrl": "http://127.0.0.1:9000/.well-known/jwks.json",
+        "jwksUrl": "http://127.0.0.1:9000/jwks",
       },
       "browserLogin": {
         "url": "http://127.0.0.1:9000/__zuplo/oauth/dev-login",
@@ -81,19 +74,55 @@ When `browserLogin.url` points at `/__zuplo/oauth/dev-login`, the
 `browserLogin.clientSecret` options aren't required. The consent page renders
 normally.
 
+The policy requires `oidc.issuer` and `oidc.jwksUrl`, but dev-login doesn't use
+them. Keep the placeholder values in this example for local testing. The `/jwks`
+URL is a placeholder, not an endpoint the gateway serves.
+
 :::caution
 
-The `/__zuplo/oauth/dev-login` route returns `403 Forbidden` for any request
-that doesn't arrive over loopback. It's not a security risk to leave configured
-for production, but it's also not useful — production deployments should use a
-real OIDC provider through one of the
-[IdP-specific wrappers](../auth/overview.mdx#identity-providers).
+Use an OIDC identity provider in deployed environments. The dev-login endpoint
+only accepts requests from loopback origins and returns `403 Forbidden` for
+other origins.
 
 :::
 
-A common pattern is keeping two OAuth policies in the project — one for
-production (Auth0, Okta, Entra, or any other supported IdP) and one for local
-dev — and selecting between them in `routes.oas.json` based on the environment.
+### Configure local and deployed environments
+
+Attach the same MCP OAuth policy to every MCP route. To use dev-login locally
+and an identity provider when deployed, configure a generic `mcp-oauth-inbound`
+policy with environment variables:
+
+```jsonc
+// config/policies.json
+"options": {
+  "oidc": {
+    "issuer": "$env(OIDC_ISSUER)",
+    "jwksUrl": "$env(OIDC_JWKS_URL)",
+  },
+  "browserLogin": {
+    "url": "$env(BROWSER_LOGIN_URL)",
+    "tokenUrl": "$env(BROWSER_LOGIN_TOKEN_URL)",
+    "clientId": "$env(BROWSER_LOGIN_CLIENT_ID)",
+    "clientSecret": "$env(BROWSER_LOGIN_CLIENT_SECRET)",
+  },
+},
+```
+
+For local development, set these values:
+
+```bash title=".env"
+OIDC_ISSUER=http://127.0.0.1:9000
+OIDC_JWKS_URL=http://127.0.0.1:9000/jwks
+BROWSER_LOGIN_URL=http://127.0.0.1:9000/__zuplo/oauth/dev-login
+```
+
+Leave `BROWSER_LOGIN_TOKEN_URL`, `BROWSER_LOGIN_CLIENT_ID`, and
+`BROWSER_LOGIN_CLIENT_SECRET` unset locally. In each deployed environment, set
+all six variables to your identity provider's values.
+
+Provider-specific policies such as `mcp-auth0-oauth-inbound` use the provider's
+login page and don't support dev-login. See
+[Define one OAuth policy](./overview.mdx#2-define-one-oauth-policy).
 
 ## Environment variables
 
@@ -115,6 +144,9 @@ AUTH0_AUDIENCE=https://mcp-gateway.example.com
 `.env` is read at `zuplo dev` startup. Restart the dev server after adding or
 changing an environment variable.
 
+Match your environment variable names to the `$env(...)` references in
+`policies.json`.
+
 Never commit `.env` to source control. Instead, check in a `.env.example` (or
 `env.example`) that documents which variables are required and an
 empty/placeholder value for each.

package/docs/mcp-gateway/code-config/overview.mdx

@@ -61,6 +61,9 @@ supported IdP. The Auth0 case looks like this:
 }
 ```
 
+Match your environment variable names to the `$env(...)` references in
+`policies.json`.
+
 Each wrapper takes a small set of provider-specific options (a domain, a tenant
 ID, a subdomain, and so on) and derives the OIDC URLs from them. For IdPs
 without a dedicated wrapper — Ory Hydra, Authentik, FusionAuth, PingFederate, a
@@ -70,10 +73,8 @@ the worked example.
 
 :::caution
 
-A project can have only one MCP OAuth policy. The gateway rejects any
-configuration with two, regardless of variant. The same policy is attached to
-every MCP route in the project — every route authenticates against the same
-identity provider.
+Attach the same MCP OAuth policy to every MCP route in the project. Attaching
+different OAuth policies causes a configuration error.
 
 :::
 
@@ -157,9 +158,8 @@ gateway returns a configuration error on the first matching request.
 
 ## Verify the gateway is wired up
 
-Start the project with `zuplo dev` and the gateway is reachable at
-`http://127.0.0.1:9000/mcp/linear-v1`. A quick sanity check is to send an
-unauthenticated POST:
+Start the project with `zuplo dev`, or `npm run dev` if the project's `dev`
+script runs that command. Then send an unauthenticated request to the route:
 
 ```bash
 curl -i -X POST http://127.0.0.1:9000/mcp/linear-v1 \
@@ -176,7 +176,7 @@ skips your IdP during development.
 ## Add more upstreams
 
 The pattern is the same for each additional upstream: one MCP OAuth policy stays
-shared across the project, and one `mcp-token-exchange-*` policy and one route
+attached across the project, and one `mcp-token-exchange-*` policy and one route
 get added per new upstream MCP server. Per-user state is keyed by
 `(subjectId, upstreamServerId)`, so each user maintains independent connections
 to each upstream they consent to.

package/docs/mcp-gateway/how-to/connect-upstream-oauth.mdx

@@ -90,6 +90,20 @@ upstream OAuth provider:
 
 Use `$env(...)` for `clientSecret` so the secret stays out of source control.
 
+When you register the OAuth app with the upstream provider, register this
+redirect URI, where `<connection-id>` is the policy's `id` (for the example
+policy above, `linear`, inferred from the `mcp-token-exchange-linear` name):
+
+```text
+https://<gateway-host>/__zuplo/auth/connections/<connection-id>/callback
+```
+
+This is different from `/__zuplo/oauth/callback`, which is the callback for the
+identity provider that signs users in to the gateway itself. Registering that
+path with the upstream provider fails with `redirect_uri_mismatch`. Both paths
+are listed in the
+[MCP Gateway reference](../reference.mdx#upstream-connection-endpoints).
+
 ## Set scopes when the upstream needs them
 
 When the upstream requires specific scopes that aren't discoverable from MCP

package/docs/mcp-gateway/quickstart-local.mdx

@@ -70,10 +70,8 @@ older project and the build complains about the compatibility date, see
 
 2. **Add an OAuth policy with the dev-login shortcut**
 
-   Setting up a real identity provider for local development is friction. You'd
-   register a loopback callback, manage test users, and so on. The gateway
-   exposes a loopback-only shortcut that skips the IdP round-trip entirely and
-   signs you in as a fixed `dev-browser-user`.
+   The local dev-login endpoint signs you in as `dev-browser-user` without an
+   identity provider.
 
    Open `config/policies.json` and add the generic OAuth policy pointed at the
    dev-login URL:
@@ -88,7 +86,7 @@ older project and the build complains about the compatibility date, see
        "options": {
          "oidc": {
            "issuer": "http://127.0.0.1:9000",
-           "jwksUrl": "http://127.0.0.1:9000/.well-known/jwks.json"
+           "jwksUrl": "http://127.0.0.1:9000/jwks"
          },
          "browserLogin": {
            "url": "http://127.0.0.1:9000/__zuplo/oauth/dev-login"
@@ -98,32 +96,20 @@ older project and the build complains about the compatibility date, see
    }
    ```
 
+   The policy requires `oidc.issuer` and `oidc.jwksUrl`, but dev-login doesn't
+   use them. Keep these placeholder values for this tutorial; the gateway
+   doesn't serve `/jwks`.
+
    :::caution
 
-   `/__zuplo/oauth/dev-login` returns `403 Forbidden` for any request that
-   doesn't arrive over loopback, so it's safe to leave configured, but only
-   useful in local dev. Production deployments should use a real OIDC provider
-   through one of the [IdP wrappers](./auth/overview.mdx#identity-providers). A
-   common pattern is keeping two OAuth policies (one for production, one for
-   dev) and selecting between them in `routes.oas.json` by environment.
+   Before deploying, configure an OIDC identity provider. The dev-login endpoint
+   only accepts requests from loopback origins and returns `403 Forbidden` for
+   other origins. See
+   [Configure local and deployed environments](./code-config/local-development.mdx#configure-local-and-deployed-environments)
+   to use one policy with different environment variables for each environment.
 
    :::
 
-   When you do switch to a real provider, its policy reads credentials from
-   `$env(...)` references. Define those values in a `.env` file at the project
-   root:
-
-   ```bash title=".env"
-   MCP_AUTH0_DOMAIN=your-tenant.us.auth0.com
-   MCP_AUTH0_CLIENT_ID=your-auth0-web-app-client-id
-   MCP_AUTH0_CLIENT_SECRET=your-auth0-web-app-client-secret
-   ```
-
-   `.env` is read when `npm run dev` starts, so restart the dev server after
-   adding or changing a variable. Never commit `.env`. Check in a `.env.example`
-   with placeholder values instead. The dev-login shortcut above needs no
-   environment variables, so you can skip this until you wire up a provider.
-
 3. **Add a token-exchange policy for the upstream**
 
    Each OAuth-protected upstream gets its own `mcp-token-exchange-inbound`
@@ -200,6 +186,8 @@ older project and the build complains about the compatibility date, see
    npm run dev
    ```
 
+   The project's `dev` script runs `zuplo dev`.
+
    The route is now reachable at `http://127.0.0.1:9000/mcp/linear-v1`.
 
    :::tip{title="Checkpoint: confirm the OAuth policy is wired up"}
@@ -219,12 +207,12 @@ older project and the build complains about the compatibility date, see
 
    :::
 
-   :::caution{title="Use 127.0.0.1, not localhost"}
+   :::caution{title="Use the same hostname for local URLs"}
 
-   OAuth metadata and callback URLs key off the request origin. Other loopback
-   aliases (`localhost`, `::1`) can break OAuth subtly in local dev. See
-   [Local development](./code-config/local-development.mdx) for the full set of
-   local-only details, including the known `workerd` restart quirk.
+   Use `127.0.0.1` in your MCP client URL to match the policy in this tutorial.
+   You can use `localhost` instead, but update both URLs to avoid a callback
+   mismatch. See
+   [Local development](./code-config/local-development.mdx#use-one-loopback-origin-everywhere).
 
    :::
 

package/docs/mcp-gateway/quickstart.mdx

@@ -124,15 +124,12 @@ result on your machine.
 
 5. **Configure upstream authentication**
 
-   The **Outbound Auth** step controls whether the gateway needs upstream
-   credentials before forwarding MCP requests. Linear requires OAuth, so choose:
-   - **User OAuth**: exchange each user's gateway grant for an upstream MCP
-     grant, so every user connects their own Linear account.
-   - **Dynamic** OAuth client registration: the gateway registers itself with
-     Linear's OAuth server on demand, so no upstream client credentials are
-     needed.
+   On **Outbound Auth**, leave **User OAuth** selected so each user connects
+   their own Linear account. Click **Next**.
 
-   Both are the defaults. Click **Finish**.
+   Leave **OAuth client registration** set to **Dynamic**. The gateway registers
+   with Linear automatically, so you don't need a Linear client ID or secret.
+   Click **Finish**.
 
    <ModalScreenshot size="md">
 
@@ -153,29 +150,32 @@ result on your machine.
 
 6. **Set your identity provider's environment variables**
 
-   The scaffolded inbound auth policy reads your provider's credentials from
-   environment variables, so set those before testing. Open your project's
-   **Settings** from the navigation bar, then click **Environment Variables**
-   under Project Settings.
+   In `config/policies.json`, set the Auth0 policy's environment variable
+   references to match these names, then save the file:
+
+   ```json title="Auth0 policy options"
+   {
+     "auth0Domain": "$env(AUTH0_DOMAIN)",
+     "clientId": "$env(AUTH0_CLIENT_ID)",
+     "clientSecret": "$env(AUTH0_CLIENT_SECRET)"
+   }
+   ```
+
+   Open your project's **Settings** from the navigation bar, then click
+   **Environment Variables** under Project Settings.
 
    Add one variable per credential. For the Auth0 example:
 
-   | Name                      | Value                      | Secret? |
-   | ------------------------- | -------------------------- | ------- |
-   | `MCP_AUTH0_DOMAIN`        | `your-tenant.us.auth0.com` | No      |
-   | `MCP_AUTH0_CLIENT_ID`     | your application client ID | Yes     |
-   | `MCP_AUTH0_CLIENT_SECRET` | your application secret    | Yes     |
+   | Name                  | Value                      | Secret? |
+   | --------------------- | -------------------------- | ------- |
+   | `AUTH0_DOMAIN`        | `your-tenant.us.auth0.com` | No      |
+   | `AUTH0_CLIENT_ID`     | your application client ID | Yes     |
+   | `AUTH0_CLIENT_SECRET` | your application secret    | Yes     |
 
    Check the **Secret** box for the client ID and secret so their values are
-   hidden in the encrypted secret store. `MCP_AUTH0_DOMAIN` isn't sensitive, so
+   hidden in the encrypted secret store. `AUTH0_DOMAIN` isn't sensitive, so
    leave it unchecked. Click **Save** for each.
 
-   <ModalScreenshot size="md">
-
-   ![The three MCP_AUTH0 environment variables in project settings](../../public/media/mcp-gateway-quickstart/06-env-vars.png)
-
-   </ModalScreenshot>
-
    :::note
 
    A new deployment is needed for environment variable changes to take effect.
@@ -184,7 +184,7 @@ result on your machine.
 
    :::caution
 
-   `MCP_AUTH0_DOMAIN` is a bare hostname (`my-tenant.us.auth0.com`), not a URL.
+   `AUTH0_DOMAIN` is a bare hostname (`my-tenant.us.auth0.com`), not a URL.
 
    :::
 

package/docs/policies/mcp-token-exchange-inbound/doc.md

@@ -108,51 +108,73 @@ as Entra tenant admin consent. If connections start requiring frequent
 reauthorization after setting `prompt: false`, remove the option so the consent
 grant is requested again.
 
-## Authorization Server Issuer Mismatch
+## OAuth Metadata Validation
 
-Some providers publish inconsistent OAuth metadata: the protected-resource
-document advertises a path-scoped authorization server, but that server's own
-metadata reports a different (usually root-origin) `issuer`. ServiceNow is one —
-its protected-resource metadata names
-`https://<instance>.service-now.com/sncapps/...` while the metadata served there
-reports `https://<instance>.service-now.com`. Atlassian and Okta
-org-versus-custom authorization servers publish the same shape.
+The gateway checks OAuth metadata before connecting to an upstream. If a
+provider publishes metadata that does not match its URLs, you can skip either of
+the checks below for that connection.
 
-RFC 8414 section 3.3 requires a client to reject a metadata document whose
-`issuer` differs from the identifier the well-known URL was built from, so the
-gateway hard-fails discovery against these providers. Set
-`skipIssuerMetadataValidation` to `true` on that connection to proceed anyway:
+Both options default to `false` and support `user-oauth` and `shared-oauth`.
+They are not available with `id-jag`. Leave them disabled unless you have
+confirmed the mismatch with the provider and trust its metadata and endpoints.
+Enable only the option needed for that mismatch.
+
+### Authorization Server Issuer Mismatch
+
+`skipIssuerMetadataValidation` allows the authorization server's metadata to
+report an `issuer` that differs from the server URL used to discover it.
+
+For example, the upstream might advertise `https://auth.example.com/team` as its
+authorization server, while that server's metadata reports
+`https://auth.example.com` as its `issuer`. By default, the gateway rejects this
+mismatch. To allow it, set the following policy options:
 
 ```json
 {
-  "name": "mcp-token-exchange-servicenow",
-  "policyType": "mcp-token-exchange-inbound",
-  "handler": {
-    "module": "$import(@zuplo/runtime/mcp-gateway)",
-    "export": "McpTokenExchangeInboundPolicy",
-    "options": {
-      "displayName": "ServiceNow",
-      "authMode": "user-oauth",
-      "skipIssuerMetadataValidation": true
-    }
-  }
+  "displayName": "Acme",
+  "authMode": "user-oauth",
+  "skipIssuerMetadataValidation": true
+}
+```
+
+This disables the issuer check required by RFC 8414 section 3.3. The gateway
+accepts the metadata's OAuth endpoints without checking that the document's
+issuer matches the expected authorization server. Only use it after verifying
+that the metadata and endpoints belong to the provider you intend to use.
+Authorization-response issuer validation and the check that the callback uses
+the same authorization server remain enabled.
+
+### Resource Indicator Mismatch
+
+`skipResourceIndicatorValidation` allows the `resource` in the upstream's
+protected-resource metadata to differ from the upstream URL configured in the
+route handler's `rewritePattern`.
+
+By default, the resource URL must have the same origin (scheme, host, and port)
+as the upstream URL. Its path must also match the upstream path or be a parent
+of it. For example, `https://api.example.com` is valid for an upstream at
+`https://api.example.com/mcp`, but `https://api.example.com/other` is not.
+
+A provider might expose its MCP server at `https://mcp.example.com/mcp` but
+advertise `https://api.example.com/mcp` as its resource. If the provider
+confirms that both URLs identify the same service, set the following policy
+options:
+
+```json
+{
+  "displayName": "Acme",
+  "authMode": "user-oauth",
+  "skipResourceIndicatorValidation": true
 }
 ```
 
-**Warning**: this puts the connection out of spec. The issuer check is an
-unqualified MUST in both RFC 8414 section 3.3 and the MCP authorization spec,
-whose own example is the attack it prevents — a document served from
-`https://attacker.example/.well-known/oauth-authorization-server` claiming
-`"issuer": "https://honest.example"` must be rejected. The check binds the
-metadata to the TLS-authenticated host it came from, and with it off the gateway
-trusts the authorization, token and JWKS endpoints from a document that never
-proved it speaks for that issuer.
-
-Only enable it for a specific upstream known to publish a mismatched issuer, and
-only when the metadata URL's host is itself trusted. Never enable it as a
-default. It relaxes the discovery-time check only: the RFC 9207
-authorization-response check and the callback-leg authorization-server binding
-still apply.
+The gateway still sends the advertised `resource` on OAuth authorization and
+token requests. It skips only the comparison with the configured upstream URL.
+If the advertised resource identifies another service, the gateway could receive
+a token intended for that service and forward it to this upstream. Only enable
+this option when you trust the upstream to receive the resulting token. Issuer
+metadata validation remains enabled unless you also set
+`skipIssuerMetadataValidation`.
 
 ## ID-JAG Token Exchange (Cross-App Access)
 
@@ -174,8 +196,9 @@ Use this mode in enterprise deployments where the gateway and the upstream trust
 the same identity provider (for example, Okta Cross-App Access), so upstream
 access follows the caller's identity without a per-user upstream consent flow.
 The `user-oauth`/`shared-oauth` options — `scopes`, `scopeDelimiter`, `prompt`,
-`skipIssuerMetadataValidation`, and `clientRegistration` — do not apply; the
-`id-jag` mode is configured entirely through the `idJag` option.
+`skipIssuerMetadataValidation`, `skipResourceIndicatorValidation`, and
+`clientRegistration` — do not apply; the `id-jag` mode is configured entirely
+through the `idJag` option.
 
 ```json
 {

package/docs/policies/mcp-token-exchange-inbound/schema.json

@@ -59,6 +59,9 @@
                 {
                   "required": ["skipIssuerMetadataValidation"]
                 },
+                {
+                  "required": ["skipResourceIndicatorValidation"]
+                },
                 {
                   "required": ["clientRegistration"]
                 }
@@ -126,7 +129,12 @@
             "skipIssuerMetadataValidation": {
               "type": "boolean",
               "x-advanced": true,
-              "description": "Skips the RFC 8414 section 3.3 issuer-echo check when discovering the upstream authorization server. That check requires the `issuer` in the authorization server's metadata to equal the `authorization_servers` entry the protected-resource metadata advertised. Some providers publish a path-scoped authorization server whose metadata reports the root origin instead — for example ServiceNow advertises `https://<instance>.service-now.com/sncapps/...` but its metadata reports `https://<instance>.service-now.com` — so discovery hard-fails without this option. Warning: enabling this puts the connection out of spec. The check is an unqualified MUST in both RFC 8414 section 3.3 and the MCP authorization spec, which require rejecting a metadata document whose `issuer` differs from the identifier the well-known URL was built from; the spec's own example is a document served from `https://attacker.example/.well-known/oauth-authorization-server` claiming `\"issuer\": \"https://honest.example\"`. The echo check binds the metadata to the TLS-authenticated host it came from, and with it off the gateway trusts the authorization, token and JWKS endpoints from a document that never proved it speaks for that issuer. Only enable it for a specific upstream known to publish a mismatched issuer, and only when the metadata URL's host is itself trusted. It relaxes the discovery-time check only — the RFC 9207 authorization-response check and the callback-leg authorization-server binding still apply."
+              "description": "Allows the authorization server metadata's `issuer` to differ from the server URL used for discovery. Defaults to `false`. Enable only for a confirmed provider metadata mismatch after verifying that its metadata and OAuth endpoints are trusted. This disables the RFC 8414 section 3.3 issuer check; authorization-response and callback checks still apply. Available only with `user-oauth` and `shared-oauth`."
+            },
+            "skipResourceIndicatorValidation": {
+              "type": "boolean",
+              "x-advanced": true,
+              "description": "Allows the upstream metadata's `resource` URL to have a different origin or path from the configured upstream URL. Defaults to `false`. The gateway still sends the advertised `resource` on OAuth requests. Enable only for a confirmed provider metadata mismatch: a token intended for another service could otherwise be sent to this upstream. Available only with `user-oauth` and `shared-oauth`."
             },
             "clientRegistration": {
               "x-advanced": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.8.0",
+  "version": "7.8.1",
   "type": "module",
   "description": "The official Zuplo CLI for local development and platform management",
   "homepage": "https://zuplo.com/docs/cli/overview",
@@ -32,9 +32,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "7.8.0",
-    "@zuplo/core": "7.8.0",
-    "@zuplo/runtime": "7.8.0",
-    "@zuplo/test": "7.8.0"
+    "@zuplo/cli": "7.8.1",
+    "@zuplo/core": "7.8.1",
+    "@zuplo/runtime": "7.8.1",
+    "@zuplo/test": "7.8.1"
   }
 }