Appliance Web Certificate

By default, browsers that open the Athena web console on port 8443 see a certificate issued by the appliance's own Athena CA. You can replace it with a certificate from your own CA (a corporate PKI or a public CA). Upload a PFX and Athena checks it and shows you every problem before you switch. The switch is live, with no restart, and you can switch back to the built-in certificate at any time.

The setting is in Settings → Appliance → Web certificate (port 8443), between Firewall and API documentation (Swagger). The same actions are available over the REST API and in the PowerShell module.

Who can use it#

By default only the built-in Admin role holds them. Users who have appliance.view but not appliance.manage see the current certificate and the note “Read-only: changing this needs the appliance.manage permission.” See Permission Model & Role Bundles.

The current certificate#

The top of the section describes the certificate port 8443 presents right now:

In the last 30 days the section also shows “The web certificate expires in N days. Upload a renewed one before it does.” After expiry it shows “The web certificate has expired: browsers refuse it. Upload a valid one or revert to the built-in certificate.” If TLS is turned off on the server, the section shows only “TLS is off on this server, so there is no web certificate to manage.”

Replacing the certificate#

You need a PFX (PKCS#12) file that contains the server certificate with its private key, ideally with the whole chain (intermediates). The file can be at most 1 MB. If you have separate PEM files, see Preparing the PFX.

1. Open Settings → Appliance and scroll to Web certificate (port 8443).
2. Under Replace the certificate, click the browse button next to PFX file (.pfx / .p12) and pick your file.
3. Type the PFX password.
4. Click Check. Athena opens the PFX and runs every check without changing anything. It shows the certificate's details, then any errors (red) and warnings (amber).
5. If there are no errors, the Use this certificate button appears. Click it. Port 8443 serves the new certificate from the next connection, and the toast says “Port 8443 now serves the uploaded certificate. Reload the page to see it in the browser.”
6. Reload the page. Your browser now shows the new certificate.

Athena keeps the PFX on the appliance and stores its password encrypted, never in plain text. The uploaded certificate stays in use after restarts and appliance reboots. To renew, upload the new PFX the same way. It replaces the old one directly.

Reverting to the built-in certificate#

While an uploaded certificate is in use, a Revert to built-in button appears next to Check. It switches port 8443 back to the built-in Athena certificate at once, also without a restart (“Port 8443 serves the built-in Athena certificate again.”). Browsers that don't trust the Athena Root CA will show a certificate warning again.

What Athena checks#

Errors block the switch: a browser would refuse the certificate, or the server couldn't use it. Warnings don't block it. Read them and decide for yourself.

• Names checked: the server's host names (Server:Hostnames). On the appliance these are its host name, FQDN and IPv4 address, as set in the appliance console. localhost, 127.0.0.1 and ::1 are never required. An IP address must be listed as an IP: SAN. A wildcard such as *.corp.example covers exactly one label (athena.corp.example, but not a.b.corp.example).
• Offline by design: the chain check doesn't contact CRL or OCSP servers and doesn't download missing intermediates, because an air-gapped appliance may have no route out. Only the certificates in your PFX and the appliance's trust store count, so include the intermediates in the PFX. The intermediates in the PFX are sent to browsers with the certificate in every TLS handshake.
• If the chain can't be evaluated at all, you get the warning “The certificate chain could not be checked on this server: …”. It doesn't block the switch.

If the uploaded certificate can't be loaded#

When Athena starts, it loads the uploaded certificate. If the file can't be read or decrypted, Athena doesn't lock you out. Port 8443 serves the built-in certificate instead, so the console stays reachable, and the section shows in red: “The uploaded certificate could not be loaded (…); port 8443 serves the built-in certificate.” To fix it, upload the PFX again, or click Revert to built-in to clear the setting.

Expiry tracking and audit#

Athena checks the port 8443 certificate (built-in or uploaded) every hour. It writes an audit event when the certificate enters its last 30 days and again when it expires: once per stage for each certificate while the server runs.

To get an alert before a certificate runs out, forward these events to your SIEM. See Audit Forwarding to SIEM and the Audit Event Types Reference.

REST API#

All endpoints return the usual { success, message, data } envelope and answer 404 off the appliance. Uploads are multipart/form-data with the PFX in the field file (at most 1 MB) and its password in the field password.

A request with no file, or a file over 1 MB, gets 400 “Send the PFX as the multipart field 'file' (at most 1 MB)”. To authenticate scripts, see API Tokens and the API Reference.

PowerShell#

The Athena PowerShell module wraps the same API. The PFX password is taken as a SecureString.

# Check the corporate certificate first, then switch to it
$pw = Read-Host -AsSecureString 'PFX password'
$check = Test-AthenaWebCertificate -Path .\athena-web.pfx -Password $pw
$check.Errors; $check.Warnings
# Use it only if no check blocks it
if ($check.Ok) { Set-AthenaWebCertificate -Path .\athena-web.pfx -Password $pw }

# Days left on the certificate port 8443 presents
(Get-AthenaWebCertificate).DaysLeft

# Back to the built-in Athena certificate
Reset-AthenaWebCertificate

Troubleshooting#

Related#

• Server TLS Certificate: ports, TLS settings and own certificates on non-appliance installs.
• Certificates & PKI: the Athena Root CA and the agent port.
• Appliance Backup & Restore: back up the appliance before major changes.
• Audit Event Types Reference: every audit event type.
• Downloads: appliance images and updates.