--- title: "Certificates" description: "Install a CA-signed certificate for the Koios web interface and manage the client certificates Koios presents to OPC-UA servers" source_url: https://ai-ops.com/docs/system/certificates --- # Certificates Navigate to **System > Certificates** to manage the TLS certificates Koios uses to identify itself — to browsers, and to the devices it connects to. The page has two tabs: | Tab | Covers | |-----|--------| | **Web interface** | The certificate browsers see when they open Koios over HTTPS | | **OPC-UA clients** | The client certificates Koios presents when connecting to secured OPC-UA servers | The two are unrelated. Replacing one has no effect on the other. --- ## Web Interface Out of the box Koios serves a built-in self-signed certificate on the HTTPS port. It encrypts the connection, but no browser trusts it, so every user sees a security warning and has to click through it before reaching the login page. Upload a certificate signed by a certificate authority your browsers already trust — your organization's internal CA, or a public one — and the warning goes away. ### Active Certificate The **Active certificate** card shows what is being served right now, with a badge naming where it came from: | Badge | Meaning | |-------|---------| | **Built-in self-signed** | The shipped fallback. Browsers will warn. | | **Uploaded via UI** | A certificate uploaded on this page. | | **Operator file drop** | A certificate placed on the server's certificates volume. It outranks anything uploaded here. | Below the badge, the card lists the certificate's details: - **Common name** and **Issuer** - **Subject alt names**, when the certificate carries any - **Valid from** and **Valid until**, with a badge counting the days remaining - **Serial** and the **SHA-256** fingerprint The expiry badge reads **Expires in 42d** while the certificate is valid — teal normally, yellow at 30 days or fewer remaining, red at 15 or fewer. Once the date has passed it turns red and counts up instead, reading **Expired 3d ago**. Koios does not raise an alarm or an event when a certificate is about to expire, so check this card as part of your regular maintenance. > [!NOTE] The private key is never shown > Only the certificate is read back. The private key you upload is written where the web server can read it and is never returned to the interface, included in a status view, or offered as a download. ### What You Need Two files are required, plus an optional third. All are PEM encoded: | File | Contents | |------|----------| | **Certificate** | The leaf certificate for this server. Begins with `-----BEGIN CERTIFICATE-----`. | | **Private key** | The matching key. It must **not** be passphrase-protected. | | **Chain / intermediates** | Optional. Any intermediate CA certificates your CA requires. | The certificate's common name or subject alt names should match the hostname or IP address your users type to reach Koios. A certificate that is valid but issued for a different name still produces a browser warning. If your key is passphrase-protected, strip the passphrase before uploading: ```bash openssl rsa -in encrypted.key -out koios.key ``` > [!WARNING] Passphrase-protected keys are rejected > Koios must be able to start unattended, so the web server needs the key unlocked at every boot. Storing the passphrase alongside the key in cleartext would buy nothing, so passphrase-protected keys are refused with a message pointing at the command above. ### Installing a Certificate 1. Open the **Web interface** tab 2. In the **Upload a certificate** card, select your **Certificate (PEM)** file 3. Select the matching **Private key (PEM)** file 4. If your CA issued intermediates, select the **Chain / intermediates** file 5. Click **Upload & apply** Koios validates the files before doing anything with them, then applies the certificate and reloads the web server without dropping connections. There is no restart and no downtime. Reload the page afterward if your browser is still showing the old certificate. Uploading requires the **Can manage HTTPS certificates** permission, listed under **System Settings** in the role editor and held by the built-in Administrator role. Without it the form and the revert button stay visible but disabled, with a tooltip explaining why. See [Roles & Permissions](https://ai-ops.com/docs/system/roles-permissions.md). ### If the Upload Is Rejected Validation runs before anything is applied, and the certificate currently in use stays live. Expect a rejection when: - The certificate or key is not valid PEM - The private key does not match the certificate - The certificate has expired, or is not valid yet - The key is passphrase-protected - The certificate or chain file contains a private key — upload the key only in the key field If the files pass validation but the web server refuses the result, Koios rolls back to the previous certificate and reports the failure. In every failure case the interface you are using stays reachable. > [!TIP] A bad certificate cannot lock you out > Koios revalidates the certificate on every boot and falls back to the built-in self-signed one if it cannot be used. Restarting the container is always a way back into the interface. ### Reverting to Self-Signed When a certificate uploaded through this page is active, a **Revert to self-signed** button appears on the **Active certificate** card. It removes the uploaded certificate and key and restores the built-in one. A confirmation dialog appears first, since browsers start warning again immediately afterward. The button is not offered for the built-in certificate or for one placed on the server as a file — there is nothing to remove in the first case, and the second is not managed from here. ### Certificates Placed on the Server A certificate placed directly on the certificates volume takes precedence over anything uploaded through this page. This is the path to use when certificates are issued and rotated by automation rather than by hand. While one is active, the badge reads **Operator file drop**, the upload form is disabled, and a note explains that the certificate must be removed from the server to hand control back to the interface. For the file names, the exact location, and how to install a certificate this way at deploy time, see [Environment Variables](https://ai-ops.com/docs/installation/environment-variables.md). > [!NOTE] Back up the certificates volume > An installed certificate and its private key live on the `koios_certs` volume. Restoring an install without it drops the web interface back to the built-in self-signed certificate and you will need to install yours again. See [Backing Up Docker Volumes](https://ai-ops.com/docs/installation/backup-restore.md). ### When TLS Is Disabled If Koios runs with TLS disabled — typically because a load balancer or reverse proxy in front of it terminates HTTPS — none of this applies. Koios serves plain HTTP and the certificate presented to users is the one on your proxy. The tab still loads, but nothing it shows is in the path browsers use. --- ## OPC-UA Clients The **OPC-UA clients** tab is the central manager for the client certificates Koios presents when connecting to OPC-UA servers with a security mode of **Sign** or **Sign & Encrypt**. Generate or upload certificates here once, then assign them to devices in each device's connection settings. Devices with no certificate assigned use the default one. Managing these certificates requires the **Can manage OPC-UA certificates** permission, listed under **OPC-UA Certificates** in the role editor and held by the built-in Engineer and Administrator roles. It also gates the private key download. This is separate from the web interface certificate permission above. This tab replaced the certificate controls that used to live on the OPC-UA protocol detail page; that page now links here instead. For generating, uploading, regenerating, assigning, and getting an OPC-UA server to trust a Koios certificate, see [OPC-UA Certificates](https://ai-ops.com/docs/protocols/opc-ua-certificates.md). --- ## Auditing Certificate uploads and reverts are recorded in the audit trail, along with who performed them. Private key material is never written to the record. See [Audit Log](https://ai-ops.com/docs/system/audit-log.md). --- ## What's Next - [OPC-UA Certificates](https://ai-ops.com/docs/protocols/opc-ua-certificates.md): the full guide to OPC-UA client certificates - [Environment Variables](https://ai-ops.com/docs/installation/environment-variables.md): TLS settings and installing a certificate at deploy time - [Roles & Permissions](https://ai-ops.com/docs/system/roles-permissions.md): grant certificate management to a role