Root Certificate Installation

What the certificate installation Worklet does

This Automox Worklet™ installs custom root certificates to the macOS system keychain, enabling endpoints to trust certificates issued by your organization's internal certificate authority. The Worklet supports macOS Catalina and earlier versions (Darwin kernel version 19 and below).

The Worklet accepts a base64-encoded certificate as input and securely adds it to the System.keychain as a trusted root CA. After installation completes, all applications on the endpoint recognize the certificate as valid, eliminating security warnings when accessing internal resources or third-party services using custom-signed certificates.

Why deploy trusted root certificates

Organizations using internally-signed certificates, internal CAs, or third-party certificate authorities need those roots trusted on every endpoint. Without them, browsers and applications display warnings or block access entirely, degrading user experience and potentially driving users to bypass security controls.

Automating certificate distribution through this Worklet maintains consistent trust store configuration across your fleet. It eliminates manual steps, reduces deployment time, and keeps compliance with your organization's certificate trust policies without requiring user intervention.

How root certificate installation works

1. Evaluation phase: Checks the Darwin kernel version to verify the endpoint is running macOS Catalina (version 19) or earlier. If the endpoint runs Big Sur (version 20) or later, the Worklet exits without taking action.

2. Remediation phase: Decodes the base64-encoded certificate, writes it to a temporary file in /var/tmp/, adds it to the System.keychain as a trusted root using the security add-trusted-cert command, and removes the temporary file.

Root certificate installation requirements

• macOS Catalina (10.15.x) or earlier versions

• Root-level privileges or sudo access required for keychain modifications

• Base64-encoded certificate data must be provided via the rootCert parameter

• Certificate name identifier required for naming the installed certificate

• Write access to /var/tmp/ directory

Expected certificate trust state

After successful execution, the root certificate appears in the System.keychain and all applications on the endpoint recognize it as a trusted CA. Browsers no longer display warnings when accessing resources protected by certificates issued by this CA, and API clients can verify connections without certificate errors.

The Worklet creates no visible artifacts on the endpoint after completion. The certificate persists in the keychain until manually removed or reimaged. Multiple certificates can be installed across different Worklet executions, each adding another trusted root to the system's certificate store.

How to validate root certificate installation changes

1. Run this Worklet on a pilot macOS endpoint and review evaluation output for root certificate installation.

2. Confirm Automox activity logs show successful completion and exit code 0.

3. Verify endpoint state using checks aligned to evaluation script logic, such as exit.

4. Validate remediation effects from script operations such as exit, else, cat, then rerun evaluation for compliance.

For technical validation, compare endpoint state to the Worklet evaluation logic and remediation flow for root certificate installation. This supports repeatable security workflows, faster change control review, and auditable compliance evidence.

Useful script references for this Worklet include evaluation operations such as exit and remediation operations such as exit, else, cat. Use these indicators to verify that endpoint changes match intended policy outcomes.