Installing the DirectControl Agent for Mac

This section explains how to install the DirectControl Agent for a Mac computer.

Preparing to Install the DirectControl Agent for Mac

You must install the DirectControl Agent for Mac on each computer that you want to manage through IBM Security and Active Directory. You can check the Release Notes included with the software, or visit the IBM Security Web site (scroll to Supported Platforms and click the Details tab) to verify that each computer where you plan to install is running a supported version of the mac operating system.

The installation package also contains a utility, ADCheck, which verifies that each of your Mac computers is ready for installation of the DirectControl agent. ADCheck confirms that a computer is running a supported OS, has sufficient disk space to install the DirectControl agent, and that the domain you intend to join has functioning domain controllers and DNS servers. Information about running ADCheck is included in this documentation.

Installing the Agent on Apple M1 Mac Computers

Depending on whether you using the graphical installer or the command line version to install the DirectControl Agent for Mac on Apple M1 Mac computers, you may need to install some additional software.

  • If you install the DirectControl Agent for Mac on an Apple M1 Mac computer using the graphical user interface, you might be asked to install Rosetta.

    Click Install, then enter your user name and password to allow installation to proceed.

    For more information, see https://support.apple.com/en-us/HT211861.

  • If you install the DirectControl Agent for Mac on an Apple M1 Mac computer using the install.sh script, or by installing remotely, you might need manually install Rosetta first. Please run the following command with root privileges to install Rosetta 2:

    /usr/sbin/softwareupdate --install-rosetta --agree-to-license

Verifying DirectControl Agent for Mac Installation Prerequisites

Before installing the DirectControl Agent for Mac on your Mac computers, be certain that you or another administrator has installed IBM Security Management Services on a Windows computer in the domain. IBM Security Management Services includes the Access Manager Console, which is the primary management console for performing ongoing operations, including the application of group policies.

For information about other IBM Security Management Services components, such as Zone Provisioning Agent, see the Planning and Deployment Guide and the Administrator’s Guide for Linux and UNIX.

Deciding When and How to Join a Domain

Following installation, you will be prompted to join a domain. Whether to join a domain depends primarily on how you intend to join. IBM Security provides two ways to join a domain:

  • Through Auto Zone, which is the recommended method for installations with 1500 or fewer users. When joined through Auto Zone, all users and groups defined in Active Directory for the forest — as well as all Active Directory users defined in a forest with a two-way, cross-forest trust relationship to the forest of the joined domain — automatically become valid users and groups on the Mac computer.
  • By connecting to a specific IBM Security zone, which is the recommended method for installations with 1500 or more users, or for installations in which fine-tuned access control is needed. A zone is similar to an Active Directory organizational unit (OU) and allows you to organize the computers in your organization in meaningful ways to simplify account and access management and the migration of information from existing sources to Active Directory.

The assumption of this guide is that you are joining Auto Zone. After installation, you can follow the instructions to join the domain and with a few configuration steps all your Active Directory users will be able to log into this computer.

If you have a set of Apple Open Directory users, you should migrate them following installation but before joining a domain.

On the other hand, if your environment requires a zone structure, you must create that structure before joining a domain. Therefore, after installing the DirectControl agent, consult the Planning and Deployment Guide and the Administrator’s Guide for Linux and UNIX, which explain in detail how to plan, create, and maintain an Active Directory installation of non-Windows computers with Verify Privilege Server Suite.

Installing the DirectControl Agent

The DirectControl Agent for Mac can be installed in several different ways. The procedure in this section shows how do so by double-clicking the IBM Security Installer package (DMG) and following the instructions displayed on the screen. This installation method is recommended for most users when installing on a single computer or a limited number of computers.

When you use the IBM Security package installer, you will be prompted to join the domain. You may also join the domain after installation using either the adjoin command-line program or the IBM Security Directory Access plug-in.

IBM Security provides a number of other ways to install the DirectControl Agent for Mac

  • By executing the DirectControl Agent for Mac installation script, install.sh in a Terminal window on a Mac computer and following the instructions displayed by the script.

    If you are an experienced UNIX administrator and are familiar with UNIX command-line installations, running install.sh is a good method to use. When you install using the install.sh script, you can automatically join an Active Directory domain as part of the installation process; see Installing Using the install.sh Script for details.

  • By installing remotely, without user interaction, using Apple Remote Desktop. This is a good method to use if you are using Apple Remote Desktop for software distribution. With Apple Remote Desktop you can add pre- and post-installation scripts that allow you to join the remote computer to a domain after installation; see Installing Silently on a Remote Computer for details.

To install the DirectControl Agent for Mac on a Mac computer using the graphical user interface:

  1. Before installing the DirectControl Agent for Mac, disable Apple’s built-in Active Directory plug-in, and remove Active Directory from the Authentication, and Contacts search paths. For more information, see Disabling the Apple Built-in Active Directory Plug-in.

  2. In addition, be certain that the Apple Directory Utility is closed.

  3. Log on with the Administrator account.

  4. Navigate to the directory on the CD or your local network where the agent package is located. For example, if you are installing from the IBM Security CD, open the MacOS directory.

  5. Double-click the DMG file, for example:

    centrifydc-release-mac10.10-x86_64.dmg

  6. Double-click ADCheck to open the ADCheck utility.

    Alt

    ADCheck performs a set of operating system, network, and Active Directory checks to verify that the Mac computer meets the system requirements necessary to install the DirectControl Agent for Mac and join an Active Directory domain.

  7. Enter the domain you intend to join with the Mac computer and click AD Check; for example:

    Alt

  8. Review the results of the checks performed. If the target computer, DNS environment, and Active Directory configuration pass all checks with no warnings or errors, you should be able to perform a successful installation and join the specified domain. If you receive errors or warnings, correct them before proceeding with the installation; see the Administrator’s Guide for Linux and UNIX for more information about ADCheck.

  9. Double-click the IBM Security DC package to open the Installer:

    Alt

  10. Review the information in the Welcome page, then click Continue.

  11. Review or print the terms of the license agreement, then click Continue; click Agree to agree to the terms of the license agreement. Then click Install (note that you cannot change the volume on which the agent is installed — it must be on the same volume as Mac OS X).

  12. If prompted, enter the administrator name and password, and click Install Software to install the DirectControl Agent for Mac.

    Alt

    If you see the following warning box, click OK. If you did not have Directory Utility running during the installation, you can ignore the warning. If Directory Utility was open, you can quit and restart it to show the correct status of the IBM Security plug-in.

    Alt

    The installation process runs and presents the Installation Completed page once the DirectControl Agent for Mac is installed.

    Alt

  13. Select Launch IBM Security Join Assistant if you want to join a domain, then click Continue.

    If you know that you want to use IBM Security zones in your environment, exit the installer now. You must create zones first, before you can join to one. Refer to Deciding When and How to Join a Domain for more information.

    If you chose not to launch the IBM Security Join Assistant before clicking Continue, the installer presents a summary indicating that the installation was successful. You can now close the installer.

    If you chose to launch the IBM Security Join Assistant, you can start the process of Joining an Active Directory Domain described in the next section.

    If the Mac system is MacOS 11 or later, you must configure full disk access for the DirectControl Agent for Mac before you join the system to an Active Directory domain.

Joining an Active Directory Domain

This topic shows how to use the IBM Security Join Assistant to join a domain. To join a domain, you must be a domain admin or a domain user with permission to create computer objects. If necessary, your domain administrator can use the Delegation Wizard to delegate permission to create computer objects. Refer to Who Can Add a Workstation to a Domain for more information.

Alternately, you may run the adjoin command-line utility, interactively or in a script, for each Macintosh computer you want to add to a domain in the forest. See the Administrator’s Guide for Linux and UNIX for details.

To join the Mac to a domain:

  1. Launch the IBM Security Join Assistant.

    There are two ways to launch the IBM Security Join Assistant:

    • from the DirectControl agent installer, as described in Installing the DirectControl Agent for Mac.

    • click Applications > Utilities > IBM Security, double-click IBM Security Join Assistant to open it, then click Continue on the Welcome page

      Alt

  2. Enter the active directory domain that you want to join as well as administrator credentials for that domain, then click Continue.

    A page appears that allows you to select how to join the domain with an option to enroll in the Privileged Access Service.

    Alt

  3. Select from the following options:

    Select this option To do this
    Auto Joins the computer through Auto Zone, which allows joining a computer with little or no configuration. This option is recommended for most installations.
    Zone Joins to the zone that you type in the box. Note that you must have created at least one zone before you can use this option.
    Computer name Defaults to the name of the computer on which you are running the join assistant, but you can change it if you want to use a different name for the local host in Active Directory.

    Enrollment is no longer supported.

  4. (Optional) Click the arrow to expand the Advanced Options and select any Advanced Options that you want to use to join the device.

    Select this option To do this
    Overwrite existing joined computer Overwrite the information stored in Active Directory for an existing computer account. This option allows you to replace the information for a computer previously joined to the domain. If there is already a computer account with the same name stored in Active Directory, you must use this option if you want to replace the stored information. You should only use this option when you know it is safe to force information from the local computer to overwrite existing information. Checking this option is the same as running the adjoin command with the --force option.
    Container DN Specify the distinguished name (DN) of the container or Organizational Unit in which you want to place this computer account. By default, computer accounts are created in the domain’s default Computers container. Click Browse to browse Active Directory and select the container to use, or click Container DN and enter the name of the container in distinguished name format; for example, if the domain suffix is acme.com and you want to place this computer in the paris.regional.sales.acme.com organizational unit, you would type: ou=paris, ou=regional, ou=sales Checking this option is the same as running the adjoin command with the --container option.
    Preferred Domain Server Specify the name of the domain controller to which you prefer to connect. You can use this option to override the automatic selection of a domain controller based on the Active Directory site information. Checking this option is the same as running the adjoin command with the --server option.
    Computer Alias Name Specify an alias name you want to use for this computer in Active Directory. This option creates a Kerberos service principal name for the alias and the computer may be referred to by this alias. Checking this option is the same as running the adjoin command with the --alias option.

  5. Click Join.

    IBM Security Join Assistant informs you that you have successfully joined your Mac to your Active Directory domain at <mydomain.com>.

  6. Click Done to close the IBM Security Join Assistant.

    Your Active Directory users can now log on to the joined Mac computer, as described in Logging onto the Mac after Joining a Domain.

Configuring Full Disk Access for the DirectControl Agent for Mac

Due to a limitation of MacOS 11.x and MacOS 12.x, “Full Disk Access” is required for the DirectControl Agent for Mac. You can configure this yourself if you're an administrator on the computer, or you can set it by way of your MDM (Mobile Device Management) provider.

To configure full disk access as an administrator:

  1. Log in to the Mac computer as an administrator user.

  2. Open System Preferences.

  3. Click Security & Privacy.

  4. Click Privacy.

  5. Click Lock and then enter the password or use TouchID to unlock.

  6. In the left pane, scroll down and select Full Disk Access.

  7. Click + (the plus button).

  8. Press and hold these three keys together: Shift + Command + G.

  9. Enter the path "/usr/local/sbin/adclient" and click GO, then click Open to add the path.

  10. Repeat step 7 and 8, then input the path "/Applications/Utilities/Centrify/Centrify Join Assistant.app" and click GO, then click Open to add the path.

  11. Repeat step 7 and 8, then input the path "/Applications/Utilities/Centrify/Smart Card Assistant.app" and click GO, then click Open to add the path.

  12. Click Lock again to lock the system preferences.

    Alt

Configuring Full Disk Access Through Your MDM Provider

Contact your MDM provider for more information. Your MDM provider will need the following information:

% codesign -dv /usr/local/sbin/adclient
Executable=/usr/local/sbin/adclient
Identifier=adclient
...
% codesign -dr - /usr/local/sbin/adclient
Executable=/usr/local/sbin/adclient
designated => identifier adclient and anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = "64CT837G5Z"
% codesign -dv /Applications/Utilities/Centrify/Centrify\ Join\ Assistant.app
Executable=/Applications/Utilities/Centrify/Centrify Join Assistant.app/Contents/MacOS/Centrify Join Assistant
Identifier=com.centrify.cdc.centrifyjoinassistant
...
% codesign -dr - /Applications/Utilities/Centrify/Centrify\ Join\ Assistant.app
Executable=/Applications/Utilities/Centrify/Centrify Join Assistant.app/Contents/MacOS/Centrify Join Assistant
designated => identifier "com.centrify.cdc.centrifyjoinassistant" and anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = "64CT837G5Z"
% codesign -dv /Applications/Utilities/Centrify/Smart\ Card\ Assistant.app
Executable=/Applications/Utilities/Centrify/Smart Card Assistant.app/Contents/MacOS/SCTool
Identifier=com.centrify.cdc.smartcardassistant
...
% codesign -dr - /Applications/Utilities/Centrify/Smart\ Card\ Assistant.app
Executable=/Applications/Utilities/Centrify/Smart Card Assistant.app/Contents/MacOS/SCTool
designated => identifier "com.centrify.cdc.smartcardassistant" and anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = "64CT837G5Z"

Configuring Full Disk Access for Apple Remote Desktop

If your organization uses Apple Remote Desktop to run any DirectControl Agent for Mac commands (such as adjoin, adleave, and so forth), you need to also set Full Disk Access for Apple Remote Desktop. You can do this either as an administrator user or through your MDM service, following the same procedures as mentioned earlier.

If you're configuring full disk access as an administrator, the application path to add is as follows:

/System/Library/CoreServices/RemoteManagement/ARDAgent.app

If you're configuring full disk access through your MDM provider, here's the information that your provider needs:

% codesign -dv /System/Library/CoreServices/RemoteManagement/ARDAgent.app
Executable=/System/Library/CoreServices/RemoteManagement/ARDAgent.app/Contents/MacOS/ARDAgent
Identifier=com.apple.RemoteDesktopAgent
...
% codesign -dr - /System/Library/CoreServices/RemoteManagement/ARDAgent.app
Executable=/System/Library/CoreServices/RemoteManagement/ARDAgent.app/Contents/MacOS/ARDAgent
designated => identifier "com.apple.RemoteDesktopAgent" and anchor apple

Logging onto the Mac After Joining a Domain

When using Auto Zone, all Active Directory users in the domain become valid users on a joined computer. To verify that the software is working properly, you can simply log into the Mac computer by using an Active Directory account.

On the Mac login screen, select Other and enter an Active Directory user name and password:

Alt

Upgrading The DirectControl Agent for Mac

In most cases, you can update agents on Mac computers by simply installing the new agent either directly or remotely on top of an existing agent. As a best practice, you should perform in-place upgrades using a local Mac administrative (admin) account or any other user account that has local administrative rights and reboot the computer after completing the upgrade. In most cases, you should not perform the upgrade while you are logged on as an Active Directory user in a currently active session.

In rare cases, you might be advised to run adflush to clear the Active Directory cache before performing an in-place upgrade. For example, if you are updating agents from version 4.x, or earlier, to 5.1.x, run adflush first to ensure a smooth upgrade. It is highly unusual for an upgrade to require you to leave and rejoin a managed Mac computer to the domain.