The console is served over HTTPS. Out of the box the agent creates its own certificate at every start, which is why your browser warns you and why it warns you again after a restart or an upgrade.
Replacing it with a certificate from your own authority removes the warning and lets your browser confirm it is talking to the right machine.
What you need
- The certificate, as PEM text, issued for the name you open the console by —
localhoston the machine itself, or the machine's name or address if you have turned on remote access. Include any intermediate certificates, leaf first. - The private key, as PEM text.
The key must belong to the certificate. DPLens checks that before accepting the pair and refuses a mismatch rather than starting with something that cannot work.
The key is never written to a file. Both are sealed to this machine, and your configuration file holds only the names they are stored under.
From the console
- Go to Settings and audit → Security → Console certificate.
- Paste the certificate chain into the first box, leaf first, and the private key into the second.
- Choose Install certificate… and confirm.
The console restarts within a few seconds.
Every signed-in session ends, including yours. Your browser must trust
the new certificate before you can sign in again. If you are working
remotely, make sure the new chain is trusted by the machine you are browsing
from before you install it.
Afterwards the card shows the certificate as operator-supplied, with its fingerprint and chain length. Compare that fingerprint with the one your browser reports — they should match.
The installation is recorded in the audit log, with the fingerprint and never the key material.
Without the console
If you deploy by configuration rather than clicking, seal both files and name them in the configuration.
type leaf.pem | "C:\Program Files\DPLens\dplens.exe" --set-secret secret://console/tls-cert
type leaf.key | "C:\Program Files\DPLens\dplens.exe" --set-secret secret://console/tls-key
settings:
ui:
tls_cert_handle: secret://console/tls-cert
tls_key_handle: secret://console/tls-key
Any pair of handle names works, as long as you set both. A single handle is refused when the configuration is checked, and so is PEM text pasted directly into the file — certificates and keys belong in the secret store, not in a document you might copy to another machine.
For a fleet, the deployment MSI carries the console pair only if you ask it to (--include-console-cert at capture), because a certificate issued to one machine is wrong on every other. Include it when the pair is valid for every target — a wildcard, or a name every target answers to; otherwise each machine mints its own self-signed certificate and you replace it there as above.
If the certificate cannot be loaded
If a handle is missing, the pair stops validating, or the console cannot start with the material you gave it, DPLens falls back to its own self-signed certificate and keeps serving.
That is deliberate: a console you can still reach and that warns you is more useful than one that has gone dark. You will see:
- the Security tab showing the certificate as a fallback, with the reason,
- an entry in the audit log recording the fallback and why.
Fix the material and install it again.
Removing it
Delete the two handles from settings.ui, or apply a configuration without them. The console returns to its own certificate at the next restart.
The sealed material stays in the secret store until you overwrite it. To remove it entirely, set the handles to a new value, or uninstall with REMOVE_STATE=1.