zuplo 6.67.32 → 6.68.0

package/docs/policies/okta-fga-authz-inbound/doc.md

@@ -0,0 +1,181 @@
+## Usage
+
+To use this policy, you must programmatically set the relationship checks to be
+performed against your Okta FGA store. This is done using the static
+`setContextChecks` method.
+
+The most common way to set the authorization checks are:
+
+1. Creating custom inbound policies for each authorization scenario
+2. Creating a custom inbound policy that reads data from the OpenAPI operation
+   and sets the authorization checks dynamically
+
+### Example: Custom Authorization Policies
+
+Create a file like `modules/oktafga-checks.ts` to define your custom
+authorization policies:
+
+```typescript
+import {
+  ZuploRequest,
+  ZuploContext,
+  RuntimeError,
+  HttpProblems,
+  OktaFGAAuthZInboundPolicy,
+} from "@zuplo/runtime";
+
+export async function canReadFolder(
+  request: ZuploRequest,
+  context: ZuploContext
+) {
+  if (!request.params?.folderId) {
+    throw new RuntimeError("Folder ID not found in request");
+  }
+
+  context.log.info("Setting OktaFGA context checks");
+
+  if (!request.user?.sub) {
+    return HttpProblems.forbidden(request, context, {
+      detail: "User not found",
+    });
+  }
+
+  // Set the authorization check to verify if the user has viewer access to the folder
+  OktaFGAAuthZInboundPolicy.setContextChecks(context, {
+    user: `user:${request.user.sub}`,
+    relation: "viewer",
+    object: `folder:${request.params.folderId}`,
+  });
+
+  return request;
+}
+
+export async function canEditDocument(
+  request: ZuploRequest,
+  context: ZuploContext
+) {
+  if (!request.params?.documentId) {
+    throw new RuntimeError("Document ID not found in request");
+  }
+
+  if (!request.user?.sub) {
+    return HttpProblems.forbidden(request, context, {
+      detail: "User not found",
+    });
+  }
+
+  // Set the authorization check to verify if the user has editor access to the document
+  OktaFGAAuthZInboundPolicy.setContextChecks(context, {
+    user: `user:${request.user.sub}`,
+    relation: "editor",
+    object: `document:${request.params.documentId}`,
+  });
+
+  return request;
+}
+```
+
+#### Applying to Routes
+
+In your route configuration, apply both the custom authorization policy and the
+OktaFGA policy:
+
+```json
+{
+  "path": "/folders/:folderId",
+  "methods": ["GET"],
+  "policies": {
+    "inbound": ["jwt-auth", "authz-can-read-folder", "oktafga-authz"]
+  }
+}
+```
+
+Then in your `policies.json`:
+
+```json
+{
+  "name": "authz-can-read-folder",
+  "export": "canReadFolder",
+  "module": "$import(./modules/oktafga-checks)"
+},
+{
+  "name": "oktafga-authz",
+  "export": "OktaFGAAuthZInboundPolicy",
+  "module": "$import(@zuplo/runtime)",
+  "options": {
+    // OktaFGA configuration...
+  }
+}
+```
+
+### Example: Dynamic Authorization Checks
+
+You can make your authorization checks more dynamic by reading data from your
+OpenAPI specification or other sources. This allows you to define authorization
+rules that adapt based on the route, method, or other request properties.
+
+For example, you could access custom data defined in your route:
+
+```typescript
+export async function dynamicAuthCheck(
+  request: ZuploRequest,
+  context: ZuploContext
+) {
+  // Access custom data from the route configuration
+  const data = context.route.raw<{
+    "x-authz": {
+      resourceType: string;
+      permission: string;
+      resourceIdParam: string;
+    };
+  }>();
+  const authzData = data["x-authz"];
+
+  if (!authzData?.resourceType || !authzData?.permission) {
+    throw new RuntimeError(
+      "Missing resource type or permission in route config"
+    );
+  }
+
+  if (!request.user?.sub) {
+    return HttpProblems.forbidden(request, context);
+  }
+
+  // Extract resource ID from request parameters
+  const resourceId = request.params?.[authzData.resourceIdParam];
+
+  if (!resourceId) {
+    throw new RuntimeError(
+      `Resource ID parameter '${authzData.resourceIdParam}' not found`
+    );
+  }
+
+  // Set dynamic authorization check
+  OktaFGAAuthZInboundPolicy.setContextChecks(context, {
+    user: `user:${request.user.sub}`,
+    relation: authzData.permission,
+    object: `${authzData.resourceType}:${resourceId}`,
+  });
+
+  return request;
+}
+```
+
+Then in your OpenAPI document, you would set the custom data on the `x-authz`
+property:
+
+```json
+{
+  "paths": {
+    "/custom-data": {
+      "post": {
+        "x-authz": {
+          "resourceType": "document",
+          "resourceIdParam": "documentId",
+          "permission": "editor"
+        }
+      }
+    }
+  }
+}
+```

package/docs/policies/okta-fga-authz-inbound/intro.md

@@ -0,0 +1,20 @@
+This policy authorizes requests using Okta Fine-Grained Authorization (FGA),
+providing robust access control for your API resources. If the request is not
+authorized, a 403 response will be returned.
+
+With this policy, you'll benefit from:
+
+- **Powerful Authorization Model**: Implement complex relationship-based access
+  control using Okta FGA's authorization model
+- **Flexible Permission Structure**: Define granular permissions with
+  user-to-resource relationships that scale with your application
+- **Seamless Okta Integration**: Leverage your existing Okta identity
+  infrastructure for consistent authorization across your ecosystem
+- **Dynamic Authorization Logic**: Create context-aware authorization rules that
+  adapt based on route, method, or request properties
+- **Simplified Implementation**: Reduce development time with ready-to-use
+  authorization checks that integrate with your API gateway
+- **Enhanced Security**: Apply fine-grained access control to protect sensitive
+  resources and operations
+- **Centralized Policy Management**: Manage all your authorization rules in one
+  place through Okta FGA

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

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Okta FGA Authorization",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": true,
+  "isInternal": false,
+  "isBeta": true,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Authorize requests using Okta FGA.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "OktaFGAAuthZInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "OktaFGAAuthZInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": [
+            "credentials",
+            "region",
+            "storeId",
+            "authorizationModelId"
+          ],
+          "properties": {
+            "region": {
+              "type": "string",
+              "description": "The region your store is deployed.",
+              "enum": ["us1", "eu1", "au1"],
+              "examples": ["us1"]
+            },
+            "storeId": {
+              "type": "string",
+              "description": "The ID of the store.",
+              "examples": ["$env(FGA_STORE_ID)"]
+            },
+            "authorizationModelId": {
+              "type": "string",
+              "description": "The ID of the authorization model.",
+              "examples": ["$env(FGA_MODEL_ID)"]
+            },
+            "allowUnauthorizedRequests": {
+              "type": "boolean",
+              "default": false,
+              "x-show-example": false,
+              "description": "Indicates whether the request should continue if authorization fails. Default is `false` which means unauthorized users will automatically receive a 403 response."
+            },
+            "credentials": {
+              "type": "object",
+              "required": ["clientId", "clientSecret"],
+              "properties": {
+                "clientId": {
+                  "type": "string",
+                  "description": "The client ID."
+                },
+                "clientSecret": {
+                  "type": "string",
+                  "description": "The client secret."
+                }
+              },
+              "examples": [
+                {
+                  "clientId": "$env(FGA_CLIENT_ID)",
+                  "clientSecret": "$env(FGA_CLIENT_SECRET)"
+                }
+              ]
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "OktaFGAAuthZInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "authorizationModelId": "$env(FGA_MODEL_ID)",
+            "credentials": {
+              "clientId": "$env(FGA_CLIENT_ID)",
+              "clientSecret": "$env(FGA_CLIENT_SECRET)"
+            },
+            "region": "us1",
+            "storeId": "$env(FGA_STORE_ID)"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/okta-jwt-auth-inbound/intro.md

@@ -0,0 +1,7 @@
+Authenticate requests with JWT tokens issued by Okta. This is a customized
+version of the
+[OpenId JWT Policy](https://zuplo.com/docs/policies/open-id-jwt-auth-inbound)
+specifically for Okta.
+
+See [this document](https://zuplo.com/docs/articles/oauth-authentication) for
+more information about OAuth authorization in Zuplo.

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

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Okta JWT Auth",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Authenticate users using Okta issued JWT tokens.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "OktaJwtInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "OktaJwtInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["issuerUrl"],
+          "properties": {
+            "allowUnauthenticatedRequests": {
+              "type": "boolean",
+              "default": false,
+              "description": "Allow unauthenticated requests to proceed. This is use useful if you want to use multiple authentication policies or if you want to allow both authenticated and non-authenticated traffic."
+            },
+            "issuerUrl": {
+              "type": "string",
+              "examples": ["https://dev-12345.okta.com/oauth2/abc"],
+              "description": "Your Okta authorization server's issuer URL. For example, `https://dev-12345.okta.com/oauth2/abc`."
+            },
+            "audience": {
+              "type": "string",
+              "examples": ["api://my-api"],
+              "description": "The Okta audience of your API, for example `api://my-api`."
+            },
+            "oAuthResourceMetadataEnabled": {
+              "type": "boolean",
+              "default": false,
+              "description": "Flag that determines whether OAuth protected resource metadata is enabled."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "OktaJwtInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "allowUnauthenticatedRequests": false,
+            "audience": "api://my-api",
+            "issuerUrl": "https://dev-12345.okta.com/oauth2/abc",
+            "oAuthResourceMetadataEnabled": false
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/open-id-jwt-auth-inbound/doc.md

@@ -0,0 +1,58 @@
+This policy authenticates incoming requests using OpenID-compliant JWT bearer
+tokens. It validates the token's signature, expiration, and claims against your
+OpenID provider's configuration.
+
+## Configuration
+
+When setting up this policy, you'll need to configure your OpenID provider
+details. Note that sometimes the `issuer` and `audience` will vary between your
+environments (e.g. dev, staging and prod). We recommend storing these values in
+your environment variables and using `$env(VARIABLE_NAME)` to include them in
+your policy configuration.
+
+:::note
+
+Note you can have multiple instances of the same policy with different `name`s
+if you want to have slightly different rules (such as settings for the
+`allowUnauthenticatedRequests` setting).
+
+:::
+
+```json
+{
+  "path": "/products/:123",
+  "methods": ["POST"],
+  "handler": {
+    "module": "$import(./modules/products)",
+    "export": "postProducts"
+  },
+  "corsPolicy": "None",
+  "version": "none",
+  "policies": {
+    "inbound": ["your-jwt-policy-name"]
+  }
+}
+```
+
+## Using the user property in code
+
+After the policy validates a JWT token, it populates the `ZuploRequest`'s `user`
+property with data from the token. You can access this in your request handlers:
+
+```typescript
+export async function myHandler(request: ZuploRequest, context: ZuploContext) {
+  // Access the authenticated user information
+  const userId = request.user?.sub;
+  const userClaims = request.user?.data;
+
+  // Use the user information in your business logic
+  context.log.info(`Request from user: ${userId}`);
+
+  // Continue processing
+  return request;
+}
+```
+
+For a complete example of using the user object in a
+[RequestHandler](../handlers/custom-handler.md), see
+[Setting up JWT auth with Auth0](../policies/auth0-jwt-auth-inbound.md).

package/docs/policies/open-id-jwt-auth-inbound/intro.md

@@ -0,0 +1,30 @@
+The Open ID JWT Authentication policy allows you to authenticate incoming
+requests using an OpenID-compliant bearer token. It works with common
+authentication services like Auth0 but should also work with any valid OpenID
+JWT token.
+
+When configured, Zuplo checks incoming requests for a JWT token and
+automatically populates the `ZuploRequest`'s `user` property with a user object.
+This `user` object will have a `sub` property - taking the `sub` id from the JWT
+token. It will also have a `data` property populated by other data returned in
+the JWT token (including any claims).
+
+With this policy, you'll benefit from:
+
+- **Universal Provider Support**: Works with any OpenID-compliant identity
+  provider including Auth0, Okta, Azure AD, and more
+- **Enhanced Security**: Validate token signatures, expiration, and claims to
+  ensure only authorized users access your API
+- **Flexible Configuration**: Easily customize token sources, audience
+  validation, and required claims
+- **Comprehensive User Context**: Access user identity and claims directly in
+  your request handlers
+- **Zero-Code Authentication**: Implement industry-standard authentication with
+  simple configuration
+- **Multiple Authentication Modes**: Support both required and optional
+  authentication patterns
+- **Seamless Integration**: Works with your existing OpenID infrastructure with
+  minimal setup
+
+See [this document](https://zuplo.com/docs/articles/oauth-authentication) for
+more information about OAuth authorization in Zuplo.

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

@@ -0,0 +1,128 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "JWT Auth",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "The Open ID JWT Authentication policy allows you to authenticate incoming requests using an Open ID compliant bearer token.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "OpenIdJwtInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "OpenIdJwtInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": [],
+          "properties": {
+            "authHeader": {
+              "type": "string",
+              "default": "Authorization",
+              "x-show-example": false,
+              "description": "The name of the header with the key."
+            },
+            "issuer": {
+              "type": "string",
+              "examples": ["$env(AUTH_ISSUER)"],
+              "description": "The expected issuer claim in the JWT token."
+            },
+            "audience": {
+              "type": "string",
+              "examples": ["$env(AUTH_AUDIENCE)"],
+              "description": "The expected audience claim in the JWT token."
+            },
+            "jwkUrl": {
+              "type": "string",
+              "examples": [
+                "https://zuplo-demo.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)."
+            },
+            "secret": {
+              "type": "string",
+              "examples": ["$env(AUTH_JWT_SIGNING_KEY)"],
+              "description": "The key used to verify the signature of the JWT token (either this or `jwkUrl` must be set)."
+            },
+            "allowUnauthenticatedRequests": {
+              "type": "boolean",
+              "default": false,
+              "description": "indicates whether the request should continue if authentication fails. Defaults is `false` which means unauthenticated users will automatically receive a 401 response."
+            },
+            "subPropertyName": {
+              "type": "string",
+              "examples": ["sub"],
+              "description": "The name of the property in the JWT token that contains the user's unique identifier."
+            },
+            "headers": {
+              "type": "object",
+              "description": "Additional headers to send with the JWK request.",
+              "additionalProperties": {
+                "type": "string"
+              }
+            },
+            "oAuthResourceMetadataEnabled": {
+              "type": "boolean",
+              "default": false,
+              "description": "Flag that determines whether OAuth protected resource metadata is enabled."
+            }
+          },
+          "examples": [
+            {
+              "x-example-name": "Public Key Validation with JWKS (Recommended)",
+              "x-example-description": "This example shows how to configure the policy using a Public Key from an OpenID Connect provider.",
+              "issuer": "$env(AUTH_ISSUER)",
+              "audience": "$env(AUTH_AUDIENCE)",
+              "jwkUrl": "https://zuplo-demo.us.auth0.com/.well-known/jwks.json"
+            },
+            {
+              "x-example-name": "Client Secret Validation",
+              "x-example-description": "This example shows how to configure the policy using a shared secret.",
+              "issuer": "$env(AUTH_ISSUER)",
+              "audience": "$env(AUTH_AUDIENCE)",
+              "secret": "$env(AUTH_SECRET)"
+            }
+          ]
+        }
+      },
+      "examples": [
+        {
+          "export": "OpenIdJwtInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "audience": "$env(AUTH_AUDIENCE)",
+            "issuer": "$env(AUTH_ISSUER)",
+            "jwkUrl": "https://zuplo-demo.us.auth0.com/.well-known/jwks.json"
+          }
+        },
+        {
+          "export": "OpenIdJwtInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "audience": "$env(AUTH_AUDIENCE)",
+            "issuer": "$env(AUTH_ISSUER)",
+            "secret": "$env(AUTH_SECRET)"
+          }
+        }
+      ]
+    }
+  }
+}