How To Troubleshoot MacOS AD Binding Errors

Today in this post, I will discuss how to troubleshoot MacOS AD binding errors that you might get while testing MacOS Directory Binding using a Configuration Profile with Directory payload.

This is a follow up to my previous post on how to AD bind a Mac with Microsoft Intune which explains how you can use Profile Manager (macOS Server) to create a Configuration Profile (.mobileconfig) with Directory payload that can be delivered/deployed via an MDM solution (Intune in our case) to enforce/trigger the Active Directory bind.

There, I clearly mentioned that for the Configuration Profile as created using Profile Manager to be deployed via Intune, it firsts needs to be tested for a successful manual installation on a standalone Mac.

Considering real-world scenarios, it’s very likely that you would encounter a profile install failure when you try to validate the profile functionality by checking if it gets installed manually.

In such cases, how would you check why the profile install failed? How would you confirm if the profile install failure error is due to

• config issues of the profile itself (typo, etc.), or
• domain account as specified in the profile does not have enough rights on the OU, or
• any network related issues (DNS info not proper, Device can’t resolve the domain to proper host, etc.)

This blog post aims to empower you with the troubleshooting knowledge that will help you find out the reason for why the profile install failed and hopefully, fix the same as well.

Getting Started

If you have been following my blogs, you would know that I do prefer to provide a quick background related to the particular topic that I am talking about in the post.

Following the same approach, I would first like to take you through the Active Directory Binding Process of MacOS.

This is because if you know how a Mac device binds to an Active Directory, you would also know about the breakpoints involved in the process.

Quick Overview – MacOS Active Directory Bind Process

Consider that you are configuring Active Directory bind on a Mac device. Based on your preference (GUI or CLI), you configure the parameters as required using the

• Directory Utility tool (Active Directory Plug-in) and you click on the Bind button.
• Terminal using the dsconfigad command and you hit Enter.

 The event of processes that follows are as below.

1. The Mac device tries to discover the hosts available on the network that are providing LDAP, Kerberos service for the domain.

Considering that step 1 completed successfully and the Mac device discovered information (IP Address) of all the hosts providing LDAP and Kerberos services for the domain

2. The Mac device chooses any one of the hosts and creates a preliminary Kerberos configuration with which it tries to connect and authenticate to it.

Considering step 2 was a success,

3. The Mac device then queries the connected Domain Controller for the host information of the nearest Domain Controller.

4. The Domain Controller sends the host information of the nearest Domain Controller. [based on IP subnet of the Mac device]

5. With the host information of the nearest Domain Controller obtained from step 3 ( or preferred DC if provided), the Mac device creates the final Kerberos configuration [KRB5] that it will use to authenticate and connect to the LDAP and Kerberos service of the Domain Controller in context.

6. The Mac device connects to and authenticates to the Domain Controller and then uses the Global Catalog service to search the domain (and forest) for an existing computer record (if there exists one) that matches the Client ID as provided by the Admin. If no Client ID was predefined for the binding activity, it creates a new computer object in the OU as specified by the Admin.

As part of the final step, the Mac device updates the service principals for the computer record (domain SID and DNS records of the same) in Active Directory.

Just for reference, the below snap (had to trim due to size) tries to show you how it looks when viewed from events on the Mac itself. 

Note that steps required for the Mac to discover and connect to any random Domain Controller and then retrieve the host information for the nearest Domain Controller is skipped if the Directory Bind specifies a Preferred Domain Controller.

DNS plays an important role as the Mac device should be able to resolve/retrieve the different service records (LDAP, Kerberos, Kpasswd, GC) for the Active Directory domain in context.

Breakpoints of MacOS Active Directory Bind Process

Now that we have an overview of the MacOS Active Directory bind process, let’s understand the breakpoints of the process as well.

• The credential of the domain account as provided should be valid or else this would fail.

• The domain account that was provided while initiating the bind must have the rights to create/update/manage computer objects in the OU as specified. Else it will fail.

• The initial host discovery is entirely dependent on DNS service, and as such if the Mac device is not configured with proper DNS server info, the process fails there itself.

• If there is a firewall configured, then you need to ensure that the required ports on the Domain Controller are accessible (open) so that the Mac device can use it to connect to the required services.

Now let’s get back to the main agenda of this post.

How To Troubleshoot MacOS AD Binding Errors

To troubleshoot any issue, you require to check a set of logs or events that can help you to trace and get to the cause of the issue.

This blog post shows how you can use the Console app for troubleshooting MacOS AD Binding Errors.

The macOS Console app is a powerful in-built tool for viewing logs and error events that you can use for troubleshooting and get to know why the Configuration Profile with Directory payload failed to get installed.

Check Profile Install Failure Error with MacOS Console

You will find the Console app here at /Applications/Utilities folder of your Mac or you can also call it to action using the Spotlight (Command + Space) feature.

Before you click on the Install button for the profile to test if it installs successfully or not, it is suggested that you

• Open the Console app and click on Start to start capturing the log streams.

• Go back to System Preferences > Profiles and now click on the Install button for the profile.

Let’s assume that the profile installation attempt fails and you get the below screen.

• Switch back to the Console app and first click on the Pause button to stop capturing further log streams.

• Next select the Errors and Faults tab.

You would now see all the error events that were generated by all the different processes for the time of capture. However, going through all these error events to trace the profile failure would surely take much time.

Thankfully, the Console app lets you filter log entries with queries using the search field at the top of the window, and it also supports complex queries.

Thus, if you know the particular process that the error would more likely be associated with, you can narrow your search by looking for events for that particular process.

For example, in our case here, I have searched to check the events for the process com.apple.preferences.configurationprofiles.remoteservice which is related to the profile install failure that we have.

With this, you can now easily check the reason why the configuration profile with directory payload is failing to install.

MacOS AD Binding Errors – Profile Installation Failed

For the purpose of this blog post, I managed to repro the below errors in my lab environment.

Hopefully, these would be the ones that you are most likely to get if are trying out MacOS AD Binding using a Config Profile (.mobileconfig) configured with Directory payload.

Error #1: Attempts to bind to the server ‘<domain>’ failed due to a credentials problem

[ERROR] Profile installation (Settings for Joymalya’s Mac mini (com.apple.mdm.Joymalyas-Mac-mini.local.4f2c60cf-369d-4463-8ad5-8bb819fe517e.alacarte:4f2c60cf-369d-4463-8ad5-8bb819fe517e)) (Error Domain=ConfigProfilePluginDomain Code=-319 "The ‘Directory Binding Account’ payload could not be installed. Attempts to bind to the server ‘intunewithjoy.in’ failed due to a credentials problem." UserInfo={NSLocalizedDescription=The ‘Directory Binding Account’ payload could not be installed. Attempts to bind to the server ‘intunewithjoy.in’ failed due to credentials problem.})

Cause

• The Domain Account credentials provided/specified in the Config Profile is not valid. The error maybe is because of a typo which is the most common.

Resolution

• Check for any typo in the credentials for the Domain Account while creating the Config Profile and correct the same.

Verify that the provided credentials work. Check if the Domain Account has its password expired or if the account is in a locked state. If possible, it is always advisable to use a Service Account with no password expiry set, created only for the purpose of directory binding Mac devices.

Error #2: The server ‘<domain>’ either couldn’t be found, or was not responding

[ERROR] Profile installation (Settings for Joymalya’s Mac mini (com.apple.mdm.Joymalyas-Mac-mini.local.4f2c60cf-369d-4463-8ad5-8bb819fe517e.alacarte:4f2c60cf-369d-4463-8ad5-8bb819fe517e)) (Error Domain=ConfigProfilePluginDomain Code=-319 "The ‘Directory Binding Account’ payload could not be installed. The server ‘intunewithjoy.in’ either couldn’t be found, or was not responding." UserInfo={NSLocalizedDescription=The ‘Directory Binding Account’ payload could not be installed. The server ‘intunewithjoy.in’ either couldn’t be found, or was not responding.})

This is again a very common error that you are likely to encounter if you are testing Mac AD Binding.

Cause

• DNS resolution for the domain not resolving correctly to the host (Domain Controller)

Resolution

• Use the Terminal to check if the Mac device is able to retrieve the required service records (SRV) for the domain using the command format as follows: host -t SRV _<SERVICE>._<PROTOCOL>.<YOURDOMAIN>

It is recommended to use a DNS server that acts as the authoritative name server for the Active Directory domain or use any other DNS server that is configured to allow Dynamic DNS updates from the Active Directory servers , so that the Mac device can retrieve the required service records.

• Confirm that the Mac device can connect to the required ports of the Domain Controller for the respective services.

Port	Protocol	Service
53	TCP/UDP	DNS query to resolve host
389	TCP/UDP	LDAP
88	TCP	Kerberos
464	TCP/UDP	Kpasswd [used to change Kerberos password]
3268	TCP	Global Catalog query to search domain objects

If the Mac is unable to connect to the ports, you would get the same error.

Why I received this error and how I resolved?

For me, my test lab consisted of a physical Mac Mini (which I am trying to bind) and a Domain Controller that is sitting inside a Hyper-V VM.

When I did a quick ping to the domain from the Mac, I saw that it was not able to resolve it to the correct host. Somehow the Mac was resolving the domain to the IP set on the NIC for the external network (maybe due to the domain being a public domain), instead of using the internal private network in which the DC resides.

Checked to see if I have put the correct DNS host information and it was correct indeed. Still the error. So, I resorted to modifying the hosts file on the Mac to point the FQDN to the IP of the local DC in my virtual lab.

And this corrected the issue for me. The Mac now correctly resolved the domain to the IP of my Domain Controller.

Error #3: Attempts to bind to the server ‘<domain>’ returned an unspecified problem

[ERROR] Profile installation (Settings for Joymalya’s Mac mini (com.apple.mdm.Joymalyas-Mac-mini.local.4f2c60cf-369d-4463-8ad5-8bb819fe517e.alacarte:4f2c60cf-369d-4463-8ad5-8bb819fe517e)) (Error Domain=ConfigProfilePluginDomain Code=-319 "The ‘Directory Binding Account’ payload could not be installed. Attempts to bind to the server ‘intunewithjoy.in’ returned an unspecified problem." UserInfo={NSLocalizedDescription=The ‘Directory Binding Account’ payload could not be installed. Attempts to bind to the server ‘intunewithjoy.in’ returned an unspecified problem.})

Cause

• The error message in itself does not reveals much and can be due to various reasons.

For example, you may get this error if the Domain Account provided in the directory payload does not have permission in AD to create/manage objects in the specified OU.

Resolution

• Verify and ensure you are meeting all the pre-requisites for Mac AD Binding.

I actually don’t know the exact reason for which I got this error. Because for me, the error disappeared after a device restart which makes me think that it had something to do with the stale cache of the system maybe.

Have you encountered any other error while working on AD binding Mac devices? Do let me know so that I can include it here for the benefit of all.

The End

As a disclaimer, I would again state that AD Binding a Mac device should not be your preferred choice and is also not the most recommended thing within the IT community. There are specialized solutions available in the market like JAMF with its JAMF Connect which helps to provision a Mac device using an enterprise managed single identity.

In the end, I would say that it all comes down to what tools you have in your arsenal and how you can make use of them to get to your end-goal.

That was all for today. Hope you would find this post informative and useful.