Copy page

Authorization

MCP Google OAuth Policy

Authenticate MCP gateway requests using a gateway-issued OAuth access token, with browser login delegated to Google.

This is a Google-friendly wrapper around McpOAuthInboundPolicy. Provide clientId + clientSecret, and Google's fixed OIDC issuer, JWKS URL, and browser login endpoints are derived automatically.

Configuration

The configuration shows how to configure the policy in the 'policies.json' document.

config/policies.json
{
  "name": "my-mcp-google-oauth-inbound-policy",
  "policyType": "mcp-google-oauth-inbound",
  "handler": {
    "export": "McpGoogleOAuthInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "browserLoginOverrides": {
        "pkce": "none",
        "remoteTimeoutMs": 10000,
        "sessionTtlSeconds": 28800,
        "stateTtlSeconds": 900
      },
      "clientId": "$env(GOOGLE_CLIENT_ID)",
      "clientSecret": "$env(GOOGLE_CLIENT_SECRET)",
      "gateway": {
        "accessTokenTtlSeconds": 900,
        "cimdEnabled": true,
        "refreshTokenTtlSeconds": 2592000
      },
      "scope": "openid profile email"
    }
  }
}

Policy Configuration

• name <string> - The name of your policy instance. This is used as a reference in your routes.
• policyType <string> - The identifier of the policy. This is used by the Zuplo UI. Value should be mcp-google-oauth-inbound.
• handler.export <string> - The name of the exported type. Value should be McpGoogleOAuthInboundPolicy.
• handler.module <string> - The module containing the policy. Value should be $import(@zuplo/runtime).
• handler.options <object> - The options for this policy. See Policy Options below.

Policy Options

The options for this policy are specified below. All properties are optional unless specifically marked as required.

• clientId (required) <string> - The Google OAuth client_id registered for the gateway's browser login flow. Google uses a fixed OIDC issuer and discovery endpoint.
• clientSecret (required) <string> - The Google OAuth client_secret. Use $env(...) to source from a secret environment variable.
• scope <string> - OIDC scopes requested during browser login. Defaults to "openid profile email".
• gateway <object> - Gateway-side OAuth token settings. The gateway issuer and advertised URLs are derived from the incoming request origin.
  • accessTokenTtlSeconds <integer> - Lifetime of access tokens issued by /oauth/token. Defaults to 900.
  • refreshTokenTtlSeconds <integer> - Lifetime of refresh tokens issued by /oauth/token. Defaults to 2592000.
  • cimdEnabled <boolean> - Whether to advertise client_id_metadata_document_supported in AS metadata. Defaults to true.
• idJag <undefined> - Optional Identity Assertion JWT Authorization Grant (ID-JAG / XAA) support for the gateway token endpoint.
• browserLoginOverrides <object> - Optional overrides for the derived browser-login settings.
  • remoteTimeoutMs <integer> - No description available. Defaults to 10000.
  • stateTtlSeconds <integer> - No description available. Defaults to 900.
  • sessionTtlSeconds <integer> - No description available. Defaults to 28800.
  • pkce <string> - Whether to send S256 PKCE on the federated browser-login authorization request and replay the verifier at the token exchange. Defaults to "none". Set to "S256" when the identity provider mandates PKCE on the authorization-code flow. Allowed values are S256, none. Defaults to "none".

Using the Policy

Authenticate MCP gateway requests using a gateway-issued OAuth access token, with browser login delegated to Google.

This is a thin Google-friendly wrapper around the generic McpOAuthInboundPolicy. Use it when you want to configure browser login with just clientId + clientSecret instead of the full set of OIDC URLs.

Derived configuration

Google uses a fixed OIDC issuer and discovery document. Given a Google OAuth client ID, the wrapper derives:

These endpoint shapes come from Google's OIDC discovery document at https://accounts.google.com/.well-known/openid-configuration.

Configuration

Code
{
  "name": "google-managed-oauth",
  "policyType": "mcp-google-oauth-inbound",
  "handler": {
    "module": "$import(@zuplo/runtime)",
    "export": "McpGoogleOAuthInboundPolicy",
    "options": {
      "clientId": "$env(GOOGLE_CLIENT_ID)",
      "clientSecret": "$env(GOOGLE_CLIENT_SECRET)"
    }
  }
}

clientId must be a Google OAuth web client ID, such as 123456789012-abc123def456.apps.googleusercontent.com. The policy rejects issuer URLs, Google API hostnames, and values that do not use Google's OAuth client ID shape.

Pairing

Pair this policy with McpTokenExchangeInboundPolicy and McpProxyHandler, the same as McpOAuthInboundPolicy. Only one MCP OAuth policy is allowed per project; attach the same policy by name to every MCP route.

Read more about how policies work