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 webpack-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. In that case, you can skip the first step, and use a certificate issued by your organization instead of a self-signed certificate.

Generate a self-signed certificate for localhost

To generate a private key and self-signed certificate for localhost in a simple way:

  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 generated private key in localhost.key and a self-signed certificate in localhost.crt. The certificate is valid for 365 days. You can now configure your local web server with localhost.crt and localhost.key, and trust localhost.crt in your browser.

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, you must replace localhost with mymachine.local in the openssl command above.

Configure a local web server for HTTPS

You must configure your local web server to use the self-signed certificate and private key you generated in Generate a self-signed certificate for localhost. The configuration depends on the web server you’re using.

Configure the LuciadRIA samples webpack-dev-server for HTTPS

If you’re using the webpack-dev-server that comes with the LuciadRIA samples, you can run it with HTTPS by adding the --server-type=https argument to the npm run dev command. You can also specify the paths to your certificate and key with the --server-options-cert and --server-options-key arguments. 

npm run dev -- --server-type=https --server-options-cert=path/to/localhost.crt --server-options-key=path/to/localhost.key

If you don’t specify these arguments, the server generates a new self-signed certificate.

Use the --server-options-cert and --server-options-key arguments to use the same certificate and key every time you start the server. This way, you only need to trust the certificate in your browser once.

It’s also recommended to use command line tool arguments instead of modifying the webpack.config.js file. The webpack configuration file is typically shared with other developers, who are likely to use different certificates and keys.

You can also modify the webpack.config.js file of your sample to always use HTTPS. To do so, add the following to the devServer configuration of your webpack.config.js file: 

server: {
  type: 'https',
  key: "path/to/localhost.key",
  cert: "path/to/localhost.crt",
}

Consult the webpack devServer.server 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 your self-signed certificate and private key. You can do so with this openssl command: 

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 localhost.crt file you generated earlier.

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 localhost.crt file you generated earlier. 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.