What is a secure context?

A secure context is a browsing context that meets certain minimum browser security requirements. In modern browsers, your site can access powerful APIs only if you load it in a secure context (window.isSecureContext). If you don’t load your site in a secure context, those APIs are unavailable or partially degraded.

When is a browser context considered secure?

A browsing context is considered secure when its document is loaded securely. A document is loaded securely in these cases:

  • The document is loaded over HTTPS.

  • The document is loaded from localhost.

If your application runs in an <iframe>, the parent document of the <iframe> must also be secure for the <iframe> to be considered secure. Check the MDN documentation for more details.

Why does LuciadRIA require a secure context?

LuciadRIA uses WebGPU for hardware-accelerated rendering. Browsers restrict usage of the WebGPU API to secure contexts.

Running your application in a secure context

To run your web application in a secure context, you can choose to:

  • Serve your application over HTTPS, mostly relevant for deployment.

  • Serve your application from localhost, typically relevant for local development only.

Secure the browsing context for local development

When you’re developing locally, the easiest way to secure the browsing context is to serve your application from localhost. This is also the default configuration of the LuciadRIA sampleserver in the release, as well as the Vite dev server used for development in LuciadRIA samples.

If you want to access your application from a different host name, you can set up HTTPS for local development.

Secure the browsing context for deployment

When deploying your application, you must serve it over HTTPS. You typically need to obtain a certificate, which your organization may already have, and configure your server to use it. An alternative is running your server behind a reverse proxy that handles HTTPS.

Checking if your application is running in a secure context

You can verify that your application is running in a secure context by checking the value of window.isSecureContext in your browser’s developer console. If it returns true, your application is running in a secure context. If it returns false, your application isn’t running in a secure context. 

if (!window.isSecureContext) {
  console.warn("Not a secure context. WebGPU unavailable.");
}
if (!("gpu" in navigator)) {
  console.info("WebGPU not supported or not enabled.");
}

Setting up HTTPS for local development

To set up HTTPS for local development, you need to:

Your organization may already have a trusted certificate that you can use for local development instead of a self-signed one.

Configure the Vite dev server for HTTPS

If you’re using the Vite dev server that comes with the LuciadRIA samples, you can enable HTTPS with an automatically generated certificate or with your own certificate.

Using an automatically generated certificate

Enable HTTPS and generate a self-signed certificate for localhost by setting the RIA_VITE_HTTPS environment variable before running npm run dev: 

# On Mac and Linux:
RIA_VITE_HTTPS=1 npm run dev

# On Windows (cmd.exe):
set RIA_VITE_HTTPS=1&&npm run dev

This uses the @vitejs/plugin-basic-ssl plugin to generate the certificate, cached at node_modules/.vite-samples-cache/basic-ssl/_cert.pem in the LuciadRIA distribution root. The same certificate is reused across dev server restarts, as long as it hasn’t expired.

Using your own certificate

If you already have a certificate, for example, one issued by your organization, or you want more control over the certificate than the automatically generated one offers, you can configure Vite’s native server.https option in your sample’s own vite.config.ts file instead.

  1. If you don’t have a certificate yet, generate a self-signed one for localhost:

    1. Create a localhost.cnf file with this content: 

      [dn]
CN=localhost
[req]
distinguished_name = dn
[EXT]
subjectAltName=DNS:localhost
keyUsage=digitalSignature
extendedKeyUsage=serverAuth

    2. Run this openssl command to generate a private key and self-signed certificate for localhost: 

      openssl req -x509 -out localhost.crt -keyout localhost.key \
  -newkey rsa:2048 -nodes -sha256 \
  -days 365 \
  -subj "/CN=localhost" -extensions EXT -config localhost.cnf

      The result is a private key in localhost.key and a self-signed certificate in localhost.crt, valid for 365 days.

      If you’re using a different host name, you must generate a certificate for that host name instead. For example, if you’re using mymachine.local, replace localhost with mymachine.local in the openssl command above.

  2. Add @types/node as a dev dependency, since reading the certificate files uses Node’s fs module: 

    npm install @types/node --save-dev

  3. Merge the server.https option into your sample’s vite.config.ts: 

    import fs from "fs";
import {mergeConfig} from "vite";
import createSampleViteConfig from "@luciad/ria-toolbox-config/vite.config.ts";

const baseConfig = createSampleViteConfig(import.meta.url);

export default (env) => mergeConfig(baseConfig(env), {
  server: {
    https: {
      key: fs.readFileSync("path/to/localhost.key"),
      cert: fs.readFileSync("path/to/localhost.crt"),
    },
  },
});

Consult the Vite server.https documentation for more information.

Configure the LuciadRIA sample server for HTTPS

To enable HTTPS on the LuciadRIA sample server, you must create a keystore containing a certificate and private key.

If you used the automatically generated certificate, reuse it: _cert.pem at node_modules/.vite-samples-cache/basic-ssl/_cert.pem is a single file containing both the certificate and the private key, so pass it to both -in and -inkey: 

openssl pkcs12 -export -in node_modules/.vite-samples-cache/basic-ssl/_cert.pem -inkey node_modules/.vite-samples-cache/basic-ssl/_cert.pem -out localhost.p12 -name localhost

If you used your own certificate instead, reuse its certificate and key files:

openssl pkcs12 -export -in localhost.crt -inkey localhost.key -out localhost.p12 -name localhost

Then, you must set these environment variables to enable HTTPS in the sample server:

  • RIA_SAMPLE_SERVER_HTTPS=true To enable HTTPS, defaults to false.

  • RIA_SAMPLE_SERVER_KEYSTORE=path/to/localhost.p12 Required for HTTPS, the path to the keystore file you created.

  • RIA_SAMPLE_SERVER_KEYSTORE_PASSWORD=<password you used when creating the keystore> Required for HTTPS. The password you used when creating the keystore

  • RIA_SAMPLE_SERVER_KEYSTORE_TYPE=<keystore type"> Optional. The type of the keystore, defaults to "PKCS12".

  • RIA_SAMPLE_SERVER_KEYSTORE_ALIAS=<alias> Optional. The name of the certificate in the keystore. The same as the -name value in the openssl command above, defaults to "localhost".

You can set these variables in the startSampleServer.sh or startSampleServer.bat script. Alternatively, you can configure them system-wide in your environment, so you don’t have to set them every time you install a new LuciadRIA release.

After enabling HTTPS, make sure to access the sampleserver using https:// instead of http://.

Other common web servers

For other common web servers, see this documentation:

Trust the self-signed certificate in your browser

To prevent browser warnings about untrusted certificates, you must trust the self-signed certificate in your browser.

https certificate error
Figure 1. If the certificate isn’t trusted, your browser shows you a warning like this one.

The browser you’re using determines the steps required for trusting self-signed certificates:

Google Chrome

  1. Open chrome://certificate-manager.

  2. Click Local certificates.

  3. Click Installed by you under Custom.

  4. Under Trusted Certificates, click Import and select the certificate file you generated in Configure the Vite dev server for HTTPS (_cert.pem or localhost.crt if you used your own certificate).

Mozilla Firefox

  1. Make sure that the web server is running with the self-signed certificate.

  2. Open about:preferences#privacy in Firefox.

  3. Scroll down to Certificates and click View Certificates…​.

  4. In the Servers tab, click Add Exception…​.

  5. Enter the URL of the web server, for example https://localhost:3001, in the Location field and click Get Certificate.

  6. Select the Permanently store this exception checkbox and click Confirm Security Exception.

Safari

  1. Open the certificate file you generated in Configure the Vite dev server for HTTPS (_cert.pem or localhost.crt if you used your own certificate). This should open the Keychain app.

  2. Add the certificate to the System keychain.

  3. In the Keychain app, select System in the left sidebar.

  4. Find the localhost certificate in the list on the Certificates tab and double-click it.

  5. In the certificate details, expand the Trust section.

  6. Set When using this certificate to Always Trust.

  7. Close the certificate details and enter your password to save the changes.

After trusting the certificate, you can access your application without any warnings.