Skip to content

Commit 08df9a5

Browse files
sharadregotisharadregoti
committed
Portal B20: apply editorial revisions to Configure CORS how-to
- Remove Tyk Classic API definition section; replace with a Note callout linking to the Classic CORS reference - Promote Tyk OAS as the sole primary path for Gateway CORS config - Convert bold-prefixed pseudo-steps to proper numbered list items with continuation content indented under each step - Replace env var column in optional settings table with config keys (CORS.MaxAge, CORS.AllowCredentials) linked to their exact anchors in the configuration reference; remove PORTAL_CORS_DEBUG (not in config reference); correct default allowed methods to GET and POST
1 parent cd285d4 commit 08df9a5

1 file changed

Lines changed: 113 additions & 142 deletions

File tree

‎portal/how-to-guides/configure-cors.mdx‎

Lines changed: 113 additions & 142 deletions
Original file line numberDiff line numberDiff line change
@@ -23,89 +23,88 @@ Portal application CORS controls which external origins may call the Portal's ow
2323
`PORTAL_CORS_ENABLE` defaults to `false`. All cross-origin requests to the Portal are rejected until you set this to `true`.
2424
</Warning>
2525

26-
**1. Enable CORS**
27-
28-
Set `PORTAL_CORS_ENABLE=true` on the Portal process.
29-
30-
<Tabs>
31-
<Tab title="Environment variable">
32-
```ini
33-
PORTAL_CORS_ENABLE=true
34-
```
35-
</Tab>
36-
<Tab title="Kubernetes (Helm)">
37-
```yaml
38-
extraEnvs:
39-
- name: PORTAL_CORS_ENABLE
40-
value: "true"
41-
```
42-
</Tab>
43-
</Tabs>
44-
45-
**2. Set allowed origins**
46-
47-
Set `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.
48-
49-
{/* TODO: Verify the default behavior when PORTAL_CORS_ALLOWED_ORIGINS is unset. Code analysis (rs/cors library) indicates an empty slice allows all origins. The configuration reference states no origins are allowed by default. Confirm with the Portal team before documenting a specific default. */}
50-
51-
<Tabs>
52-
<Tab title="Environment variable">
53-
```ini
54-
PORTAL_CORS_ALLOWED_ORIGINS=https://admin.example.com,https://developer.example.com
55-
```
56-
</Tab>
57-
<Tab title="Kubernetes (Helm)">
58-
```yaml
59-
extraEnvs:
60-
- name: PORTAL_CORS_ALLOWED_ORIGINS
61-
value: "https://admin.example.com,https://developer.example.com"
62-
```
63-
</Tab>
64-
</Tabs>
65-
66-
<Warning>
67-
Do not set `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.
68-
</Warning>
69-
70-
**3. Set allowed headers and methods**
71-
72-
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`, `POST`, and `HEAD`.
73-
74-
<Tabs>
75-
<Tab title="Environment variable">
76-
```ini
77-
PORTAL_CORS_ALLOWED_HEADERS=Authorization,Content-Type,X-Requested-With
78-
PORTAL_CORS_ALLOWED_METHODS=GET,POST,PUT,DELETE,OPTIONS
79-
```
80-
</Tab>
81-
<Tab title="Kubernetes (Helm)">
82-
```yaml
83-
extraEnvs:
84-
- name: PORTAL_CORS_ALLOWED_HEADERS
85-
value: "Authorization,Content-Type,X-Requested-With"
86-
- name: PORTAL_CORS_ALLOWED_METHODS
87-
value: "GET,POST,PUT,DELETE,OPTIONS"
88-
```
89-
</Tab>
90-
</Tabs>
91-
92-
**4. (Optional) Configure additional CORS settings**
93-
94-
| Variable | Type | Default | Description |
95-
|---|---|---|---|
96-
| `PORTAL_CORS_MAX_AGE` | `int` | `0` | How long, in seconds, browsers may cache the preflight response. A positive value reduces preflight round trips. |
97-
| `PORTAL_CORS_ALLOW_CREDENTIALS` | `bool` | `false` | Whether the Portal includes credentials (cookies, HTTP authentication) in CORS responses. |
98-
| `PORTAL_CORS_DEBUG` | `bool` | `false` | Logs CORS decisions to the Portal output. Enable temporarily when diagnosing CORS issues. |
99-
100-
**5. Restart the Portal**
101-
102-
Restart the Portal process or pod for the environment variable changes to take effect.
103-
104-
**6. Verify**
105-
106-
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.
107-
108-
{/* TODO: Screenshot — Portal response headers in browser DevTools Network tab showing Access-Control-Allow-Origin header present */}
26+
1. **Enable CORS**
27+
28+
Set `PORTAL_CORS_ENABLE=true` on the Portal process.
29+
30+
<Tabs>
31+
<Tab title="Environment variable">
32+
```ini
33+
PORTAL_CORS_ENABLE=true
34+
```
35+
</Tab>
36+
<Tab title="Kubernetes (Helm)">
37+
```yaml
38+
extraEnvs:
39+
- name: PORTAL_CORS_ENABLE
40+
value: "true"
41+
```
42+
</Tab>
43+
</Tabs>
44+
45+
2. **Set allowed origins**
46+
47+
Set `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.
48+
49+
{/* TODO: Verify the default behavior when PORTAL_CORS_ALLOWED_ORIGINS is unset. Code analysis (rs/cors library) indicates an empty slice allows all origins. The configuration reference states no origins are allowed by default. Confirm with the Portal team before documenting a specific default. */}
50+
51+
<Tabs>
52+
<Tab title="Environment variable">
53+
```ini
54+
PORTAL_CORS_ALLOWED_ORIGINS=https://admin.example.com,https://developer.example.com
55+
```
56+
</Tab>
57+
<Tab title="Kubernetes (Helm)">
58+
```yaml
59+
extraEnvs:
60+
- name: PORTAL_CORS_ALLOWED_ORIGINS
61+
value: "https://admin.example.com,https://developer.example.com"
62+
```
63+
</Tab>
64+
</Tabs>
65+
66+
<Warning>
67+
Do not set `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.
68+
</Warning>
69+
70+
3. **Set allowed headers and methods**
71+
72+
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`.
73+
74+
<Tabs>
75+
<Tab title="Environment variable">
76+
```ini
77+
PORTAL_CORS_ALLOWED_HEADERS=Authorization,Content-Type,X-Requested-With
78+
PORTAL_CORS_ALLOWED_METHODS=GET,POST,PUT,DELETE,OPTIONS
79+
```
80+
</Tab>
81+
<Tab title="Kubernetes (Helm)">
82+
```yaml
83+
extraEnvs:
84+
- name: PORTAL_CORS_ALLOWED_HEADERS
85+
value: "Authorization,Content-Type,X-Requested-With"
86+
- name: PORTAL_CORS_ALLOWED_METHODS
87+
value: "GET,POST,PUT,DELETE,OPTIONS"
88+
```
89+
</Tab>
90+
</Tabs>
91+
92+
4. **(Optional) Configure additional CORS settings**
93+
94+
| Config key | Type | Default | Description |
95+
|---|---|---|---|
96+
| [`CORS.MaxAge`](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-max-age) | `int` | `0` | How long, in seconds, browsers may cache the preflight response. A positive value reduces preflight round trips. |
97+
| [`CORS.AllowCredentials`](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-allow-credentials) | `bool` | `false` | Whether the Portal includes credentials (cookies, HTTP authentication) in CORS responses. |
98+
99+
5. **Restart the Portal**
100+
101+
Restart the Portal process or pod for the environment variable changes to take effect.
102+
103+
6. **Verify**
104+
105+
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.
106+
107+
{/* TODO: Screenshot — Portal response headers in browser DevTools Network tab showing Access-Control-Allow-Origin header present */}
109108

110109
---
111110

@@ -117,74 +116,46 @@ When a consumer tests an API using the API Playground on the Live Portal, the br
117116
**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.
118117
</Warning>
119118

120-
### Tyk Classic API definition
121-
122-
**1. Open the API in Tyk Dashboard**
123-
124-
In Tyk Dashboard, go to **APIs** and open the API that belongs to your Portal API product.
125-
126-
**2. Enable CORS**
127-
128-
Go to the **Advanced Options** tab and expand the **CORS** section. Enable the **CORS** toggle.
129-
130-
{/* TODO: Screenshot — Tyk Dashboard API designer, Advanced Options tab, CORS section enabled, showing the fields described in step 3 */}
131-
132-
**3. Set allowed origins, methods, and headers**
133-
134-
- **Allowed Origins**: Add the full URL of your Live Portal, for example `https://portal.example.com`.
135-
- **Allowed Methods**: Add all HTTP methods the API supports. Include at minimum `GET`, `POST`, and `OPTIONS`.
136-
- **Allowed Headers**: Add `Origin`, `Content-Type`, and the authentication header your API uses, for example `Authorization`.
137-
138-
**4. Configure options passthrough**
139-
140-
Leave **Options Passthrough** disabled (the default). When disabled, the Gateway intercepts `OPTIONS` preflight requests, adds CORS headers, and returns `200 OK` without forwarding to the upstream or enforcing authentication. Enable Options Passthrough only if your upstream service handles CORS natively.
141-
142-
**5. Save the API**
143-
144-
Click **Update** to save the API definition.
145-
146-
**6. Verify**
147-
148-
Open the API Playground on your Live Portal and send a test request. The request should complete without CORS errors in the browser console.
149-
150-
### Tyk OAS API definition
119+
1. **Locate the CORS block**
151120

152-
**1. Locate the CORS block**
121+
In a Tyk OAS API definition, CORS configuration sits under `x-tyk-api-gateway.middleware.global.cors`.
153122

154-
In a Tyk OAS API definition, CORS configuration sits under `x-tyk-api-gateway.middleware.global.cors`.
123+
2. **Add the CORS configuration**
155124

156-
**2. Add the CORS configuration**
125+
```yaml expandable
126+
x-tyk-api-gateway:
127+
middleware:
128+
global:
129+
cors:
130+
enabled: true
131+
allowedOrigins:
132+
- "https://portal.example.com"
133+
allowedMethods:
134+
- GET
135+
- POST
136+
- PUT
137+
- DELETE
138+
- OPTIONS
139+
allowedHeaders:
140+
- Origin
141+
- Content-Type
142+
- Authorization
143+
optionsPassthrough: false
144+
```
157145

158-
```yaml expandable
159-
x-tyk-api-gateway:
160-
middleware:
161-
global:
162-
cors:
163-
enabled: true
164-
allowedOrigins:
165-
- "https://portal.example.com"
166-
allowedMethods:
167-
- GET
168-
- POST
169-
- PUT
170-
- DELETE
171-
- OPTIONS
172-
allowedHeaders:
173-
- Origin
174-
- Content-Type
175-
- Authorization
176-
optionsPassthrough: false
177-
```
146+
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.
178147

179-
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.
148+
3. **Import or update the API**
180149

181-
**3. Import or update the API**
150+
Import the updated definition in Tyk Dashboard or update the API via the Tyk Dashboard API.
182151

183-
Import the updated definition in Tyk Dashboard or update the API via the Tyk Dashboard API.
152+
4. **Verify**
184153

185-
**4. Verify**
154+
Open the API Playground on your Live Portal and send a test request. The request should complete without CORS errors in the browser console.
186155

187-
Open the API Playground on your Live Portal and send a test request. The request should complete without CORS errors in the browser console.
156+
<Note>
157+
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.
158+
</Note>
188159

189160
---
190161

0 commit comments

Comments
 (0)
⚡