These instructions are applicable to an On-Premises/Private Cloud deployment. If you wish to implement a proprietary or self-signed certificate for your Cloud deployment, please contact Teramind Support for assistance.
Introduction
By default, Teramind monitors encrypted HTTPS traffic by injecting a web proxy certificate into visited websites. In Mac, this certificate is signed by the Internet Widgits root certificate, which acts as the Certificate Authority (CA) for all monitored domain certificates. These certificates are typically generated automatically upon the first successful connection to a domain.
However, organizations have the option to utilize a proprietary root CA certificate instead of the default Teramind version to satisfy internal security protocols.
Step 1: Create a Certificate
To generate a new root CA certificate and private key, run the following commands in your Terminal (adjust the parameters as needed):
openssl genrsa -out key.pem 2048
openssl req -x509 -new -nodes -key key.pem -sha256 -days 1826 -out mycert.crt -subj "/O=ACME Inc./CN=ACME Proxy Certificate"
Step 2: Trust the Certificate on macOS
By default, macOS only trusts certificates issued by globally recognized Certificate Authorities (like DigiCert or Let's Encrypt). Because you have generated a proprietary (self-signed) certificate, macOS will view it as a potential security risk and block encrypted traffic.
Adding the certificate to the System Keychain and marking it as Trusted establishes a "Chain of Trust." This prevents "Your connection is not private" warnings in browsers and ensures that Teramind can monitor HTTPS traffic seamlessly without interrupting the user experience.
Method 1: Terminal (Recommended for Speed)
Run the following command in your Terminal, replacing <path_to_the_certificate> with the actual file path (e.g., /Users/John/Desktop/mycert.crt).
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain <path_to_the_certificate>
Command Breakdown:
Option | Description |
| Adds the certificate as a trusted root for the admin/system. |
| Formally designates the certificate as a Root Certificate Authority. |
| Specifies the System Keychain, ensuring the certificate applies to all users on the machine. |
| The location of your |
Method 2: Manual (Keychain Access UI)
1. Open Keychain Access: Press Cmd + Space and type "Keychain Access."
2. Import: Drag and drop your mycert.crt file into the System keychain category.
3. Set Trust: Find your certificate (this is the CN parameter of your certificate, e.g., "ACME Proxy Certificate") and double-click it:
4. Set Trust: Expand the Trust section. Change the When using this certificate dropdown to Always Trust.
5. Authenticate: Close the window and enter your administrator password to save the changes.
Method 3: Remote Deployment (via an MDM)
If you are managing a fleet of Macs via MDM (Mobile Device Management) like Jamf, you should deploy the certificate via a profile rather than manual installation. The specific instructions are tool-specific, but here is a general workflow for most MDM platforms:
1. Upload the Certificate: Upload the .crt file you created in Step 1 to your MDM. This is usually done on the MDM's "Certificates" or "Configuration Profiles" section.
2. Configure the Payload: Ensure the certificate payload is set to the System level (not User level).
3. Mark the Certificate as Trusted: Most MDMs automatically trust certificates deployed via a certificate payload. However, double-check the trusted certificates or security policies setting, esure the "Root" designation is checked if applicable.
4. Verifying the certificate on devices: After deployment, the MDM should automatically distribute the certificate to all connected devices. It’s important to check on each device that the certificate is installed and marked as trusted to avoid security or compatibility issues. You can do so from a target Mac's System Settings > Privacy & Security > Profiles screen.
Step 3: Update the Database Table
To configure a custom certificate for self-hosted instances, administrators must update specific keys within the Teramind database. Using a database administration tool such as pgAdmin, navigate to the kv_store table located within the tm_onsite > public schema. You must insert or update the following three keys with their corresponding values:
Field | Value* |
| The private key password (leave empty if no password was set). |
| The plaintext content from the key.pem file created in Step 1. |
| The plaintext content from the mycert.crt file created in Step 1. |
*Note: The Teramind server cannot validate these values at the time of entry. It is essential to ensure the data is correct and that the corresponding paths or files are present. If the Agent receives invalid or empty certificate data from the server, it will automatically revert to the default Quick Web Proxy certificate to ensure monitoring continuity.
Step 4: Restart or Reboot the Server
Once the database entries are saved, the changes will not take effect until the Teramind services are re-initialized. Run the following command in your terminal to restart the server:
sudo systemctl restart teramind
Alternatively, you can execute a full system reboot to ensure all components recognize the new certificate:
sudo reboot
Step 5: Verify the Certificate Activation
To confirm the new certificate is active, open a web browser on a monitored endpoint and visit an HTTPS website. Inspect the site's certificate details; it should now show as being issued by your proprietary root CA rather than the default "Internet Widgits".
