.. _ln_manager_webui_https_certificates:

*************************
Web UI HTTPS Certificates
*************************

The manager can serve the Web UI over HTTPS on its normal manager port when
:ref:`webui_https_cert_file <instance/webui_https_cert_file>` is configured.
This is mainly useful when the browser is not running on the same host as the
manager, because several browser features are restricted to secure contexts.

For typical lab use, the browser URL will often contain a local host name, for
example:

.. code-block:: text

   https://rmc-lx0001:43809/

A browser checks 2 things:

* the certificate must be trusted by the browser or operating system
* the certificate must be valid for the exact name used in the URL

If the browser opens ``https://rmc-lx0001:43809/``, the certificate must be
valid for ``rmc-lx0001``. The TCP port is not part of the certificate name
check, so the same certificate can be used on any manager port on that host.

Local Lab Host Names
====================

For a host name such as ``rmc-lx0001`` or ``testbench-control``, a public
certificate service normally cannot help directly. [#letsencrypt-public-dns]_
Those names are not public DNS names. They may resolve only inside the lab
network, through local DNS, ``/etc/hosts``, VPN configuration, or site-specific
name service.

.. [#letsencrypt-public-dns] If the manager is reached through a real public
   DNS name that you control, a service such as Let's Encrypt can issue a
   browser-trusted certificate for that public name. This is not the usual
   setup for bare lab host names such as ``rmc-lx0001``.

The usual lab solution is a local certificate authority:

1. Create or use a local lab certificate authority.
2. Make the browser machines trust that local certificate authority.
3. Issue a server certificate for each manager host name users will open, for
   example ``rmc-lx0001``.
4. Configure the manager to use the generated certificate and private key.

   .. code-block:: lnc

      instance
      # ...
      webui_https_cert_file: /path/to/rmc-lx0001.crt
      webui_https_key_file: /path/to/rmc-lx0001.key

The certificate should contain the host name as a DNS subject alternative name,
usually written as ``DNS:rmc-lx0001`` by certificate tools. Modern browsers
rely on subject alternative names for this check.

If users will open the Web UI through more than one name, include all of those
names in the certificate. For example, a host might need both
``DNS:rmc-lx0001`` and ``DNS:rmc-lx0001.lab.example`` if both URLs are used.

Creating A Lab CA On Ubuntu 24.04
=================================

Ubuntu 24.04 normally provides OpenSSL. If it is missing, install it first:

.. code-block:: bash

   sudo apt install openssl

Create a working directory on a trusted machine:

.. code-block:: bash

   mkdir -p "$HOME/ln-manager-lab-ca"
   cd "$HOME/ln-manager-lab-ca"

Create the lab certificate authority:

.. code-block:: bash

   openssl genrsa -out lab-ca.key 4096
   chmod 600 lab-ca.key

   cat > lab-ca.conf <<'EOF'
   [req]
   prompt = no
   distinguished_name = dn
   x509_extensions = v3_ca

   [dn]
   CN = LN Manager Lab CA

   [v3_ca]
   subjectKeyIdentifier = hash
   authorityKeyIdentifier = keyid:always,issuer
   basicConstraints = critical, CA:true
   keyUsage = critical, keyCertSign, cRLSign
   EOF

   openssl req -x509 -new -key lab-ca.key -sha256 -days 3650 \
     -config lab-ca.conf -out lab-ca.crt

Keep ``lab-ca.key`` private. It can issue certificates that browsers trusting
``lab-ca.crt`` will accept. Do not copy ``lab-ca.key`` to user laptops or to
manager hosts that do not need to issue certificates. The file users import
into Firefox is ``lab-ca.crt``.

Creating A Host Certificate
===========================

Create one certificate for the manager host name users will open in the
browser. This example creates a certificate for ``rmc-lx0001`` and also allows
``rmc-lx0001.lab.example`` as a second name:

.. code-block:: bash

   HOST=rmc-lx0001

   openssl genrsa -out "$HOST.key" 2048
   chmod 600 "$HOST.key"

   cat > "$HOST.conf" <<EOF
   [req]
   prompt = no
   distinguished_name = dn
   req_extensions = v3_req

   [dn]
   CN = $HOST

   [v3_req]
   basicConstraints = CA:false
   keyUsage = critical, digitalSignature, keyEncipherment
   extendedKeyUsage = serverAuth
   subjectAltName = @alt_names

   [alt_names]
   DNS.1 = $HOST
   DNS.2 = $HOST.lab.example
   EOF

   openssl req -new -key "$HOST.key" -out "$HOST.csr" -config "$HOST.conf"

   openssl x509 -req -in "$HOST.csr" \
     -CA lab-ca.crt -CAkey lab-ca.key -CAcreateserial \
     -out "$HOST.crt" -days 397 -sha256 \
     -extensions v3_req -extfile "$HOST.conf"

Check the generated certificate:

.. code-block:: bash

   openssl x509 -in "$HOST.crt" -noout -subject -issuer \
     -ext subjectAltName

If users will only open ``https://rmc-lx0001:PORT/``, remove the
``DNS.2 = ...`` line before creating the certificate. If users will open
another local name, add it as ``DNS.3``, ``DNS.4``, and so on. If users must
open the Web UI by IP address, add an ``IP.1 = 192.168.1.42`` entry, but using
a stable host name is usually easier.

Use ``$HOST.crt`` and ``$HOST.key`` in the manager config:

.. code-block:: lnc

   instance
   # ...
   webui_https_cert_file: /path/to/rmc-lx0001.crt
   webui_https_key_file: /path/to/rmc-lx0001.key

Then copy ``lab-ca.crt`` to each laptop and import it into Firefox as described
below.

Trusting A Lab CA In Firefox
============================

Each laptop that should use the HTTPS Web UI must trust the certificate
authority that issued the manager host certificate. In Firefox, import the lab
CA certificate, not the ``rmc-lx0001`` server certificate and not the private
key.

Use a file containing the public CA certificate, for example ``lab-ca.crt`` or
``lab-ca.pem``. Before importing it, make sure it really came from the lab
administrator or another trusted source. If a fingerprint is provided, compare
it before accepting the certificate.

In Firefox: [#firefox-ca-settings]_

1. Open ``Settings``.
2. Open ``Privacy & Security``.
3. Scroll to ``Certificates``.
4. Click ``View Certificates``.
5. Select the ``Authorities`` tab.
6. Click ``Import``.
7. Select the lab CA certificate file.
8. Enable ``Trust this CA to identify websites``.
9. Confirm with ``OK``.

After that, Firefox should accept HTTPS certificates issued by that lab CA,
as long as the certificate also matches the host name in the URL. Repeat this
on every browser profile or laptop that should trust the lab CA.

Some Firefox installations can also be configured to use certificate
authorities from the operating system trust store. That is useful for centrally
managed laptops, but the exact setup depends on the operating system and site
policy. For individual lab machines, importing the CA in Firefox's
``Authorities`` list is usually the most explicit path.

.. [#firefox-ca-settings] Mozilla documents Firefox certificate-authority
   handling at
   https://support.mozilla.org/en-US/kb/setting-certificate-authorities-firefox.

Self-Signed Certificates
========================

A self-signed certificate can encrypt the connection, but browsers will not
trust it automatically. Each browser will show a warning until the certificate,
or a local certificate authority that issued it, is trusted.

For one machine or a quick test, accepting a self-signed certificate warning may
be sufficient. For repeated lab use, a local certificate authority is usually
less annoying: users trust the local authority once, and then certificates for
individual manager hosts can be renewed or replaced without teaching every
browser about each individual certificate again.

Renewal
========

Certificates expire, including locally issued certificates. Make sure the
renewal or replacement process updates the files used by ``ln_manager`` and
restart the manager afterwards, or restart it from your normal service
supervision setup. Otherwise the browser will start warning about the site
again after the certificate expires.

Common Problems
===============

Opening the Web UI by IP address while the certificate is issued for a host
name will fail browser validation. Use the host name from the certificate in the
URL, or create a certificate that also contains the IP address if your
certificate tooling and browser trust setup support that.

A certificate created for ``localhost`` only helps when the browser itself is
running on the manager host. For remote browser access, use a name that resolves
from the browser machine to the manager host.

If the host is reachable as ``rmc-lx0001`` from one workstation but only as
``rmc-lx0001.lab.example`` from another, either use one consistent URL or put
both names into the certificate.