zuplo 6.67.32 → 6.68.0

package/docs/policies/upstream-gcp-federated-auth-inbound/schema.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Upstream GCP Federated Auth",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": true,
+  "isInternal": false,
+  "isBeta": true,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Authenticates with GCP resources or Google services using Workload Identity Federation allowing secure access to these resources without requiring the use of a service account private key.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "UpstreamGcpFederatedAuthInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "UpstreamGcpFederatedAuthInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": [
+            "audience",
+            "serviceAccountEmail",
+            "workloadIdentityProvider"
+          ],
+          "properties": {
+            "audience": {
+              "type": "string",
+              "examples": ["https://hello-k7meruiynq-uc.a.run.app"],
+              "description": "The audience for the minted JWT. This is typically the URL of your service. See the document [AuthRequirement](https://cloud.google.com/endpoints/docs/grpc-service-config/reference/rpc/google.api#google.api.AuthRequirement) for details."
+            },
+            "serviceAccountEmail": {
+              "type": "string",
+              "examples": ["zup-api@my-project.iam.gserviceaccount.com"],
+              "description": "The Google Service Account email address."
+            },
+            "workloadIdentityProvider": {
+              "type": "string",
+              "examples": [
+                "projects/932049231233/locations/global/workloadIdentityPools/my-pool/providers/my-provider"
+              ]
+            },
+            "tokenLifetime": {
+              "type": "number",
+              "x-show-example": false,
+              "default": 3600,
+              "description": "The lifetime in seconds of the issued token."
+            },
+            "tokenRetries": {
+              "type": "number",
+              "x-show-example": false,
+              "default": 3,
+              "description": "The number of times to retry fetching the token in the event of a failure."
+            },
+            "expirationOffsetSeconds": {
+              "type": "number",
+              "x-show-example": false,
+              "default": 300,
+              "description": "The number of seconds less than the token expiration to cache the token."
+            },
+            "useMemoryCacheOnly": {
+              "type": "boolean",
+              "x-show-example": false,
+              "description": "This is an advanced option that should only be used if you do not want to persist information in ZoneCache."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "UpstreamGcpFederatedAuthInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "audience": "https://hello-k7meruiynq-uc.a.run.app",
+            "serviceAccountEmail": "zup-api@my-project.iam.gserviceaccount.com",
+            "workloadIdentityProvider": "projects/932049231233/locations/global/workloadIdentityPools/my-pool/providers/my-provider"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/upstream-gcp-jwt-inbound/intro.md

@@ -0,0 +1,10 @@
+This policy adds a JWT token to the headers, ready for us in an outgoing request
+when calling a GCP service (e.g. Cloud Endpoints / ESPv2). We recommend reading
+the `serviceAccountJson` from environment variables (so it is not checked in to
+source control) using the `$env(ENV_VAR)` syntax.
+
+CAUTION: This policy only works with
+[certain Google APIs](https://developers.google.com/identity/protocols/oauth2/service-account#jwt-auth).
+In most cases, the
+[Upstream GCP Service Auth](https://zuplo.com/docs/policies/upstream-gcp-service-auth-inbound)
+should be used.

package/docs/policies/upstream-gcp-jwt-inbound/schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Upstream GCP Self-Signed JWT",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": true,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Creates a self-signed JWT token (generated using a Google Service Account JSON) and attaches it to the outgoing request. Useful when calling GCP services like Cloud Endpoints / ESPv2",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "UpstreamGcpJwtInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "UpstreamGcpJwtInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["audience", "serviceAccountJson"],
+          "properties": {
+            "audience": {
+              "type": "string",
+              "examples": ["your_gcp_service.endpoint.com"],
+              "description": "The audience for the minted JWT. See the document [AuthRequirement](https://cloud.google.com/endpoints/docs/grpc-service-config/reference/rpc/google.api#google.api.AuthRequirement) for details."
+            },
+            "serviceAccountJson": {
+              "type": "string",
+              "examples": ["$env(SERVICE_ACCOUNT_JSON)"],
+              "description": "The Google Service Account key in JSON format. Note you can load this from environment variables using the $env(ENV\\_VAR) syntax."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "UpstreamGcpJwtInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "audience": "your_gcp_service.endpoint.com",
+            "serviceAccountJson": "$env(SERVICE_ACCOUNT_JSON)"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/upstream-gcp-service-auth-inbound/doc.md

@@ -0,0 +1,132 @@
+This policy authenticates your Zuplo gateway to Google Cloud Platform services
+by automatically adding GCP-issued ID tokens to the `Authorization` header of
+upstream requests. It supports both authenticating to your own GCP services and
+calling Google APIs directly.
+
+### How It Works
+
+The policy performs the following operations:
+
+1. Uses your GCP service account credentials to obtain an ID token or access
+   token
+2. Caches the token for subsequent requests until it expires
+3. Adds the token to the `Authorization` header as a Bearer token
+4. Automatically handles token renewal when needed
+
+### Setup Instructions
+
+#### Create the GCP Service Account
+
+1. [Create a service account](https://cloud.google.com/iam/docs/service-accounts-create)
+   specifically for your Zuplo Gateway (e.g., `zuplo-gateway`)
+2. Grant the account permission to call any GCP services you want to proxy with
+   Zuplo
+3. [Create a Service Account key](https://cloud.google.com/iam/docs/keys-create-delete)
+   in JSON format
+4. In your Zuplo project, set an environment variable (e.g.,
+   `GCP_SERVICE_ACCOUNT`) as a secret with the value of the downloaded JSON
+
+:::caution
+
+The value of the private key is a JSON file. **Before saving it to Zuplo's
+environment variables**, you must remove all line breaks and all instances of
+the `\n` escape character. The JSON file should be a single line.
+
+:::
+
+### Policy Configuration
+
+This policy supports two main use cases, each with different configuration
+requirements:
+
+#### 1. Authenticating to Your GCP Services
+
+When calling your own services like Cloud Run, Cloud Functions, or services
+protected by Identity Aware Proxy (IAP), use the `audience` property:
+
+```json
+{
+  "name": "gcp-service-auth",
+  "export": "UpstreamGcpServiceAuthInboundPolicy",
+  "module": "$import(@zuplo/runtime)",
+  "options": {
+    "audience": "https://my-app-1235.a.run.app",
+    "serviceAccountJson": "$env(GCP_SERVICE_ACCOUNT)"
+  }
+}
+```
+
+**Audience Values:**
+
+- For **Cloud Run**: Use the full URL of your Cloud Run service (e.g.,
+  `https://my-service.a.run.app`)
+- For **Identity Aware Proxy**: Use the Client ID of your OAuth application
+- For **Cloud Functions**: Use the full URL of your function
+
+#### 2. Calling Google APIs
+
+When calling Google APIs directly (e.g., executing a
+[Workflow](https://cloud.google.com/workflows/docs/executing-workflow)), use the
+`scopes` property:
+
+```json
+{
+  "name": "gcp-service-auth-gcloud-api",
+  "export": "UpstreamGcpServiceAuthInboundPolicy",
+  "module": "$import(@zuplo/runtime)",
+  "options": {
+    "scopes": [
+      "https://www.googleapis.com/auth/cloud-platform",
+      "https://www.googleapis.com/auth/cloud-platform.read-only"
+    ],
+    "serviceAccountJson": "$env(GCP_SERVICE_ACCOUNT)"
+  }
+}
+```
+
+**Finding Required Scopes:** Refer to Google's API documentation for the
+specific API you're calling. Look for the
+[**Authorization scopes**](https://cloud.google.com/resource-manager/reference/rest/v1/projects/get#authorization-scopes)
+section, which lists the required scopes in URL format (e.g.,
+`https://www.googleapis.com/auth/cloud-platform`).
+
+### Usage Example
+
+#### Securing Cloud Run Access
+
+Apply the policy to routes that need to access your Cloud Run service:
+
+```json
+{
+  "paths": {
+    "/api/data": {
+      "get": {
+        "x-zuplo-route": {
+          "policies": {
+            "inbound": ["jwt-auth", "gcp-service-auth"]
+          },
+          "handler": {
+            "export": "forwardToOrigin",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "baseUrl": "https://my-service-1235.a.run.app"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Security Considerations
+
+- Store the service account JSON as an environment variable using
+  `$env(VARIABLE_NAME)` syntax
+- Follow the principle of least privilege when assigning permissions to your
+  service account
+- Regularly rotate your service account keys according to your security policies
+- Consider using
+  [Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation)
+  for keyless authentication when possible
+- Monitor your service account usage through GCP audit logs

package/docs/policies/upstream-gcp-service-auth-inbound/intro.md

@@ -0,0 +1,25 @@
+Secure your Google Cloud Platform services by automatically adding GCP-issued ID
+tokens to upstream requests. This policy enables your Zuplo gateway to
+authenticate with GCP IAM-protected services without requiring any code changes
+to your backend.
+
+With this policy, you'll benefit from:
+
+- **Enhanced Backend Security**: Restrict access to your GCP services to only
+  your Zuplo gateway
+- **Simplified Authentication**: Delegate authentication and authorization to
+  your gateway without backend code changes
+- **Automatic Token Management**: Handle token acquisition, caching, and renewal
+  automatically
+- **GCP Integration**: Seamlessly connect with Cloud Run, Cloud Functions, GKE
+  with IAP, and other GCP services
+- **Credential Security**: Store sensitive GCP service account credentials
+  securely in your Zuplo environment
+
+This policy works with
+[GCP Identity Aware Proxy](https://zuplo.com/docs/articles/gke-with-upstream-auth-policy)
+or services like [Cloud Run](https://cloud.google.com/iap/docs/managing-access)
+that natively support IAM authorization.
+
+For information on how Google's service-based auth works, see
+[Authenticating for invocation](https://cloud.google.com/functions/docs/securing/authenticating).

package/docs/policies/upstream-gcp-service-auth-inbound/schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Upstream GCP Service Auth",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": true,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Creates an ID Token from Google's OAuth service and attaches it to the outgoing request. Useful when calling GCP services or Google APIs that are secured with GCP IAM.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "UpstreamGcpServiceAuthInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "UpstreamGcpServiceAuthInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["serviceAccountJson"],
+          "properties": {
+            "audience": {
+              "type": "string",
+              "examples": ["https://my-service-a2ev-uc.a.run.app"],
+              "description": "The audience for the service to be called. This is typically the URL of your service endpoint like 'https://my-service-a2ev-uc.a.run.app'. If calling a Google API, leave this empty."
+            },
+            "scopes": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "examples": [["https://www.googleapis.com/auth/cloud-platform"]],
+              "description": "The scopes to grant the access token. See [documentation](https://developers.google.com/identity/protocols/oauth2/scopes) for details. This is only set with calling a Google API. If calling a service like Cloud Run, etc. leave this empty."
+            },
+            "serviceAccountJson": {
+              "type": "string",
+              "examples": ["$env(SERVICE_ACCOUNT_JSON)"],
+              "description": "The Google Service Account key in JSON format. Note you can load this from environment variables using the `$env(ENV_VAR)` syntax."
+            },
+            "tokenRetries": {
+              "type": "number",
+              "x-show-example": false,
+              "default": 3,
+              "description": "The number of times to retry fetching the token in the event of a failure."
+            },
+            "expirationOffsetSeconds": {
+              "type": "number",
+              "x-show-example": false,
+              "default": 300,
+              "description": "The number of seconds less than the token expiration to cache the token."
+            },
+            "useMemoryCacheOnly": {
+              "type": "boolean",
+              "x-show-example": false,
+              "description": "This is an advanced option that should only be used if you do not want to persist information in ZoneCache."
+            },
+            "version": {
+              "type": "number",
+              "default": 1,
+              "enum": [1, 2],
+              "x-show-example": false,
+              "description": "The version of the policy."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "UpstreamGcpServiceAuthInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "audience": "https://my-service-a2ev-uc.a.run.app",
+            "scopes": ["https://www.googleapis.com/auth/cloud-platform"],
+            "serviceAccountJson": "$env(SERVICE_ACCOUNT_JSON)"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/upstream-zuplo-jwt-auth-inbound/doc.md

@@ -0,0 +1,213 @@
+## How It Works
+
+When a request passes through this policy:
+
+1. The policy generates a new JWT token using Zuplo's JWT service
+2. The JWT includes standard claims (subject, audience, expiration) and any
+   custom claims you configure
+3. The token is added to the specified request header (default: `Authorization`)
+4. The modified request is forwarded to your upstream service
+5. Your upstream service can then validate the JWT to authenticate the request
+   comes from your Zuplo API Gateway
+
+## Configuration
+
+### Basic Configuration
+
+The simplest configuration uses all defaults:
+
+```json
+{
+  "name": "upstream-jwt-policy",
+  "policyType": "upstream-zuplo-jwt-inbound"
+}
+```
+
+This will:
+
+- Add the JWT to the `Authorization` header
+- Use `Bearer` as the token prefix
+- Set token expiration to 300 seconds (5 minutes)
+- Use the authenticated user's subject or "api-gateway" as the JWT subject
+
+### Advanced Configuration
+
+```json
+{
+  "name": "upstream-jwt-policy",
+  "policyType": "upstream-zuplo-jwt-auth-inbound",
+  "handler": {
+    "export": "UpstreamZuploJwtAuthInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "audience": "https://api.example.com",
+      "headerName": "X-API-Token",
+      "tokenPrefix": "Token",
+      "expiresIn": "10m",
+      "additionalClaims": {
+        "iss": "my-api-gateway",
+        "scope": "read write",
+        "custom": "value"
+      }
+    }
+  }
+}
+```
+
+## Options Reference
+
+### `audience`
+
+- **Type**: `string`
+- **Default**: The current request URL
+- **Description**: The audience claim for the JWT. Useful when your upstream
+  service expects a specific audience value
+
+### `headerName`
+
+- **Type**: `string`
+- **Default**: `"Authorization"`
+- **Description**: The header name where the JWT will be attached
+
+### `tokenPrefix`
+
+- **Type**: `string`
+- **Default**: `"Bearer"`
+- **Description**: The prefix to use before the JWT token. Set to an empty
+  string to send the token without a prefix
+
+### `expiresIn`
+
+- **Type**: `number | string`
+- **Default**: `300`
+- **Description**: JWT expiration time. Can be:
+  - A number representing seconds (e.g., `300` for 5 minutes)
+  - A string with time units (e.g., `"5m"` for 5 minutes, `"1h"` for 1 hour,
+    `"7d"` for 7 days)
+
+  Supported time units:
+  - `s` - seconds
+  - `m` - minutes
+  - `h` - hours
+  - `d` - days
+  - `w` - weeks
+  - `y` - years
+
+### `additionalClaims`
+
+- **Type**: `object`
+- **Default**: `{}`
+- **Description**: Additional claims to include in the JWT. These will be merged
+  with the default claims
+
+## JWT Claims
+
+The generated JWT includes the following standard claims:
+
+- `sub` (subject): The authenticated user's subject claim, or "api-gateway" if
+  no user is authenticated
+- `aud` (audience): The value from the `audience` option, or the current request
+  URL if not specified
+- `exp` (expiration): Token expiration timestamp based on the `expiresIn` option
+- `iat` (issued at): Token issuance timestamp (automatically added by JWT
+  service)
+
+Any properties in `additionalClaims` will be merged into the JWT payload.
+
+## Use Cases
+
+### Audience-Specific Authentication
+
+As a best practice, you can set the `audience` option to target specific
+upstream services. This ensures that the JWT is only valid for that service,
+preventing misuse if the token is intercepted.
+
+```json
+{
+  "name": "audience-specific-auth",
+  "policyType": "upstream-zuplo-jwt-auth-inbound",
+  "handler": {
+    "export": "UpstreamZuploJwtAuthInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "audience": "https://api.example.com"
+    }
+  }
+}
+```
+
+### Custom Claims
+
+Custom claims can be added to the JWT to provide additional context or metadata
+for your upstream service. For example, you might want to include
+environment-specific variables.
+
+```json
+{
+  "name": "service-auth",
+  "policyType": "upstream-zuplo-jwt-auth-inbound",
+  "handler": {
+    "export": "UpstreamZuploJwtAuthInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "additionalClaims": {
+        "env": "$env(MY_VAR)"
+      }
+    }
+  }
+}
+```
+
+### Custom Header Authentication
+
+Sometimes your upstream service might already expect an `Authorization` header.
+In that case you can configure the policy to use a custom header.
+
+```json
+{
+  "name": "custom-header-auth",
+  "policyType": "upstream-zuplo-jwt-auth-inbound",
+  "handler": {
+    "export": "UpstreamZuploJwtAuthInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "headerName": "X-Service-Token",
+      "tokenPrefix": "", // No prefix
+      "expiresIn": "30m"
+    }
+  }
+}
+```
+
+## Prerequisites
+
+This policy requires the JWT Service Plugin to be configured in your Zuplo
+project. The JWT service handles the cryptographic signing of tokens using your
+project's private key.
+
+## Security Considerations
+
+1. **Token Expiration**: Keep token expiration times as short as practical for
+   your use case
+2. **Claims Validation**: Upstream services should validate JWT claims,
+   especially the audience and expiration
+3. **Claim Sensitivity**: Avoid including sensitive information in JWT claims as
+   they can be decoded by anyone
+
+## Troubleshooting
+
+### Token Not Appearing in Request
+
+Check that:
+
+- The policy is correctly configured in your route
+- The `headerName` matches what your upstream service expects
+- No other policies are overwriting the header
+
+### Invalid Token Errors
+
+Verify that:
+
+- Your upstream service can validate Zuplo-signed JWTs
+- The token hasn't expired (check `expiresIn` setting)
+- The audience claim matches what your upstream service expects

package/docs/policies/upstream-zuplo-jwt-auth-inbound/intro.md

@@ -0,0 +1,16 @@
+This policy generates a Zuplo JWT token and attaches it to outgoing requests.
+It's useful when your upstream services need to authenticate requests coming
+from your Zuplo API Gateway using JWT tokens.
+
+The policy creates a self-signed JWT using Zuplo's built-in JWT service and adds
+it to the specified request header (defaults to `Authorization`). The JWT
+includes standard claims like subject, audience, and expiration time, plus any
+additional custom claims you configure.
+
+Key features:
+
+- Configurable audience claim for specific service targeting
+- Configurable header name and token prefix
+- Support for custom claims in the JWT payload
+- Adjustable token expiration time
+- Automatic subject extraction from authenticated users