diff --git a/portal/how-to-guides/configure-cors.mdx b/portal/how-to-guides/configure-cors.mdx index 0f0e5a912..c71ee4509 100644 --- a/portal/how-to-guides/configure-cors.mdx +++ b/portal/how-to-guides/configure-cors.mdx @@ -1,8 +1,170 @@ --- -title: "Configure CORS" -description: "How to configure CORS at the Developer Portal application level and at the Tyk Gateway level for APIs exposed via the portal." +title: "How to Configure CORS in Developer Portal" +sidebarTitle: "Configure CORS" +description: "Configure CORS for the Tyk Developer Portal application and for APIs exposed in the Live Portal, enabling consumers to test APIs from the API Playground." +keywords: "CORS, cross-origin resource sharing, Developer Portal CORS, Gateway CORS, API Playground, PORTAL_CORS_ENABLE" --- +Cross-origin request configuration in the Developer Portal involves two independent layers: the Portal application itself and the Tyk Gateway APIs that consumers test via the API Playground. Both layers must be configured for a fully functional cross-origin deployment. + +## Prerequisites + +- Developer Portal is deployed and accessible +- Tyk Gateway and Dashboard are running +- At least one [API product](/portal/api-products) is configured and published in the Portal +- You know the public URL of your Live Portal (for example, `https://portal.example.com`) +- You know the public URL of your Tyk Gateway (for example, `https://api.example.com`) + +## Configure Portal Application CORS + +Portal application CORS controls which external origins may call the Portal's own Admin API and Live Portal routes. It is configured via environment variables on the Portal process. + + +[PORTAL_CORS_ENABLE](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-enable) defaults to `false`. All cross-origin requests to the Portal are rejected until you set this to `true`. + + +1. **Enable CORS** + + Set [PORTAL_CORS_ENABLE](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-enable) to `true` on the Portal process. + + + + ```ini + PORTAL_CORS_ENABLE=true + ``` + + + ```json + { + "CORS": { + "Enable": true + } + } + ``` + + + +2. **Set allowed origins** + + Set [PORTAL_CORS_ALLOWED_ORIGINS](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-allowed-origins) to the origins permitted to make cross-origin requests to the Portal. Use the exact scheme and host of each origin, separated by commas. Wildcards are supported. + + When unset, all origins are allowed by default. Specify origins explicitly to restrict access. + + + + ```ini + PORTAL_CORS_ALLOWED_ORIGINS=https://admin.example.com,https://developer.example.com + ``` + + + ```json + { + "CORS": { + "AllowedOrigins": [ + "https://admin.example.com", + "https://developer.example.com" + ] + } + } + ``` + + + + + Do not set [PORTAL_CORS_ALLOWED_ORIGINS](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-allowed-origins) to `*` when `PORTAL_CORS_ALLOW_CREDENTIALS=true`. The CORS specification does not allow credentialed requests from wildcard origins. Specify each origin explicitly instead. + + +3. **Set allowed headers and methods** + + Set the HTTP headers and methods that cross-origin requests to the Portal may use. No headers are allowed by default. The default allowed methods are `GET` and `POST`. + + + + ```ini + PORTAL_CORS_ALLOWED_HEADERS=Authorization,Content-Type,X-Requested-With + PORTAL_CORS_ALLOWED_METHODS=GET,POST,PUT,DELETE,OPTIONS + ``` + + + ```json + { + "CORS": { + "AllowedHeaders": ["Authorization", "Content-Type", "X-Requested-With"], + "AllowedMethods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"] + } + } + ``` + + + +4. **(Optional) Configure additional CORS settings** + + | Config key | Default | Description | + |---|---|---| + | [CORS.MaxAge](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-max-age) | `0` | How long, in seconds, browsers may cache the preflight response. A positive value reduces preflight round trips. | + | [CORS.AllowCredentials](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-allow-credentials) | `false` | Whether the Portal includes credentials (cookies, HTTP authentication) in CORS responses. | + +5. **Restart the Portal** + + Restart the Portal process or pod for the environment variable changes to take effect. + +6. **Verify** + + Open your browser developer tools and make a cross-origin request to the Portal from an allowed origin. The response headers should include `Access-Control-Allow-Origin` and the request should succeed. + +--- + +## Configure Gateway CORS for APIs + +When a consumer tests an API using the API Playground on the Live Portal, the browser makes requests directly to the Tyk Gateway. The Portal does not proxy these requests and does not inject CORS headers. You must configure CORS on the API definition for each API exposed through the Portal. + + +**Tyk Gateway v5.8.6–v5.8.13:** A middleware ordering issue in these versions causes the allow list to run before CORS processing, returning `403 Forbidden` for OPTIONS preflight requests. + +Upgrade to Gateway v5.8.14 or later to resolve this. See [Troubleshoot CORS Issues](/portal/troubleshooting/cors-issues) for diagnosis steps. + + +1. **Locate the CORS block** + + In a Tyk OAS API definition, CORS configuration sits under `x-tyk-api-gateway.middleware.global.cors`. + +2. **Add the CORS configuration** + + ```yaml expandable + x-tyk-api-gateway: + middleware: + global: + cors: + enabled: true + allowedOrigins: + - "https://portal.example.com" + allowedMethods: + - GET + - POST + - PUT + - DELETE + - OPTIONS + allowedHeaders: + - Origin + - Content-Type + - Authorization + optionsPassthrough: false + ``` + + Set `optionsPassthrough` to `false` (the default). When `false`, the Gateway intercepts OPTIONS preflight requests, responds with CORS headers, and does not forward the request to the upstream. + +3. **Update the API** + + Update the API definition in Tyk Dashboard. + +4. **Verify** + + Open the API Playground on your Live Portal and send a test request. The request should complete without CORS errors in the browser console. + -This page is a placeholder. Content is being written. +If you are using a **Tyk Classic API definition**, configure CORS in Tyk Dashboard under **APIs** > **Advanced Options** > **CORS**. See the [Classic API CORS reference](/api-management/gateway-config-tyk-classic#cross-origin-resource-sharing-cors) for details. + +## Related + +- [Troubleshoot CORS Issues](/portal/troubleshooting/cors-issues) — diagnose and fix common CORS errors in the Developer Portal and API Playground diff --git a/portal/troubleshooting/cors-issues.mdx b/portal/troubleshooting/cors-issues.mdx index c2743f738..4539e3771 100644 --- a/portal/troubleshooting/cors-issues.mdx +++ b/portal/troubleshooting/cors-issues.mdx @@ -1,8 +1,110 @@ --- -title: "CORS Issues" -description: "Troubleshoot CORS errors in the Tyk Developer Portal, including endpoint whitelisting interactions, API playground errors, and Portal vs Gateway CORS configuration." +title: "Troubleshoot CORS Issues in Developer Portal" +sidebarTitle: "CORS Issues" +description: "Diagnose and fix CORS errors in the Tyk Developer Portal and API Playground." +keywords: "CORS, troubleshooting, Access-Control-Allow-Origin, API Playground, PORTAL_CORS_ENABLE," --- - -This page is a placeholder. Content is being written. - +Cross-origin errors in the Developer Portal arise from two independent layers: the Portal application itself and the Tyk Gateway APIs that the API Playground calls directly. Identify which layer is failing before applying a fix. + + + + **Symptom** + + Requests from your application to the Portal Admin API or Live Portal routes fail. The browser console shows: + + ``` + Access to fetch at 'https://portal.example.com/...' from origin 'https://app.example.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. + ``` + + Preflight `OPTIONS` requests to the Portal return `404 Not Found` or `405 Method Not Allowed`. + + **Cause** + + [PORTAL_CORS_ENABLE](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-enable) is `false` (the default). The Portal's CORS middleware is disabled, so no `Access-Control-Allow-Origin` header is added to any response and `OPTIONS` preflight requests fall through to the router with no matching handler. + + **Fix** + + Enable Portal CORS and set your allowed origins. See [Configure Portal Application CORS](/portal/how-to-guides/configure-cors#configure-portal-application-cors). + + + + **Symptom** + + Test requests in the API Playground fail. The browser console shows one of: + + - `401 Unauthorized` on the `OPTIONS` preflight request + - `Access to fetch at 'https://api.example.com/...' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.` + + **Cause** + + The API definition in Tyk Gateway has CORS misconfigured: + + - **CORS disabled entirely**: The Gateway routes the `OPTIONS` preflight through the authentication middleware. Because preflight requests carry no `Authorization` header, the Gateway rejects them with `401 Unauthorized`. + - **CORS enabled but Portal origin not in the allowed list**: The Gateway intercepts the preflight and returns `200 OK`, but omits the `Access-Control-Allow-Origin` header because the Portal's origin does not match `allowed_origins`. The browser treats this as a CORS failure. + + **Fix** + + Configure CORS on the API definition and add your Portal URL to the allowed origins. See [Configure Gateway CORS for APIs](/portal/how-to-guides/configure-cors#configure-gateway-cors-for-apis). + + + + **Symptom** + + API Playground requests fail on Gateway versions v5.8.6 through v5.8.13, even when CORS is correctly configured and the Portal origin is in `allowed_origins`. The browser console shows: + + ``` + TypeError: Failed to fetch + ``` + + The `OPTIONS` preflight returns `403 Forbidden` with one of the following response bodies: + + ```json + {"error": "Requested endpoint is forbidden"} + ``` + + ```json + {"error": "Access to this API has been disallowed"} + ``` + + **Cause** + + A middleware ordering regression in Gateway versions v5.8.6–v5.8.13 caused the allow-list middleware (`VersionCheck`) to run before the CORS middleware. The allow-list evaluates the `OPTIONS` method against endpoint rules and returns `403 Forbidden` before the CORS middleware can intercept and handle the preflight. + + **Fix** + + Upgrade Tyk Gateway to v5.8.14 or later, where the middleware ordering is corrected. + + + + **Symptom** + + Credentialed cross-origin requests to the Portal fail. The browser console shows: + + ``` + The value of the 'Access-Control-Allow-Origin' header in the response must not be the wildcard '*' when the request's credentials mode is 'include'. + ``` + + **Cause** + + [PORTAL_CORS_ALLOW_CREDENTIALS](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-allow-credentials)=true is set alongside [PORTAL_CORS_ALLOWED_ORIGINS](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-allowed-origins)=*. The Portal's CORS library (`rs/cors`) does not reject this combination at startup — it returns both `Access-Control-Allow-Origin: *` and `Access-Control-Allow-Credentials: true` in the response. The CORS specification forbids this combination, so the browser rejects the response. + + **Fix** + + Replace the wildcard with explicit allowed origins: + + ```ini + PORTAL_CORS_ALLOWED_ORIGINS=https://admin.example.com,https://app.example.com + PORTAL_CORS_ALLOW_CREDENTIALS=true + ``` + + See [Configure Portal Application CORS](/portal/how-to-guides/configure-cors#configure-portal-application-cors). + + + +--- + +## Related + +- [Configure CORS](/portal/how-to-guides/configure-cors) — set up Portal application CORS and Gateway API CORS +- [Portal configuration reference](/product-stack/tyk-enterprise-developer-portal/deploy/configuration) — full list of Portal environment variables diff --git a/product-stack/tyk-enterprise-developer-portal/deploy/configuration.mdx b/product-stack/tyk-enterprise-developer-portal/deploy/configuration.mdx index 418366927..c219aca3f 100644 --- a/product-stack/tyk-enterprise-developer-portal/deploy/configuration.mdx +++ b/product-stack/tyk-enterprise-developer-portal/deploy/configuration.mdx @@ -522,7 +522,7 @@ In other words, any cross-origin request will be denied. When enabled, the below **Config file:** CORS.AllowedOrigins
**Type:** `[string]`
**Description**: A list of origin domains to allow access from. Wildcards are also supported, e.g. [`*.foo.com`] will allow access from any domain that ends with *.foo.com*. -By default, no origins are allowed. To apply this setting, an array of the allowed origins. +When unset, all origins are allowed by default. Specify origins explicitly to restrict access. To configure using a configuration file: ```json