Skip to main content

1E 23.11 (SaaS)

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

Note

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.

Note

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 https://support.1e.com/.

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

  • Within the zip, 1E Client for macOS is provided as 1e.client-macOS_v23.11.x.x.pkg.

Certificate files

The client authentication certificate, and Go Daddy Certificate Authority (CA) certificates 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).

    1. 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.

    1. Client Authentication

  3. Has at least the following Key Usage.

    1. Digital Signature

    2. Key encipherment.

  4. Has a private key.

  5. Revocation information is included.

    1. 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.

    1. For a Mac this could be MAC01.local and is case-sensitive

Go Daddy CA certificate

Each client requires the Certificate Authority (CA) certificates used by the 1E server’s certificate Trust Path, so the client can validate the server. 1E servers use certificates issued by Go Daddy. Typically the client only needs the Go Daddy Root CA certificate, but in some cases you may also require the Go Daddy Intermediate CA certificate.

Cetificate type

Certificate Name

SHA1 thumbprint (as seen in browser certificate details)

SHA256 thumbrint (as seen in Go Daddy repository)

Root CA

Go Daddy Root Certificate Authority - G2

47 BE AB C9 22 EA E8 0E 78 78 34 62 A7 9F 45 C2 54 FD E6 8B

45 14 0B 32 47 EB 9C C8 C5 B4 F0 D7 B5 30 91 F7 32 92 08 9E 6E 5A 63 E2 74 9D D3 AC A9 19 8E DA

Intermediate CA

Go Daddy Secure Certificate Authority - G2

27 AC 93 69 FA F2 52 07 BB 26 27 CE FA CC BE 4E F9 C3 19 B8

97 3A 41 27 6F FD 01 E0 27 A2 AA D4 9E 34 C3 78 46 D3 E9 76 FF 6A 62 0B 67 12 E3 38 32 04 1A A6

Obtain Certificate Authority (CA) certificates as individual .cer files (which are Base-64 encoded X.509 format). Some alternative ways of getting them are:

  • Received from your 1E Account Team

  • Download .crt files from https://certs.godaddy.com/repository - you can rename or convert these as .cer files

  • Use Microsoft Manage Computer Certificates (certlm.msc) on a Windows computer, to export each CA certificate as a .cer file using base-64 encoded X.509 format.

Warning

You must have individual .cer files instead of a bundle such as a .pem because the Keychain Access app only imports the last certificate it encounters.

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.

Warning

The Subject Name of the certificate must be the host name of the macOS device.  You will supply this value during enrolment. 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

Note

Together, the client authentication certificate and its associated private key are termed an identity on macOS. The client authentication certificate (with its private key), and the Go Daddy Certificate Authority (CA) certificates 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 machine.

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

Caution

The Keychain Access app cannot be guaranteed to always refresh its view following, for example, an update of access control permission. However, after exiting the app, killing the process:

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

Then restarting the app, will ensure the Keychain Access view will correctly display the contents of the Key Store.

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

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

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.

Note

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:

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain <certificate.cer>
Prepare the dmg file for the 1E Client

Please note the following:

  • 1E Client installation files are available for download from https://support.1e.com/.

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

  • Within the zip, 1E Client for macOS is provided as 1e.client-macOS_v23.11.x.x.dmg.

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

mkdir ~/Downloads/1e.client
cd ~/Downloads/1e.client
wget https://<<serverURL>>/1e.client-macOS_v8.0.x.x.dmg
hdiutil attach 1e.client-macOS_v24.x.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 .

Install the Provisioning Profile

Note

This is a prerequisite for 1E Client to run on macOS.

For UI installations follow these steps:

  1. Download the 1E_Client.provisionprofile file from the 1E Support Portal https://support.1e.com.

  2. Copy the profile file onto the macOS device.

  3. Open Finder and double-click on the file to install.

  4. You will be prompted to allow the installation by using an admin password.

Install the 1E Client

To install the macOS 1E Client perform 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 you wish to use for installation or upgrade.

    2. Invoke install.sh script to 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:

      sudo ./install.sh tachyon.acme.local:4000 https://tachyon.acme.local/Background

      Note

      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.

  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.

    sudo installer -pkg /path/to/pkg/1e.client-macOS_v8.0.x.x.pkg -target /
  3. 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:

hdiutil eject /Volumes/image.1e.client-macOS_v8.0.x.x
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 the previous installation options.

The pkg installation package for macOS 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.

sudo sh '/Library/Application Support/1E/Client/1E.Client.updateconf.sh' 
'/Library/Application Support/1E/Client/1E.Client.conf' 
SWITCH='tachyon.acme.local:4000;tachyon.acme.com:4000' 
BACKGROUNDCHANNELURL='https://tachyon.acme.local:443/Background/;https://tachyon.acme.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.

Note

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:

    sudo 'PATH_TO_THE_START_SCRIPT'
  2. Run the following command:

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

If the 1E Client should fail to start correctly please check:

  • sudo launchctl list | grep -i 1e - to confirm the service is actually running. It should appear as com.1e.pkg.1E.Client

  • /Library/Logs/1E.Client.Daemon.log - shows any service start errors

  • tail -f /Library/Logs/1E.Client.log - shows 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.

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:

    sudo 'PATH_TO_THE_STOP_SCRIPT'
  2. Run the following command:

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

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

//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

Note

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:

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

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

sudo installer -pkg /path/to/pkg/1e.client-macOS_vx.x.x.x.pkg -target /

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

Note

To set the SWITCH and BACKGROUNDCHANNELURL post upgrade (in case not set earlier), please reconfigure the client.