Understanding Account Migration on Centrify for Mac OS X

Account Migration, or Account Mapping can be a tricky concept to understand at first, but once you get your head around the idea of home directory locations and the importance of user UIDs – the next step to comprehension is only a short hop away.

First, let’s understand the original purpose of Account Migration:
  • Imagine a user that has been logging into their Mac with a regular local account, all their documents, settings and other stuff is stored locally on the machine in their local home folder.
  • The Mac is joined onto a domain and the user can also use their network credentials to login to the Mac as well and take advantage of all that lovely single-sign on goodness.
  • So at this point, the user has two (separate) accounts:
    1. The local Mac account, with all their work in the local home folder associated with that local account.
    2. The network AD account, for accessing company resources on the network.
So what does Account Migration do?
  • It effectively merges the two accounts so that the user gets to log into the Mac with their network credentials, and access their company goodies, but still get their original desktop and everything else in their original home folder.
  • From the user’s point of view – the only change is that they now only need to login with their network credentials to get into their Mac – nothing else is different.
  • After logging in – their desktop user experience stays the same as it always has been…apart from that they don’t have to keep entering their credentials again to get into their corporate network. Brilliant!
So how does it work?

(For the purposes of this article…) there are two main components to local accounts on Mac systems:

  • The profile index for the user list — the “pointer” that let’s OS X know that there is a local account here.
  • The actual home folder itself in the /Users/ directory.

The first component, the “pointer”, is only needed for local accounts, it is what OS X uses to list out user accounts in the System Preferences. Network accounts don’t use this – this is why network logins only show up in the System Preferences user list while the Network account is actually logged in, and disappears when they are logged out.

The important part is (2), that local home folder in the /Users/ directory.

When a Network account logs into the Mac, if it has a local home folder configured, then it will look in the /Users/ directory to see if that account’s home folder is there, if it’s not, then it will create one. If it’s already there – then it will link the Network account to that home folder, thus “claiming” that home folder for this Network account to use.

For this linking process to be successful, two things must match:
  • The local home path must be correct, in most cases this would be: /Users/username
  • The UID of the Network account must match the UID of /Users/username

If either of these two elements fall out of sync, the login will fail.

The first step of Account Migration is to delete the local index of the local account and leave the local home folder “orphaned”.
Note that at this point the local account is effectively being deleted off the system.
But don’t fret! Other than the local account credentials being cleared, no other data is removed.

The same behaviour can be seen when manually deleting a local user account in the System Preferences > Users & Groups menu.

The deletion menu will give three options:

System Preferences - Users and Groups

The option that Account Migration uses is (b) “Don’t change the home folder”.

After deleting the index of the local account, a mapping file is then created which tells OS X that the ‘orphaned’ home folder in/Users/ is now going to be owned by a new account – the AD account.

When the AD user logs in, it will use the home folder of the previously-deleted local account.
Thus: Network credentials + original home folder = happy user experience.


Here is the process in bullet form:
    • Example scenario
      Local Account Username: test_local
      Local Account UID: 502
      Local Account Home: /Users/test_local/
      AD Account Username: test_AD
      AD Account UID: 88888
  • Procedure
    1. Open Account Migration, select “test_local” for mapping over with “test_AD”
    2. Local Account Username & UID is deleted off the system user list
    3. /Users/test_local/ remains on system, folder and file ownership properties UID is still at “502”
    4. Mapping file created at: /etc/centrifydc/passwd.ovr
    5. Entry is created in the mapping file to inform OS X of the new owner of the home folder:
    6. The configuration file is reloaded and cache flushed to update the new user variables.
  • Result:
    1. Account: test_local
      • Credentials will no longer work as it has been deleted off the system.
    2. Account: test_AD
      • AD credentials will log the user into the system and the user will see the home folder and preferences for the “test_local” user as if “test_AD” was always the local user.


Savvy readers will also have noticed that this method can also be used for Mac systems that were previously joined to a domain via an alternative method, (for example the built-in Apple AD plugin) and so will have created local home folders for AD users with their own UIDs (which may be different to Centrify UIDs).

Theoretically, any orphaned home folder or home folder with a conflicting UID can be reclaimed back using Account Migration.

Note that migrated account settings take precedent over the AD account attributes that were configured in AD for the Mac where the account mapping file resides. So even if an AD account is configured with a network home folder on all other systems – if they were to login to a specific Mac where the mapping file dictates their account is now pointing to a particular local home folder, then the network home folder from AD will be ignored and on that specific Mac – the AD account will have a local home folder.


The original version of the Account Migration Tool was a separate download and could only migrate one account per machine.

From Centrify version 5.1.0 onwards, you can map multiple accounts at the same time and the whole visual interface has been overhauled to give a much clearer view of which home folders have been mapped over to which AD account.

If you have determined that Account Migration will be necessary for your Mac accounts, then it is highly recommended to update to at least version 5.1.0 and manage the accounts via the built-in interface instead of the old standalone tool. The panel can be accessed via:

System Preferences > Centrify > Account Migration

Centrify Account Migration Settings


Of course, if the only thing different about the local home folder is that the UID does not match the AD account UID (but the path is correct). Then you could throw caution to the wind, skip Account Migration altogether and just force back ownership to the AD account:

As Local Admin, open the Terminal and run:

sudo chown -R ad_username /Users/ad_username/

So many options!

Part 2: A bit more on knowing when Account Migration is needed, and when it is NOT needed