Internal Certificate Installation

Goal

When Sa2web is deployed on an intranet or private network, the server usually cannot request a public Let's Encrypt certificate through Caddy. If the installer uses a Caddy internal certificate, client devices must trust the local Caddy root certificate so browsers can open the admin console, user portal, and collaboration links without certificate warnings.

This section applies when:

• The system is accessed through an internal IP address, intranet domain, or domain that cannot be resolved publicly.
• The installer selected the Caddy internal certificate mode.
• The site opens, but the browser reports an untrusted or invalid certificate.

Prerequisites

• The product has been deployed and services are running.
• The access address is known, such as https://<APP_DOMAIN>/admin/login or https://<APP_DOMAIN>/app/login.
• You can log in to the installation server and read the install directory.
• You know which client platforms need the certificate, such as Windows, macOS, Linux, iOS, Android, or Firefox.

Get the Caddy Root Certificate

On the installation server, locate the Caddy local root certificate:

$INSTALL_PATH/data/caddy/pki/authorities/local/root.crt

$INSTALL_PATH is the product installation directory, for example /opt/sa. Verify the file and fingerprint:

ls -l $INSTALL_PATH/data/caddy/pki/authorities/local/root.crt
openssl x509 -in $INSTALL_PATH/data/caddy/pki/authorities/local/root.crt -noout -subject -issuer -fingerprint -sha256

Distribute only root.crt to users who need to access the system. Do not distribute private key files from the same directory.

Distribution Recommendations

Rename the certificate to a recognizable file name, for example:

Sa2web-internal-root-ca.crt

Send the certificate with the following information:

Item	Description
Purpose	Trust HTTPS access for the intranet Sa2web deployment
Target URL	https://<APP_DOMAIN>/
Fingerprint	SHA256 fingerprint from the openssl command
Scope	Workstations, test devices, or mobile devices that need system access

For enterprise environments, prefer domain policy, MDM, endpoint management, or system images to deploy the root certificate consistently.

Windows

1. Save root.crt locally.
2. Double-click the certificate and select "Install Certificate".
3. Select "Local Machine". If the user has no administrator permission, select "Current User".
4. Select "Place all certificates in the following store".
5. Choose "Trusted Root Certification Authorities".
6. Finish the import, then close and reopen the browser.
7. Visit https://<APP_DOMAIN>/admin/login to verify the certificate status.

Administrator PowerShell can also import the certificate:

Import-Certificate -FilePath .\Sa2web-internal-root-ca.crt -CertStoreLocation Cert:\LocalMachine\Root

macOS

1. Save root.crt locally.
2. Double-click the certificate to open Keychain Access.
3. Import it into the System keychain.
4. Open the certificate details.
5. Expand Trust and set "When using this certificate" to "Always Trust".
6. Enter the system password to save the change.
7. Restart the browser and open the system URL again.

Chrome, Safari, and Edge usually use the macOS system keychain. Firefox may need a separate import.

Linux

Debian and Ubuntu:

sudo cp Sa2web-internal-root-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

RHEL, CentOS, Rocky Linux, and AlmaLinux:

sudo cp Sa2web-internal-root-ca.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

Restart the browser after installation. If the warning remains, check whether the browser uses its own certificate store, especially Firefox.

Firefox

Firefox may not fully rely on the operating system certificate store. Import the root certificate directly:

1. Open Firefox Settings.
2. Go to Privacy & Security.
3. Find Certificates and click View Certificates.
4. On the Authorities tab, click Import.
5. Select root.crt.
6. Enable "Trust this CA to identify websites".
7. Confirm and restart Firefox.

Enterprise environments can also enable Firefox enterprise roots so Firefox trusts the operating system certificate store.

iOS and iPadOS

1. Send root.crt to the device through an enterprise-approved channel.
2. Open the certificate file and install the profile.
3. Go to Settings > General > VPN & Device Management and complete profile installation.
4. Go to Settings > General > About > Certificate Trust Settings.
5. Enable full trust for the root certificate.
6. Reopen Safari or another browser and visit the system URL.

Android

Menu names vary by vendor, but the usual path is:

1. Save root.crt to the device.
2. Go to Settings > Security > Encryption & credentials.
3. Select Install certificate or Install CA certificate.
4. Select root.crt and confirm.
5. Reopen the browser and visit the system URL.

Some Android versions or enterprise browsers do not trust user-installed CA certificates. In that case, deploy the certificate through MDM or device management policy.

Verification

After installation, open:

https://<APP_DOMAIN>/
https://<APP_DOMAIN>/admin/login
https://<APP_DOMAIN>/app/login

The expected result:

• The browser address bar no longer shows a certificate error.
• The certificate chain includes the local Caddy root certificate.
• The admin console and user portal can be opened normally.
• Collaboration links do not show certificate warnings on the target client devices.

Command-line verification:

curl -I https://<APP_DOMAIN>/

If the client trusts the root certificate, the command should return HTTP response headers.

Renewal and Reinstallation

Redistribute and reinstall the root certificate when:

• The product is reinstalled and $INSTALL_PATH/data/caddy/pki is cleared.
• The deployment is migrated to a new server and Caddy generates a new internal CA.
• The local Caddy root certificate is deleted or rotated.
• A client device is reinstalled or its trusted root store is cleared.

If product upgrades preserve $INSTALL_PATH/data, users usually do not need to reinstall the root certificate.

FAQ

Issue	Cause	Fix
Browser still reports an unsafe connection	Certificate was not installed into the trusted root store	Reimport it according to the operating system steps and restart the browser
Only Firefox reports an error	Firefox uses a separate certificate store	Import the certificate in Firefox certificate settings
Mobile browser still reports an error	Mobile OS does not fully trust the CA	Enable full trust on iOS, or deploy through MDM on Android
Domain does not match the certificate	The access address differs from the configured domain or IP	Use the configured system access domain, or reconfigure the certificate
root.crt cannot be found	Caddy has not generated the local CA or the path is wrong	Confirm $INSTALL_PATH, start services, then check the path again
Collaboration users still see warnings	Their actual access devices do not trust the root certificate	Install the root certificate on those devices

Security Notes

• Install root certificates only from administrator-approved channels.
• Verify the SHA256 fingerprint before installation.
• Do not distribute the Caddy CA private key.
• Remove unnecessary root certificates when devices are retired, reclaimed, or no longer need access.