zuplo 6.72.2 → 6.72.7

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

@@ -4,10 +4,11 @@ The `mcp-token-exchange-inbound` policy resolves gateway-managed upstream MCP
 credentials and applies them to the request before the normal Zuplo route
 handler forwards it.
 
-Use this policy only when Zuplo manages upstream OAuth credentials, such as
-per-user OAuth or shared OAuth. If the upstream is public, uses an API key
-header, or only needs static routing/context headers, omit this policy and
-compose the existing Zuplo header/auth policies instead.
+Use this policy only when Zuplo manages upstream credentials: per-user OAuth
+(`user-oauth`), a gateway-wide shared OAuth grant (`shared-oauth`), or ID-JAG
+token exchange (`id-jag`). If the upstream is public, uses an API key header, or
+only needs static routing/context headers, omit this policy and compose the
+existing Zuplo header/auth policies instead.
 
 Zuplo is only the gateway. It discovers the upstream MCP server, sends users
 through the upstream OAuth flow, stores the resulting upstream connection, and
@@ -107,6 +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.
 
+## ID-JAG Token Exchange (Cross-App Access)
+
+Set `authMode` to `id-jag` when the upstream is protected by an Identity
+Assertion JWT Authorization Grant (ID-JAG) Resource Authorization Server, the
+pattern also known as Cross-App Access (XAA). Instead of sending users through
+the upstream's browser OAuth flow, the gateway obtains the upstream credential
+in two server-to-server steps:
+
+1. **IdP token exchange**: the gateway exchanges the caller's identity assertion
+   at the configured identity provider's token endpoint for an ID-JAG, sending
+   the configured `audience` (the Resource Authorization Server) and `resource`
+   (the upstream MCP server).
+2. **Resource AS redemption**: the gateway redeems the ID-JAG at the upstream
+   Resource Authorization Server's token endpoint using the `jwt-bearer` grant
+   and receives the upstream access token it attaches to the forwarded request.
+
+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`, and `clientRegistration` — do not apply; the
+`id-jag` mode is configured entirely through the `idJag` option.
+
+```json
+{
+  "name": "mcp-token-exchange-acme",
+  "policyType": "mcp-token-exchange-inbound",
+  "handler": {
+    "module": "$import(@zuplo/runtime/mcp-gateway)",
+    "export": "McpTokenExchangeInboundPolicy",
+    "options": {
+      "displayName": "Acme",
+      "authMode": "id-jag",
+      "idJag": {
+        "scopes": ["mcp:tools"],
+        "idp": {
+          "tokenUrl": "https://idp.example.com/oauth2/token",
+          "clientAuth": {
+            "method": "client_secret_post",
+            "clientId": "gateway-client",
+            "clientSecret": "$env(IDP_CLIENT_SECRET)"
+          }
+        },
+        "resourceAs": {
+          "tokenUrl": "https://auth.acme-mcp.example.com/oauth2/token",
+          "audience": "https://auth.acme-mcp.example.com",
+          "resource": "https://mcp.acme.example.com/mcp",
+          "clientAuth": {
+            "method": "client_secret_post",
+            "clientId": "gateway-resource-client",
+            "clientSecret": "$env(RESOURCE_AS_CLIENT_SECRET)"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Both `clientAuth` blocks also accept `client_secret_basic` and
+`private_key_jwt`. Use `private_key_jwt` for providers such as Okta that
+require a signed client assertion for token exchange; it takes `privateKeyPem`,
+an optional `keyId`, and an `algorithm` (default `RS256`). Source secrets and
+private keys from environment variables with `$env(VAR_NAME)`. When `resource`
+is omitted, the gateway defaults it to the upstream MCP server URL from the
+route handler's `rewritePattern`.
+
 ## Route Shape
 
 Publish both MCP transport methods as one Zuplo multi-method operation using

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

@@ -1,6 +1,7 @@
 Resolve gateway-managed upstream MCP credentials and apply them to the request.
 
-Use this after gateway auth when the upstream requires Zuplo-managed OAuth. Omit
-it for public upstreams or upstreams handled by ordinary Zuplo header/API-key
-policies. The route should use `McpProxyHandler` with the upstream URL
-configured on the handler.
+Use this after gateway auth when the upstream requires Zuplo-managed
+credentials: per-user OAuth, shared OAuth, or ID-JAG (Cross-App Access) token
+exchange. Omit it for public upstreams or upstreams handled by ordinary Zuplo
+header/API-key policies. The route should use `McpProxyHandler` with the
+upstream URL configured on the handler.

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

@@ -34,6 +34,38 @@
           "description": "The options for this policy.",
           "additionalProperties": false,
           "required": ["displayName", "authMode"],
+          "if": {
+            "properties": {
+              "authMode": {
+                "const": "id-jag"
+              }
+            },
+            "required": ["authMode"]
+          },
+          "then": {
+            "required": ["idJag"],
+            "not": {
+              "anyOf": [
+                {
+                  "required": ["scopes"]
+                },
+                {
+                  "required": ["scopeDelimiter"]
+                },
+                {
+                  "required": ["prompt"]
+                },
+                {
+                  "required": ["clientRegistration"]
+                }
+              ]
+            }
+          },
+          "else": {
+            "not": {
+              "required": ["idJag"]
+            }
+          },
           "properties": {
             "id": {
               "type": "string",
@@ -57,8 +89,8 @@
             },
             "authMode": {
               "type": "string",
-              "enum": ["user-oauth", "shared-oauth"],
-              "description": "Authentication mode. `user-oauth` performs per-user OAuth federation; `shared-oauth` uses a gateway-wide OAuth grant."
+              "enum": ["user-oauth", "shared-oauth", "id-jag"],
+              "description": "Authentication mode. `user-oauth` performs per-user OAuth federation; `shared-oauth` uses a gateway-wide OAuth grant; `id-jag` exchanges the caller's identity assertion at the configured IdP for an ID-JAG (Identity Assertion JWT Authorization Grant, also known as Cross-App Access / XAA), then redeems it at the upstream Resource Authorization Server for an upstream access token."
             },
             "scopes": {
               "type": "array",
@@ -126,6 +158,243 @@
                   }
                 }
               ]
+            },
+            "idJag": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["idp", "resourceAs"],
+              "description": "ID-JAG (Cross-App Access / XAA) token-exchange configuration. Required when `authMode` is `id-jag`; not used by the OAuth modes.",
+              "properties": {
+                "scopes": {
+                  "type": "array",
+                  "default": [],
+                  "description": "Scopes to request on the ID-JAG token exchange at the IdP.",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "scopeDelimiter": {
+                  "type": "string",
+                  "default": " ",
+                  "description": "Delimiter used to join scopes in the token-exchange request. Defaults to a single space."
+                },
+                "idp": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["tokenUrl", "clientAuth"],
+                  "description": "The identity provider that exchanges the caller's identity assertion for an ID-JAG.",
+                  "properties": {
+                    "tokenUrl": {
+                      "type": "string",
+                      "format": "uri",
+                      "description": "The IdP token endpoint used for the ID-JAG token exchange."
+                    },
+                    "clientAuth": {
+                      "description": "Client authentication used at the token endpoint.",
+                      "oneOf": [
+                        {
+                          "type": "object",
+                          "additionalProperties": false,
+                          "required": ["method", "clientId", "clientSecret"],
+                          "properties": {
+                            "method": {
+                              "type": "string",
+                              "const": "client_secret_post"
+                            },
+                            "clientId": {
+                              "type": "string"
+                            },
+                            "clientSecret": {
+                              "type": "string",
+                              "examples": ["$env(IDP_CLIENT_SECRET)"],
+                              "description": "OAuth client secret. Use `$env(VAR_NAME)` to source from an environment variable."
+                            }
+                          }
+                        },
+                        {
+                          "type": "object",
+                          "additionalProperties": false,
+                          "required": ["method", "clientId", "clientSecret"],
+                          "properties": {
+                            "method": {
+                              "type": "string",
+                              "const": "client_secret_basic"
+                            },
+                            "clientId": {
+                              "type": "string"
+                            },
+                            "clientSecret": {
+                              "type": "string",
+                              "examples": ["$env(IDP_CLIENT_SECRET)"],
+                              "description": "OAuth client secret. Use `$env(VAR_NAME)` to source from an environment variable."
+                            }
+                          }
+                        },
+                        {
+                          "type": "object",
+                          "additionalProperties": false,
+                          "required": ["method", "clientId", "privateKeyPem"],
+                          "properties": {
+                            "method": {
+                              "type": "string",
+                              "const": "private_key_jwt"
+                            },
+                            "clientId": {
+                              "type": "string"
+                            },
+                            "privateKeyPem": {
+                              "type": "string",
+                              "examples": ["$env(IDP_PRIVATE_KEY_PEM)"],
+                              "description": "PEM-encoded private key used to sign the client assertion. Use `$env(VAR_NAME)` to source from an environment variable."
+                            },
+                            "algorithm": {
+                              "type": "string",
+                              "enum": [
+                                "RS256",
+                                "RS384",
+                                "RS512",
+                                "ES256",
+                                "ES384",
+                                "ES512"
+                              ],
+                              "default": "RS256",
+                              "description": "JWS algorithm used to sign the client assertion."
+                            },
+                            "keyId": {
+                              "type": "string",
+                              "description": "Optional `kid` header set on the client assertion, for providers that select the verification key by key id."
+                            },
+                            "audience": {
+                              "type": "string",
+                              "format": "uri",
+                              "description": "Optional override for the client assertion `aud` claim. Defaults to the token endpoint URL."
+                            },
+                            "expiresInSeconds": {
+                              "type": "integer",
+                              "default": 300,
+                              "minimum": 1,
+                              "maximum": 3600,
+                              "description": "Client assertion lifetime in seconds."
+                            }
+                          }
+                        }
+                      ]
+                    }
+                  }
+                },
+                "resourceAs": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["tokenUrl", "audience", "clientAuth"],
+                  "description": "The upstream Resource Authorization Server that redeems the ID-JAG for an upstream access token.",
+                  "properties": {
+                    "tokenUrl": {
+                      "type": "string",
+                      "format": "uri",
+                      "description": "The Resource Authorization Server token endpoint where the gateway redeems the ID-JAG via the jwt-bearer grant."
+                    },
+                    "audience": {
+                      "type": "string",
+                      "description": "The `audience` value sent on the ID-JAG token exchange, identifying the Resource Authorization Server (typically its issuer)."
+                    },
+                    "resource": {
+                      "type": "string",
+                      "description": "Optional `resource` indicator sent on the token exchange, identifying the upstream MCP resource. Defaults to the upstream MCP server URL from the route handler's rewritePattern."
+                    },
+                    "clientAuth": {
+                      "description": "Client authentication used at the token endpoint.",
+                      "oneOf": [
+                        {
+                          "type": "object",
+                          "additionalProperties": false,
+                          "required": ["method", "clientId", "clientSecret"],
+                          "properties": {
+                            "method": {
+                              "type": "string",
+                              "const": "client_secret_post"
+                            },
+                            "clientId": {
+                              "type": "string"
+                            },
+                            "clientSecret": {
+                              "type": "string",
+                              "examples": ["$env(IDP_CLIENT_SECRET)"],
+                              "description": "OAuth client secret. Use `$env(VAR_NAME)` to source from an environment variable."
+                            }
+                          }
+                        },
+                        {
+                          "type": "object",
+                          "additionalProperties": false,
+                          "required": ["method", "clientId", "clientSecret"],
+                          "properties": {
+                            "method": {
+                              "type": "string",
+                              "const": "client_secret_basic"
+                            },
+                            "clientId": {
+                              "type": "string"
+                            },
+                            "clientSecret": {
+                              "type": "string",
+                              "examples": ["$env(IDP_CLIENT_SECRET)"],
+                              "description": "OAuth client secret. Use `$env(VAR_NAME)` to source from an environment variable."
+                            }
+                          }
+                        },
+                        {
+                          "type": "object",
+                          "additionalProperties": false,
+                          "required": ["method", "clientId", "privateKeyPem"],
+                          "properties": {
+                            "method": {
+                              "type": "string",
+                              "const": "private_key_jwt"
+                            },
+                            "clientId": {
+                              "type": "string"
+                            },
+                            "privateKeyPem": {
+                              "type": "string",
+                              "examples": ["$env(IDP_PRIVATE_KEY_PEM)"],
+                              "description": "PEM-encoded private key used to sign the client assertion. Use `$env(VAR_NAME)` to source from an environment variable."
+                            },
+                            "algorithm": {
+                              "type": "string",
+                              "enum": [
+                                "RS256",
+                                "RS384",
+                                "RS512",
+                                "ES256",
+                                "ES384",
+                                "ES512"
+                              ],
+                              "default": "RS256",
+                              "description": "JWS algorithm used to sign the client assertion."
+                            },
+                            "keyId": {
+                              "type": "string",
+                              "description": "Optional `kid` header set on the client assertion, for providers that select the verification key by key id."
+                            },
+                            "audience": {
+                              "type": "string",
+                              "format": "uri",
+                              "description": "Optional override for the client assertion `aud` claim. Defaults to the token endpoint URL."
+                            },
+                            "expiresInSeconds": {
+                              "type": "integer",
+                              "default": 300,
+                              "minimum": 1,
+                              "maximum": 3600,
+                              "description": "Client assertion lifetime in seconds."
+                            }
+                          }
+                        }
+                      ]
+                    }
+                  }
+                }
+              }
             }
           }
         }
@@ -137,6 +406,12 @@
           "options": {
             "displayName": "Linear",
             "id": "linear",
+            "idJag": {
+              "idp": {},
+              "resourceAs": {},
+              "scopeDelimiter": " ",
+              "scopes": []
+            },
             "scopes": [],
             "summary": "Native Linear remote MCP server."
           }

package/docs/policies/mcp-workos-oauth-inbound/schema.json

@@ -74,6 +74,84 @@
                 }
               }
             },
+            "idJag": {
+              "description": "Optional Identity Assertion JWT Authorization Grant (ID-JAG / XAA) support for the gateway token endpoint.",
+              "oneOf": [
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["enabled"],
+                  "properties": {
+                    "enabled": {
+                      "const": false,
+                      "description": "Disable ID-JAG support."
+                    }
+                  }
+                },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["enabled"],
+                  "properties": {
+                    "enabled": {
+                      "const": true,
+                      "description": "Enable ID-JAG support."
+                    },
+                    "trustedIssuers": {
+                      "type": "array",
+                      "minItems": 1,
+                      "description": "Trusted ID-JAG issuers. These values are never published in OAuth metadata. Omit to trust this policy's browser-login IdP.",
+                      "items": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "dependentRequired": {
+                          "issuer": ["jwksUrl"],
+                          "jwksUrl": ["issuer"]
+                        },
+                        "properties": {
+                          "issuer": {
+                            "type": "string",
+                            "format": "uri",
+                            "description": "Exact issuer URL expected in the ID-JAG iss claim. Provide together with jwksUrl, or omit both to default to this policy's browser-login IdP."
+                          },
+                          "jwksUrl": {
+                            "type": "string",
+                            "format": "uri",
+                            "description": "JWKS URL used to verify ID-JAG signatures from this issuer. Provide together with issuer, or omit both to default to this policy's browser-login IdP."
+                          },
+                          "expectedClientIds": {
+                            "type": "array",
+                            "items": {
+                              "type": "string",
+                              "minLength": 1
+                            },
+                            "description": "Optional allow-list of client IDs accepted from this issuer. The ID-JAG client_id must still match the authenticated token-endpoint client."
+                          },
+                          "subjectMapping": {
+                            "type": "string",
+                            "enum": [
+                              "iss_prefix",
+                              "iss_tenant_prefix",
+                              "sub_id_only"
+                            ],
+                            "default": "iss_prefix",
+                            "description": "How the ID-JAG subject is mapped into the gateway subject ID."
+                          }
+                        }
+                      }
+                    },
+                    "authorizationDetailsTypesAllowed": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "description": "Optional allow-list of RFC 9396 authorization_details type values accepted from ID-JAGs."
+                    }
+                  }
+                }
+              ]
+            },
             "browserLoginOverrides": {
               "type": "object",
               "description": "Optional overrides for the derived browser-login settings.",

package/docs/policies/mtls-auth-inbound/intro.md

@@ -1,7 +1,44 @@
-This policy verifies client mTLS results supplied by Zuplo's edge proxy. It
-checks the incoming mTLS verification status and, when enforcement is enabled,
-rejects requests where no client certificate was presented, certificate
-verification failed, or the certificate metadata cannot be parsed.
+The `mtls-auth-inbound` policy is the enforcement step of client mutual TLS
+(mTLS). It reads the verification result that Zuplo's edge proxy attaches to
+each request and, when enforcement is enabled, rejects requests that don't
+present a valid client certificate signed by a CA you trust. It is one part of a
+complete client mTLS setup: you first upload the signing CA to your account,
+then add this policy to the routes you want to protect.
+
+For the full walkthrough — CA upload, configuration, testing with `curl`,
+rotation, and troubleshooting (including the common
+`FAILED to get issuer certificate` error) — see the
+[Client mTLS authentication guide](https://zuplo.com/docs/articles/securing-the-gateway-with-client-mtls).
+
+## Setting up client mTLS
+
+This policy only enforces a result; it does not, on its own, make Zuplo verify
+client certificates. The end-to-end setup is:
+
+1. **Upload your CA certificate** to your account with the
+   [Zuplo CLI](https://zuplo.com/docs/cli/ca-certificate-create):
+   `zuplo ca-certificate create --name my_ca --cert ./ca.pem --account your-account`.
+   Upload the self-signed **root** CA that anchors the chain, not an
+   intermediate. CA certificates are scoped to your **account**, so once
+   uploaded, every gateway domain on the account verifies presented client
+   certificates against it.
+2. **Add this policy** (`mtls-auth-inbound`) to each route that should require a
+   verified client certificate, and set `certIssuerDN` to pin the issuer (see
+   the options described below).
+3. **Read the certificate** in your request handler or downstream policies from
+   `request.user.data.mtlsAuth`.
+4. **Test** with a client certificate issued by (or chained to) your CA:
+   `curl --cert ./client.pem --key ./client.key https://your-gateway.zuplo.app/v1/example`.
+
+See the
+[full guide](https://zuplo.com/docs/articles/securing-the-gateway-with-client-mtls)
+for CA management, custom domains, rotation, and troubleshooting.
+
+## How the policy behaves
+
+When enforcement is enabled, the policy rejects requests where no client
+certificate was presented, certificate verification failed, or the certificate
+metadata cannot be parsed.
 
 When verification passes, the policy parses the client certificate metadata and
 sets it on `request.user.data.mtlsAuth`. The metadata includes `subject`,
@@ -30,5 +67,15 @@ inspect `request.user.data.mtlsAuth.issuer` from a request signed by the desired
 CA.
 
 Note: this policy does not work with local development since it relies on
-metadata from the upstream reverse proxy, it is recommended to test this using a
+metadata from the upstream reverse proxy. It is recommended to test this using a
 working-copy or preview environment.
+
+## Learn more
+
+- [Client mTLS authentication guide](https://zuplo.com/docs/articles/securing-the-gateway-with-client-mtls)
+  — full end-to-end setup, CA management, and troubleshooting
+- [`ca-certificate` CLI reference](https://zuplo.com/docs/cli/ca-certificate-create)
+  — upload, list, describe, rename, and delete account CA certificates
+- [Gateway to Origin mTLS](https://zuplo.com/docs/articles/securing-backend-mtls)
+  — the reverse direction, where Zuplo authenticates to your backend with a
+  client certificate

package/docs/policies/okta-fga-authz-inbound/schema.json

@@ -7,7 +7,7 @@
   "isPaidAddOn": false,
   "isEnterprise": true,
   "isInternal": false,
-  "isBeta": true,
+  "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
   "products": ["api-gateway"],

package/docs/policies/open-id-jwt-auth-inbound/schema.json

@@ -54,7 +54,7 @@
             "jwkUrl": {
               "type": "string",
               "examples": [
-                "https://zuplo-demo.us.auth0.com/.well-known/jwks.json"
+                "https://my-tenant.us.auth0.com/.well-known/jwks.json"
               ],
               "description": "the url of the JSON Web Key Set (JWKS) - this is used to validate the JWT token signature (either this or `secret` must be set)."
             },
@@ -90,7 +90,7 @@
             {
               "issuer": "$env(AUTH_ISSUER)",
               "audience": "$env(AUTH_AUDIENCE)",
-              "jwkUrl": "https://zuplo-demo.us.auth0.com/.well-known/jwks.json"
+              "jwkUrl": "https://my-tenant.us.auth0.com/.well-known/jwks.json"
             },
             {
               "issuer": "$env(AUTH_ISSUER)",
@@ -107,7 +107,7 @@
           "options": {
             "issuer": "$env(AUTH_ISSUER)",
             "audience": "$env(AUTH_AUDIENCE)",
-            "jwkUrl": "https://zuplo-demo.us.auth0.com/.well-known/jwks.json"
+            "jwkUrl": "https://my-tenant.us.auth0.com/.well-known/jwks.json"
           }
         },
         {

package/docs/policies/openfga-authz-inbound/schema.json

@@ -7,7 +7,7 @@
   "isPaidAddOn": false,
   "isEnterprise": true,
   "isInternal": false,
-  "isBeta": true,
+  "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
   "products": ["api-gateway"],

package/docs/policies/propel-auth-jwt-inbound/schema.json

@@ -42,8 +42,8 @@
             },
             "authUrl": {
               "type": "string",
-              "examples": ["https://6587563.propelauthtest.com"],
-              "description": "Your PropelAuth authUrl. For example, `https://6587563.propelauthtest.com`."
+              "examples": ["https://12345678.propelauthtest.com"],
+              "description": "Your PropelAuth authUrl. For example, `https://12345678.propelauthtest.com`."
             },
             "verifierKey": {
               "type": "string",
@@ -64,7 +64,7 @@
           "module": "$import(@zuplo/runtime)",
           "options": {
             "allowUnauthenticatedRequests": false,
-            "authUrl": "https://6587563.propelauthtest.com",
+            "authUrl": "https://12345678.propelauthtest.com",
             "oAuthResourceMetadataEnabled": false,
             "verifierKey": "$env(PROPEL_VERIFIER_KEY)"
           }