Developing for HTTPS with self-signed certificates

When developing on the Neuron® in a local environment, you typically don’t have access to a domain name accessible from the Internet. You can therefore not create a valid server certificate for the machine, something that is required for enabling encryption using protocols such as HTTP, XMPP, etc. If you do development that require such encryption, you can either choose to develop on a machine published on the Internet (not recommended), or temporarily use a self-signed certificate on your local version of the Neuron®, to enable encryption.

An example of task that requires use of HTTPS, is web access using HTTP/2. Using a browser to navigate your local Neuron®, typically results in the browser defaulting to HTTP/1.1. The original mechanism of upgrading a connection to HTTP/2 was obsoleted for unencrypted communication, so there’s no automatic manner for the browser to know it can upgrade. The upgrade mechanism typically used, requires use of TLS and ALPN, where the server states what protocols it supports. The browser therefore knows immediately which protocol to use, without having to perform a costly upgrade.

Another example that requires use of HTTPS, are connections that require authentication using mTLS.

For security reasons, uploading server certificates is not permitted in the GUIs of the Neuron®. Certificates are automatically created and maintained by the Neuron® using the ACME protocol, and certificate authorities on the Internet supporting the ACME protocol. The certificates are then maintained by the Neuron® itself and stored in its internal storage, to avoid the certificate being used elsewhere. To use a self-signed certificate therefore, we need to use script.

Checking if HTTPS is enabled

To check if HTTPS is enabled already on your machine, type the following in the script prompt:

Gateway.HttpServer.OpenHttpsPorts

If an empty array is returned, HTTPS is not enabled. If it contains one or more integers, they represent the port numbers you can use to access the Neuron® using HTTPS (i.e. HTTPS is enabled).

Creating a self-signed certificate

You can use the .NET runtime to create a self-signed certificate for your localmachine (localhost) for use in development. Type the following in a command-prompt, where you replace the FILENAME and PASSWORD with the filename you want to get the certificate exported to, and the password you want to use to protect the certificate:

dotnet dev-certs https -ep FILENAME -p PASSWORD --format Pfx

Configuring the Neuron®

As the admin interface does not permit uploading of custom certificates, we need to configure the Neuron® using script. The following example illustrates the properties that must be set:

DConfig:=DomainConfiguration.Instance;
DConfig.Domain:="localhost";
DConfig.UseDomainName:=true;
DConfig.UseEncryption:=true;
DConfig.PFX:=LoadFile(FILENAME);
DConfig.Password:=PASSWORD;
UpdateObject(DConfig);

For this script to have an effect, you need to use a broker with a build-time of 2024-12-12 or later.

Port configuration in Gateway.config

For the web server to open one or more HTTPS ports, they must be configured in gateway.config. From the Admin page, under Data and Sources & Nodes, you find the gateway configuration and port settings. There must be at least a port configuration for HTTPS, as illustrated in the following figure:

Restarting Neuron®

The configuration is applied when Neuron® is started. So for the changed to take effect, you need to restart the Neuron®. Once it has restarted, you can test the web server has opened at HTTP ports for incoming communication by executing the following script again:

Gateway.HttpServer.OpenHttpsPorts

Once you have confirmed the ports are open, you can direct a browser to the Neuron® using the domain localhost and the corresponding port, if different from the default HTTPS port 443.

Security Notice

Self-signed certificates should not be trusted, or installed or configured in the operating system to be trusted, as this would create a vulnerability that can be exploited. Instead, when navigating to the local development Neuron® using HTTPS, you will get a warning and the browser will initially refuse to show the contents. Accept the warning and tell the browser to view the content anyway.

Removing Certificate

To remove the certificate, and disable encryption on your local development server, you execute the following script:

DConfig:=DomainConfiguration.Instance;
DConfig.Domain:=null;
DConfig.UseDomainName:=false;
DConfig.UseEncryption:=false;
DConfig.PFX:=null;
DConfig.Password:=null;
UpdateObject(DConfig);

After executing the script, you need to restart the Neuron®.

#tutorial, #development, #neuron, #security

Development Neurons and Neuro-Access integration

If you are developing a local project on a locally hosted development Neuron®, and you want to integrate Neuro-Access to let users to login to show protected pages, your development Neuron® must be configured to permit this. This is done by adding the XMPP addresses (JIDs) of the apps involved during development to the Roster of the development Neuron®. On published Neurons, this is not necessary, as they are federated and use their domain names to interconnect with other Neurons (such as the Neurons serving your Neuro-Access connections). But a developer Neuron® cannot do this, as it most probably lacks both a domain name and a public IP address. Communication in this case, is done using the XMPP Addresses (JIDs) of the Neurons, as clients to their parent Neurons (which are federated). For communication to pass in this case, and not be rejected as invalid, the sender has to reside in the Neurons Roster (accessible from the Admin page, in the Communication section).

#neuron, #neuro-access, #development