Skip to content

Commit 4a0ac13

Browse files
code-ashercode-asher
authored
docs: document CORS behavior between forwarded apps (coder#7944)
* docs: document CORS behavior * docs: move CORS documentation under dashboard section None of this applies to ports forwarded in other ways.
1 parent 6ac7d86 commit 4a0ac13

File tree

1 file changed

+111
-0
lines changed

1 file changed

+111
-0
lines changed

‎docs/networking/port-forwarding.md

+111
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,117 @@ Valid `share` values include `owner` - private to the user, `authenticated` - ac
8484

8585
![Port forwarding from an app in the UI](../images/coderapp-port-forward.png)
8686

87+
### Cross-origin resource sharing (CORS)
88+
89+
When forwarding via the dashboard, Coder automatically sets headers that allow
90+
requests between separately forwarded applications belonging to the same user.
91+
92+
When forwarding through other methods the application itself will need to set
93+
its own CORS headers if they are being forwarded through different origins since
94+
Coder does not intercept these cases. See below for the required headers.
95+
96+
#### Authentication
97+
98+
Since ports forwarded through the dashboard are private, cross-origin requests
99+
must include credentials (set `credentials: "include"` if using `fetch`) or the
100+
requests cannot be authenticated and you will see an error resembling the
101+
following:
102+
103+
> Access to fetch at 'https://dev.coder.com/api/v2/applications/auth-redirect' from origin 'https://8000--dev--user--apps.dev.coder.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.
104+
105+
#### Headers
106+
107+
Below is a list of the cross-origin headers Coder sets with example values:
108+
109+
```
110+
access-control-allow-credentials: true
111+
access-control-allow-methods: PUT
112+
access-control-allow-headers: X-Custom-Header
113+
access-control-allow-origin: https://8000--dev--user--apps.dev.coder.com
114+
vary: Origin
115+
vary: Access-Control-Request-Method
116+
vary: Access-Control-Request-Headers
117+
```
118+
119+
The allowed origin will be set to the origin provided by the browser if the
120+
users are identical. Credentials are allowed and the allowed methods and headers
121+
will echo whatever the request sends.
122+
123+
#### Configuration
124+
125+
These cross-origin headers are not configurable by administrative settings.
126+
127+
Applications can set their own headers which will override the defaults but this
128+
will only apply to non-preflight requests. Preflight requests through the
129+
dashboard are never sent to applications and thus cannot be modified by
130+
them. Read more about the difference between simple requests and requests that
131+
trigger preflights
132+
[here](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests).
133+
134+
#### Allowed by default
135+
136+
<table class="tg">
137+
<thead>
138+
<tr>
139+
<th class="tg-0pky" rowspan="2"></th>
140+
<th class="tg-0pky" rowspan="3"></th>
141+
<th class="tg-0pky">From</th>
142+
<th class="tg-0pky" colspan="3">Alice</th>
143+
<th class="tg-0pky">Bob</th>
144+
</tr>
145+
<tr>
146+
<th class="tg-0pky" rowspan="2"></th>
147+
<th class="tg-0pky">Workspace 1</th>
148+
<th class="tg-0pky" colspan="2">Workspace 2</th>
149+
<th class="tg-0pky">Workspace 3</th>
150+
</tr>
151+
<tr>
152+
<th class="tg-0pky">To</th>
153+
<th class="tg-0pky">App A</th>
154+
<th class="tg-0pky">App B</th>
155+
<th class="tg-0pky">App C</th>
156+
<th class="tg-0pky">App D</th>
157+
</tr>
158+
</thead>
159+
<tbody>
160+
<tr>
161+
<td class="tg-0pky" rowspan="3">Alice</td>
162+
<td class="tg-0pky" rowspan="2">Workspace 1</td>
163+
<td class="tg-0pky">App A</td>
164+
<td class="tg-0pky">✅</td>
165+
<td class="tg-0pky">✅<span style="font-weight:400;font-style:normal">*</span></td>
166+
<td class="tg-0pky">✅<span style="font-weight:400;font-style:normal">*</span></td>
167+
<td class="tg-0pky">❌</td>
168+
</tr>
169+
<tr>
170+
<td class="tg-0pky">App B</td>
171+
<td class="tg-0pky">✅*</td>
172+
<td class="tg-0pky">✅</td>
173+
<td class="tg-0pky">✅<span style="font-weight:400;font-style:normal">*</span></td>
174+
<td class="tg-0pky">❌</td>
175+
</tr>
176+
<tr>
177+
<td class="tg-0pky">Workspace 2</td>
178+
<td class="tg-0pky">App C</td>
179+
<td class="tg-0pky">✅<span style="font-weight:400;font-style:normal">*</span></td>
180+
<td class="tg-0pky">✅<span style="font-weight:400;font-style:normal">*</span></td>
181+
<td class="tg-0pky">✅</td>
182+
<td class="tg-0pky">❌</td>
183+
</tr>
184+
<tr>
185+
<td class="tg-0pky">Bob</td>
186+
<td class="tg-0pky">Workspace 3</td>
187+
<td class="tg-0pky">App D</td>
188+
<td class="tg-0pky">❌</td>
189+
<td class="tg-0pky">❌</td>
190+
<td class="tg-0pky">❌</td>
191+
<td class="tg-0pky">✅</td>
192+
</tr>
193+
</tbody>
194+
</table>
195+
196+
> '\*' means `credentials: "include"` is required
197+
87198
## SSH
88199

89200
First, [configure SSH](../ides.md#ssh-configuration) on your

0 commit comments

Comments
 (0)