Web IDE extension host domain

The extension host domain is a wildcard domain name used by the Web IDE to isolate third-party code installed using Extension Marketplace. The Web IDE relies on the web browser’s same origin policy to run extensions in a sandbox environment.

GitLab provides a default extension host domain cdn.web-ide.gitlab-static.net that is available to all GitLab offerings by default. This domain name points to an external HTTP server that hosts VS Code static assets. In offline environments, a user’s web browser can’t connect to this external HTTP server which, in turn, limits the Web IDE’s capabilities.

To circumvent this limitation, GitLab instance administrators can set up a custom extension host domain. The custom extension host domain points to the GitLab instance itself which can also serve the VS Code static assets just like the default solution.

Set up custom extension host domain

Prerequisites:

• You must be an administrator.

These instructions are for a Linux package installation that uses the default NGINX installation. GitLab administrators and DevOps engineers should adapt this guide to other installation methods.

1. Follow the guide to insert custom settings into the NGINX configuration to add a server block. This block configures NGINX to handle requests for the extension host domain. The following code snippet provides a reference configuration. Replace <extension-host-domain-placeholder> with the wildcard domain name for your Web IDE extension host domain:

   server {
     listen *:443 ssl;
     server_name *.<extension-host-domain-placeholder>;
   
     ssl_certificate /etc/gitlab/ssl/<extension-host-domain-placeholder>.pem;
     ssl_certificate_key /etc/gitlab/ssl/<extension-host-domain-placeholder>-key.pem;
   
     ## Individual nginx logs for this GitLab vhost
     access_log  /var/log/gitlab/nginx/gitlab_access.log gitlab_access;
     error_log   /var/log/gitlab/nginx/gitlab_error.log;
   
     location /assets/ {
       client_max_body_size 0;
       gzip off;
   
       proxy_read_timeout      300;
       proxy_connect_timeout   300;
       proxy_redirect          off;
   
       proxy_http_version 1.1;
   
       proxy_set_header    Host                $http_host;
       proxy_set_header    X-Real-IP           $remote_addr;
       proxy_set_header    X-Forwarded-For     $remote_addr;
       proxy_set_header    X-Forwarded-Proto   $scheme;
   
       proxy_pass http://gitlab-workhorse;
     }
   }

2. Save the file and reconfigure GitLab for the changes to take effect. Then, open the GitLab application.

3. In the upper-right corner, select Admin.

4. Select Settings > General.

5. Expand Web IDE.

6. In the Extension host domain text box, enter the custom extension host domain.

7. Select Save changes.

After saving the changes, you can open a project in the Web IDE to verify that the custom extension host is used by the editor.

Single origin fallback

By default, the Web IDE runs in multi-origin mode, which serves VS Code static assets from a separate extension host domain. This isolation prevents malicious actors from exploiting the extension host to make authenticated requests to the GitLab instance.

However, when the extension host domain is unreachable due to network or CORS restrictions, the Web IDE automatically falls back to single-origin mode. In this mode, the WebIDE serves VS Code assets from the same origin as the GitLab application, which increases the attack surface and creates security vulnerabilities.

The Enable single origin fallback setting controls whether the Web IDE can fall back to single-origin mode when the extension host domain is unreachable.

Prerequisites:

• Administrator access.

To configure this setting:

1. In the upper-right corner, select Admin.
2. Select Settings > General.
3. Expand Web IDE.
4. Select or clear the Enable single origin fallback checkbox.
5. Select Save changes.