Join a Mac Computer to an Active Directory Domain

You can join the macOS system to a domain by using the command line. Before joining a domain:

  • Make sure that the computer's name server can find the domain. To check, run the command:
    nslookup domainName
  • Make sure that the computer can reach the domain controller. To check, run the command:
    ping domainName

As of AD Bridge 9.1.0, the user interface no longer performs domain joins. Domain joins must be performed by using the command line. For documentation about previous versions of AD Bridge, please see the BeyondTrust AD Bridge Documentation Archives.

Join from the Command Line

When you join a domain using the command line utility, AD Bridge uses the hostname of the computer to derive a fully qualified domain name (FQDN). It then automatically sets the FQDN in the /etc/hosts file.

Using sudo, execute the following command in Terminal. Replace domainName with the FQDN of the domain to join and joinAccount with the user account that has privileges to join computers to the domain.

sudo /opt/pbis/bin/domainjoin-cli join domainName joinAccount

Example:

sudo /opt/pbis/bin/domainjoin-cli join example.com Administrator

To join a computer to the domain without changing the /etc/hosts file, run the following command as root:

/opt/pbis/bin/domainjoin-cli join --disable hostname domainName joinAccount

Terminal prompts you for two passwords:

  • The user account on the Mac that has admin privileges
  • The user account in Active Directory that you set in the join command

After you join a domain for the first time, you must restart the computer before you can log in.

You can also add the password for joining the domain to the command, but we recommend that you do not use this approach. If you do so, another user could view and intercept the full command that you are running, including the password. Should you choose to send the password, the command is:

sudo /opt/pbis/bin/domainjoin-cli join domainName joinAccount joinPassword

Example:

sudo /opt/pbis/bin/domainjoin-cli join example.com Administrator YourPasswordHere

Set Display Login Window Preference

After you join the domain, you can set the display login window preference on the Mac:

  1. On the Apple menu, click System Preferences.
  2. Under System, click Accounts.
  3. Click the lock, and enter an administrator's name and password to unlock it.
  4. Click Login Options.
  5. Under Display login window as, select Name and password.

Troubleshoot Computer Failing to Join a Domain

Make sure the computer's FQDN is correct in /etc/hosts. For the computer to process tickets in compliance with the Kerberos protocol and to function properly when it uses cached credentials in offline mode or when its DNS server is offline, a correct FQDN must exist in /etc/hosts.

You can determine the FQDN of a computer running Linux, Unix, or macOS by executing the following command:

ping -c 1 'hostname'

When you execute this command, the computer looks up the primary host entry for its hostname. In most cases, this means that it looks for its hostname in /etc/hosts, returning the first FQDN name on the same line.

As an example, the correct entry for the hostname qaserver in /etc/hosts is 10.100.10.10 qaserver.corpqa.example.com qaserver. If the entry in /etc/hosts is incorrect in its order or format, such as 10.100.10.10 qaserver qaserver.corpqa.example.com, the computer's FQDN would be read as and would become qaserver.

If the host entry cannot be found in /etc/hosts, the computer looks for the results in DNS instead. This means that the computer must have a correct A record in DNS. If the DNS information is wrong and you cannot correct it, add an entry to /etc/hosts.

Turn Off macOS Directory Service Authentication

If you are migrating from Open Directory or Active Directory and you had set authentication from the command line with dsconfigad or dsconfigldap, you must run the following commands to stop the computer from trying to use the built-in directory service even if the Mac is not bound to it:

dscl . -delete /Computers
dscl /Search -delete / CSPSearchPath /LDAPv3/FQDNforYourDomainController
dscl /Search -delete / CSPSearchPath /Active\ Directory/All\ Domains
dscl /Search/Contacts -delete / CSPSearchPath /Active\ Directory/All\ Domains
dscl /Search/Contacts -delete / CSPSearchPath /LDAPv3/FQDNforYourDomainController