diff --git a/docs/networking/port-forwarding.md b/docs/networking/port-forwarding.md index a5ae27a6e1671..50d61c52736df 100644 --- a/docs/networking/port-forwarding.md +++ b/docs/networking/port-forwarding.md @@ -84,6 +84,117 @@ Valid `share` values include `owner` - private to the user, `authenticated` - ac ![Port forwarding from an app in the UI](../images/coderapp-port-forward.png) +### Cross-origin resource sharing (CORS) + +When forwarding via the dashboard, Coder automatically sets headers that allow +requests between separately forwarded applications belonging to the same user. + +When forwarding through other methods the application itself will need to set +its own CORS headers if they are being forwarded through different origins since +Coder does not intercept these cases. See below for the required headers. + +#### Authentication + +Since ports forwarded through the dashboard are private, cross-origin requests +must include credentials (set `credentials: "include"` if using `fetch`) or the +requests cannot be authenticated and you will see an error resembling the +following: + +> 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. + +#### Headers + +Below is a list of the cross-origin headers Coder sets with example values: + +``` +access-control-allow-credentials: true +access-control-allow-methods: PUT +access-control-allow-headers: X-Custom-Header +access-control-allow-origin: https://8000--dev--user--apps.dev.coder.com +vary: Origin +vary: Access-Control-Request-Method +vary: Access-Control-Request-Headers +``` + +The allowed origin will be set to the origin provided by the browser if the +users are identical. Credentials are allowed and the allowed methods and headers +will echo whatever the request sends. + +#### Configuration + +These cross-origin headers are not configurable by administrative settings. + +Applications can set their own headers which will override the defaults but this +will only apply to non-preflight requests. Preflight requests through the +dashboard are never sent to applications and thus cannot be modified by +them. Read more about the difference between simple requests and requests that +trigger preflights +[here](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests). + +#### Allowed by default + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FromAliceBob
Workspace 1Workspace 2Workspace 3
ToApp AApp BApp CApp D
AliceWorkspace 1App A✅✅*✅*❌
App B✅*✅✅*❌
Workspace 2App C✅*✅*✅❌
BobWorkspace 3App D❌❌❌✅
+ +> '\*' means `credentials: "include"` is required + ## SSH First, [configure SSH](../ides.md#ssh-configuration) on your