Skip to content

Commit 65e517e

Browse files
himeshsiriwardanahimeshsiriwardana
authored
Merge pull request #5737 from wso2/fixing-product-is-issue-26257-1764135912
Fix: Add CORS configuration documentation for all affected versions (Product IS issue #26257)
2 parents 29fcb2b + 7a77cfd commit 65e517e

File tree

6 files changed

+660
-0
lines changed

6 files changed

+660
-0
lines changed

‎en/identity-server/7.0.0/docs/deploy/configure-cors.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# CORS
2+
3+
Cross Origin Resource Sharing (CORS) is a mechanism that allows the web services to control the access to its resources from different origins. The WSO2 Identity Server (WSO2 IS) supports enforcing CORS at the tenant level. This is particularly useful when a Single Page Application (SPA) is needed to be connected to the IS.
4+
You can configure the CORS either at the server level during deployment or through the REST API. Any CORS preference that is configured at the server level can be overriden at the tenant level with the notable exception of the `Allowed CORS origins`. Any CORS origin that will be made allowed at the deployment stage through the `deployment.toml` will always be enabled for all the tenants under that particular WSO2 IS instance.
5+
6+
**The Identity Server must be running in the tenant URL mode in order for CORS to work.**
7+
8+
## CORS configurations
9+
10+
Following are the CORS configurations that are configurable.
11+
12+
<table>
13+
<thead>
14+
<tr class="header">
15+
<th>
16+
Name
17+
</th>
18+
<th>
19+
Description
20+
</th>
21+
<th>
22+
Configuration
23+
</th>
24+
</tr>
25+
</thead>
26+
<tbody>
27+
<tr class="odd">
28+
<td>
29+
<p>Allow generic HTTP requests</p>
30+
</td>
31+
<td>
32+
<p>If this is through, then the generic HTTP requests will be allowed to pass through to the WSO2 IS.
33+
Otherwise, only valid and accepted CORS requests will be allowed.</p>
34+
</td>
35+
<td>
36+
allow_generic_http_requests
37+
</td>
38+
</tr>
39+
<tr class="even">
40+
<td>
41+
<p>Allow any origin</p>
42+
</td>
43+
<td>
44+
<p>If through, the CORS valve will allow requests from any origin to the WSO2 IS while ignoring the whitelisted origins. Otherwise the 'Allowed origins' for the server/tenant is considered when allowing CORS requests.</p>
45+
</td>
46+
<td>
47+
allow_any_origin
48+
</td>
49+
</tr>
50+
<tr class="odd">
51+
<td>
52+
<p>Allowed origins</p>
53+
</td>
54+
<td>
55+
<p>A list of origins that will be allowed to make CORS requests to the WSO2 IS.</p>
56+
</td>
57+
<td>
58+
allowed_origins
59+
</td>
60+
</tr>
61+
<tr class="even">
62+
<td>
63+
<p>Allow subdomains</p>
64+
</td>
65+
<td>
66+
<p>If true, then CORS requests from subdomains of the configured CORS origins will be allowed to be made to the WSO2 IS.</p>
67+
</td>
68+
<td>
69+
allow_subdomains
70+
</td>
71+
</tr>
72+
<tr class="odd">
73+
<td>
74+
<p>Supported methods</p>
75+
</td>
76+
<td>
77+
<p>The supported HTTP methods. Requests for methods not included here will be refused by the CORS filter with a HTTP 405 'Method not allowed' response.</p>
78+
</td>
79+
<td>
80+
supported_methods
81+
</td>
82+
</tr>
83+
<tr class="even">
84+
<td>
85+
<p>Support any header</p>
86+
</td>
87+
<td>
88+
<p>If true, then CORS requests for any header will be supported while ignoring the 'Supported headers' property.</p>
89+
</td>
90+
<td>
91+
support_any_header
92+
</td>
93+
</tr>
94+
<tr class="odd">
95+
<td>
96+
<p>Supported headers</p>
97+
</td>
98+
<td>
99+
<p>This will only be consulted if the 'Support any header' property is false. In such case, the CORS requests can be made only for the headers included in this property.</p>
100+
</td>
101+
<td>
102+
supported_headers
103+
</td>
104+
</tr>
105+
<tr class="even">
106+
<td>
107+
<p>Exposed headers</p>
108+
</td>
109+
<td>
110+
<p>The non-simple response headers that the web browser should expose to the author of the CORS request.</p>
111+
</td>
112+
<td>
113+
exposed_headers
114+
</td>
115+
</tr>
116+
<tr class="odd">
117+
<td>
118+
<p>Supports credentials</p>
119+
</td>
120+
<td>
121+
<p>Whether user credentials, such as cookies, HTTP authentication or client-side certificates are supported.</p>
122+
</td>
123+
<td>
124+
supports_credentials
125+
</td>
126+
</tr>
127+
<tr class="even">
128+
<td>
129+
<p>Max age</p>
130+
</td>
131+
<td>
132+
<p>Indicates how long the results of a preflight request can be cached by the web client, in seconds.
133+
Here -1 means the age is unspecified.</p>
134+
</td>
135+
<td>
136+
max_age
137+
</td>
138+
</tr>
139+
<tr class="odd">
140+
<td>
141+
<p>Tag requests</p>
142+
</td>
143+
<td>
144+
<p>Enables HTTP servlet request tagging to provide CORS information to downstream handlers.</p>
145+
</td>
146+
<td>
147+
tag_requests
148+
</td>
149+
</tr>
150+
</tbody>
151+
</table>
152+
153+
## Configure CORS during deployment
154+
155+
All the above parameters can be configured at the server level through the `deployment.toml` file. A sample configuration is shown below.
156+
157+
```
158+
[cors]
159+
allow_generic_http_requests = true
160+
allow_any_origin = false
161+
allowed_origins = [
162+
"http://wso2.is"
163+
]
164+
allow_subdomains = false
165+
supported_methods = [
166+
"GET",
167+
"POST",
168+
"HEAD",
169+
"OPTIONS"
170+
]
171+
support_any_header = true
172+
supported_headers = []
173+
exposed_headers = []
174+
supports_credentials = true
175+
max_age = 3600
176+
tag_requests = false
177+
```
178+
179+
## Work with CORS through the REST APIs
180+
181+
The CORS functionality of the WSO2 Identity Server is managed by three different REST APIs.
182+
183+
### Server Configuration API
184+
185+
The [Server Configuration API]({{base_path}}/apis/server-configuration-management-api) is able to manage all the CORS configurations of a tenant except allowed CORS origins. These configurations cannot be set at the application level.
186+
187+
### Application Management API
188+
189+
Even if the enforcement happens at the tenant level, the developers are able to configure `Allowed CORS origins` for their applications individually through the [Application Management REST API]({{base_path}}/apis/application-rest-api). Any CORS origin that will be made allowed through this API will be automatically allowed for other applications under the tenant as the CORS can only be enforced at the tenant level under the tenant-url mode.
190+
191+
### CORS API
192+
193+
[CORS API]({{base_path}}/apis/cors-rest-api) allows the developers to view all the CORS origins configured per tenant. In addition, this API facilitates viewing the applications that are associated with a single CORS origin.

‎en/identity-server/7.0.0/docs/includes/cors-config.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
SAML2 POST Binding requires CORS configurations to be set up.
2+
3+
Before configuring the service provider, add the following configurations to the `deployment.toml` file found in `<IS_HOME>/repository/conf/`. Adding this configuration allows `HTTP POST` requests.
4+
5+
6+
``` toml
7+
[cors]
8+
allow_generic_http_requests = true
9+
allow_any_origin = false
10+
allowed_origins = [
11+
"http://localhost:8080"
12+
]
13+
allow_subdomains = false
14+
supported_methods = [
15+
"GET",
16+
"POST",
17+
"HEAD",
18+
"OPTIONS"
19+
]
20+
support_any_header = true
21+
supported_headers = []
22+
exposed_headers = []
23+
supports_credentials = true
24+
max_age = 3600
25+
tag_requests = false
26+
```
27+

0 commit comments

Comments
 (0)