Deploying 1E Client on macOS

Guidance for deploying 1E Client onto macOS devices, including installation and uninstallation. Only the 1E features of 1E Client are available on macOS.

Requirements

1E Client does not have a license key. Even so, you must adhere to the terms of your license agreement.

Deployment choices

  • You must decide how you will configure the 1E Client and deploy to devices.

  • Deploying the 1E Client is normally achieved using your existing software deployment tool.

  • For more information about configuring the 1E Client properties during and after installation, please refer to 1E Client configuration settings and installer properties.

Non-Windows installation account

To install the 1E Client on a non-Windows client the installation account must have privileges to run the sudo command.

1E Client installation files

  • 1E Client installation files are available for download from the 1E Support Portal.

  • Installation source files for non-Windows are available in a zip file called 1EClient-Non-Windows.v24.x.x.x.zip

  • Within the zip, 1E Client for macOS is provided as a DMG fle like 1e.client-macOS_v24.x.x.x.pkg.

Certificate files

The client authentication certificate should be stored within the macOS Key Store under the System keychain.

Client authentication certificate

Each client device requires a client authentication certificate with the following properties. This must be deployed to devices as .pfx certificate file along with the 1E Client package. Use the following points to create and use the .pfx file:

  1. Issued by a trusted Certificate Authority (CA): Most organizations have automated distribution of CA certificates to clients and servers. For example, Group Policy can be used to deploy CA certificate to Windows clients.

  2. Has at least the following Enhanced Key Usage: Client Authentication.

  3. Has at least the following Key Usage: Digital signature, and key encipherment.

  4. Has a private key.

  5. Revocation information is included: References at least one OCSP endpoint.

  6. Has a Subject Name of type Common Name (CN=<computername>) or Subject Alternative Name (DNS Name=<computername>) where <computername> depends on the type of device. For a Mac this could be MAC01.local and is case-sensitive

Preparation

You will need to create a PFX certificate file using a template, follow this guide for using a Microsoft Certificate Authority (CA) to:

  • Create a template for issuing client authentication certificates.

  • Use the template to request certificates.

  • Export the certificate as a .pfx file ready for installation on the device.

If you do not already have a suitable certificate template on your Certificate Authority, you can create one by making a duplicate of either the Computer or Workstation template and configuring it with at least the following properties:

  • General: Use a suitable name such as 1E Client Devices and validity period.

  • Request Handling: Allow private keys to be exported.

  • Subject Name: Allow information to be supplied in the certificate request, rather than being built from Active Directory information.

  • Extensions: Application policies should contain only Client Authentication.

  • Security: Ensure relevant users and computers will be able to request certificates.

Once you have created the new template on the Certificate Authority (CA), you should issue it. Using the issued template, request a certificate for a target device, and export it in .pfx form and remember the password. The certificate and associated private key should be exported, together with all extended properties, except include all certificates in the certification path if possible and enable certificate privacy.

The Subject Name of the certificate must be the host name of the macOS device.  You will supply this value during enrollment. To find the hostname of the macOS machine open Finder and click the Apple icon in the upper left.  Select System Preferences -> Sharing -> Screen Sharing.

Below the computer name field, you will see Computers on your local network can access your computer at: this value will be your host name.  It must be typed exactly as displayed in the certificate request (case-sensitive and including any special characters).

Installation

Together, the client authentication certificate and its associated private key are termed an identity on macOS. The client authentication certificate (with its private key) should be stored within the macOS Key Store under the System keychain. The System keychain is for certificates trusted by all users and local system processes including the 1E Client which will run on the macOS device.

Installing certificates can be done by using the Keychain Access app, which can be started using either of the following methods:

  • Pressing command-space and searching for keychain.

  • From the Finder app, top left select Go > Utilities and double-click on Keychain Access to invoke the app.

Install the client certificate

To install a client certificate on each macOS device, follow these steps:

  1. Copy the client certificate .pfx file onto the macOS device.

  2. Open Finder, and double-click on the .pfx file to import the certificate into the macOS Keychain store. Or use File → Import Items... directly from Keychain Access. Enter the .pfx password when prompted.

  3. Open Keychain Access, the certificate and its associated private key should be found under the login keychain.

  4. Copy the client certificate and its associated private key, separately into the System keychain.

To allow access to the private key follow these steps:

  1. Locate the private key within the System keychain, the private key will appear under its associated certificate.

  2. Ensure the private key is present in the System keychain.

  3. Double click the private key and select the Access Control tab.

  4. Ensure Confirm before allowing access is selected and then add the 1E Client binary to the Always allow access by these applications adding the 1E Client by its path name, which is typically /Applications/1E.app/Contents/MacOS/1E.Client

The Certificate’s Private Key Access is Mandatory for 1E Client to be able to connect the Switch. If giving access to a specific app is not available, which applies to some MDM Applications, allow access to any applications.

The Keychain Access app cannot be guaranteed to always refresh following, for example an update of access control permissions. However, after exiting the app, and killing the process (see below), then restarting the app, will ensure the Keychain Access view will correctly display the contents of the Key Store.

Copy 
/Applications/Utilities/Keychain Access.app/Contents/MacOS/Keychain Access

An alternative approach to using the Keychain Access app is to import the .pfx file using the command-line and the security command:

Copy 
sudo security import <download location>/<macOSpfx>.pfx -k /Library/Keychains/System.keychain -t agg -f pkcs12 -P <password> -T '/Applications/1E Client.app'

This command imports a client certificate and the associated private key from a .pfx file to a <keychain> as an aggregated type in PKCS #12 format using the specified password and giving access to the 1E Client.

If you do not grant correct access to the client certificate's private key, and the 1E Client debug logging is configured the log will show that it cannot obtain the client certificate's private key.

Install the CA certificates

  1. Copy the CA certificate .cer file(s) onto the macOS device.

  2. Open Finder, and double-click on each .cer file in turn to import each certificate into the macOS Keychain store. Or use File > import Items... directly from Keychain Access.

  3. Open Keychain Access, the certificates should be found under the System keychain. If not, then find each newly imported certificate and copy it to the System keychain.

  4. Starting with the root CA certificate, if it is shown as not trusted, double-click to open. At the top left, above the Details section, expand the Trust section and ensure that When using this certificate Always Trust is selected and save the changes.

If you experience problems importing certificates using the Keychain Access app, for example if it reports error -25294 and CSSM_CODE_MEMORY_ERROR, an alternative way of importing public certificates and trusting them is to use the security command line tool. For example:

Copy 
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain <certificate.cer>

Automount the DMG

Once the DMG file is copied to macOS, double-click on the file to automount it under /Volumes and display it in a Finder window, as shown. You can script this using all or part of this example:

Copy 
mkdir ~/Downloads/1e.client
cd ~/Downloads/1e.client
wget https://<<serverURL>>/1e.client-macOS_v24.5.x.x.dmg
hdiutil attach 1e.client-macOS_v24.5.x.x.dmg

The last line of the output of the hdutil command will show the location of the mount point, which is likely to be /Volumes/image.1e.client-macOS_v24.x.x.x as shown.

Install the 1E Client

To install the macOS 1E Client, use one of the following options:

  1. Use the install.sh script provided in the DMG to install and configure the client using the following steps:

    1. Copy the script to a separate directory together with the package for install or upgrade.

    2. Invoke install.sh script to begin the install, configure and start the 1E Client, giving the Switch host and port as the first parameter and the Background Channel URL as the second.

      This method will start the client, but connection to the 1E Switch will fail unless the client has the necessary certificates, as described in Install the client certificate.

      Copy 
      sudo ./install.sh SWITCH=tachyon.acme.local:4000 BACKGROUNDCHANNELURL=https://tachyon.acme.local/Background

  2. Install the package file from a command window to install using the defaults. The -target is the volume mount point, not the path in the file system at which it will be installed.

    Copy 
    sudo installer -pkg /path/to/pkg/1e.client-macOS_v24.5.x.x.pkg -target /

  1. Double-click on the package .pkg file within the Finder window to install using the defaults.

For options 2 and 3, you will need to reconfigure the 1E Client either using the 1E.Client.updateconf.sh script or by editing the /etc/1E/Client/1E.Client.conf file, as described in Reconfiguration on macOS.

After installation, you can unmount the dmg using the following command:

Copy 
hdiutil eject /Volumes/image.1e.client-macOS_v24.5.x.x

Grant permissions to the 1E Client

This is not a mandatory permission for 1E Client to work but is required for the File Change Event feature which is part of 1E Endpoint Automation.

MacOS 1E Client needs Full Disk Access for certain functionality to work efficiently.

Follow these steps to grant permissions post client installation. You can choose either option:

  1. To manually grant Full Disk Access:

    1. Choose Apple menu > System Preferences.

    2. Click Security & Privacy.

    3. Select the Privacy tab.

    4. Scroll down and click Full Disk Access.

    5. Select the box for the 1E Client process.

  2. Use MDM, and the PrivacyPreferencesPolicyControl payload. Refer to https://developer.apple.com/documentation/devicemanagement/privacypreferencespolicycontrol

For details about creating configuration profiles for 1E Client, refer to Deploying 1E Client using Jamf.

Reconfiguration

You will need to use the 1E.Client.updateconf.sh script if you want to reconfigure the client, or you installed 1E Client using installation command and need to update the SWITCH and BACKGROUNDCHANNELURL.

The pkg installation package for macOS as well as /Library/Application Support/1E/Client directory post installation includes a bash script called 1E.Client.updateconf.sh. The configuration properties for the Switch and Background Channel are mandatory. Assuming they are on the same 1E Server which has a DNS Name FQDN tachyon.acme.local then the post-installation command line would be similar to the following but all on one command line. The second Switch and Background Channel can be removed if a DMZ server is not used. Single quotes avoid escape characters and are necessary to allow the use of the  ; character.

Copy 
sudo sh '/Library/Application Support/1E/Client/1E.Client.updateconf.sh' '/Library/Application Support/1E/Client/1E.Client.conf' SWITCH='<customerDNSname>-sw.cloud.1e.com:443' BACKGROUNDCHANNELURL='https://<customerDNSname>.cloud.1e.com:443/Background/'

Please refer to 1E Client configuration settings and installer properties for a list of other configuration properties that can be appended to the above command-line.

You will need to restart the 1E Client post reconfiguration for the changes to take effect.

Starting and stopping the 1E Client

Starting the 1E Client

  1. Use the script start.sh from the DMG:

    Copy 
    sudo 'PATH_TO_THE_START_SCRIPT'

  1. Run the following command:

    Copy 
    sudo launchctl load /Library/LaunchDaemons/com.1e.pkg.1E.Client.plist

Stopping the 1E Client

If it is necessary to stop the 1E Client use the command:

  1. Use the script stop.sh from the DMG:

    Copy 
    sudo 'PATH_TO_THE_STOP_SCRIPT'

  2. Run the following command:

    Copy 
    sudo launchctl unload /Library/LaunchDaemons/com.1e.pkg.1E.Client.plist

If the 1E Client fails to start correctly please check:

  • To confirm the service is actually running. It should appear as com.1e.pkg.1E.Client:

    Copy 
    sudo launchctl list | grep -i 1e

  • /Library/Logs/1E.Client.Daemon.log: Check for service start errors

  • tail -f /Library/Logs/1E.Client.log: Does this show the current operation of the 1E Client?

  • If necessary raise the /Library/Application Support/1E/Client/1E.Client.conf to LoggingLevel=debug using a suitable text editor such as vi and then restart the 1E Client.

Uninstallation

You will need to use the following Uninstall.sh script from the DMG if you want to uninstall the client.

Copy 
//For Clean uninstallation i.e. Removing the Client Configuration as well 
sudo 'PATH_TO_THE_UNINSTALL_SCRIPT' clean 

//For normal uninstallation i.e Retaining the configuration for 1E client re-installations.
sudo 'PATH_TO_THE_UNINSTALL_SCRIPT'

Upgrading

1E Client has a significant change in the default port configuration. Where previously the client would default to port 4000 in the absence of a specified port, it now defaults to port 443. To maintain connectivity with the 1E Platform Switch, it is crucial to check the 1E.Client.conf file on devices for the specified SWITCH parameter.

If the port is not explicitly stated, the upgraded client will attempt to connect using port 443, which could lead to connectivity issues if the 1E Platform Switch still uses port 4000. It is recommended that you explicitly define the port as 4000 during the upgrade process if that is the port your environment utilizes. Conducting a test upgrade on a small set of devices before rolling out the update can help ensure a smooth transition and maintain platform connectivity.

You may need, or want to provide a more recent client authentication certificate.

To upgrade the macOS 1E Client, use one of the following methods:

  1. Double-click on the package .pkg file within the Finder window.

  2. Upgrade using the package file from a command window using Existing configuration.

    Copy 
    sudo installer -pkg /path/to/pkg/1e.client-macOS_v24.5.x.x.pkg -target /

    The -target is the volume mount point, not the path in the file system at which it will be installed.

To set the SWITCH and BACKGROUNDCHANNELURL post upgrade if you have not set this earlier, please reconfigure the client.