Tips for finding Knowledge Articles

  • - Enter just a few key words related to your question or problem
  • - Add Key words to refine your search as necessary
  • - Do not use punctuation
  • - Search is not case sensitive
  • - Avoid non-descriptive filler words like "how", "the", "what", etc.
  • - If you do not find what you are looking for the first time,reduce the number of key words you enter and try searching again.
  • - Minimum supported Internet Explorer version is IE9
Home  >
article

KB-2735: How does Account Migration work on Mac OS X?

Centrify Identity Service, Mac Edition ,  

12 April,16 at 11:11 AM

Applies to: All versions of Centrify DirectControl for Mac on OS X
 
Question:
 
When running Account Migration ( System Preferences > Centrify > Account Migration ), it states that the local account will be deleted or renamed. 
 
Is there a risk of losing data with this tool? 
 
What happens when migrating a local account to an AD account? 
 

Answer:
 
There are two main components to local accounts on Mac systems: 
  1. The profile index for the user list (Which is used for listing users out like in the System Preferences). 
  2. The actual home folder files themselves in the /Users/ directory. 
The warning that Account Migration gives refers only to the index (1).
Files in the home folder themselves (2), are left unchanged. 
 
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: 
  • (a) Backup the home folder to a disk image 
  • (b) Don't change the home folder 
  • (c) Delete the home folder 
User-added image
 
The option that Account Migration uses is (b) "Don't change the home folder". 

 
After deleting the index of the local account, the method of migration differs depending on the version of Centrify for Mac agent installed.

For agent version 5.2.1 and below:
  • After the index is removed, a mapping file which tells OS X that the 'orphaned' home folder in /Users/ will now be owned by the username of the AD account - in that when the AD user logs in, it knows to use the home folder of the previously-deleted local account. 
    • This is the process: 
      • Existing local account on Mac 
        • Local Account Username: test_local 
        • Local Account UID: 502 
        • Local Account Home: /Users/test_local/ 
      • AD account from domain 
        • AD Account Username: test_AD 
        • AD Account UID: 88888 
  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: 

    +test_AD:test_local::502:20::/Users/test_local: 
    +::::::: 
     
  6. The configuration file is reloaded and cache flushed to update the new user variables. 
  • Result:
    • Account: test_local 
      • Credentials will no longer work as it has been deleted off the system. 
    • 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. 
​​​
For agent version 5.2.2 and above:
  • In Centrify for Mac agent 5.2.2, the method of migration was changed to allow for better compatibility with Mobile Accounts and to simplify the home folder layout for migrated accounts.
  • As of version 5.2.2, the passwd.ovr mapping file is no longer used. 
    • This is the process:
      • After the local user index is removed, the local home folder is renamed to match the username of the target AD user
      • The permissions, UID/GID of the local home folder is updated to be owned by the AD user.
  • Notes:
    • After this new process, the local home folder layout will be exactly as if the AD user had always logged in with a local home folder. There will be no more record of the previous local account or their (no longer used) local UID.
    • Since the mapping file is no longer used - it also means there will be no entry in the Account Migration options to unlink any migrated accounts.
    • This means that if the migration needs to be reversed, the ownership of the local home folder will need to be manually reverted to a locally re-created Mac user account:
      1. Login to the Mac as Local Admin and create a new local user account
      2. Open up the /Users/ folder and remove the newly created local user's home folder
      3. Rename the migrated AD user's home folder back to the newly created local username
      4. Open Terminal and run:
        • sudo chown -R local_username /Users/local_username
      • ​​The home folder will now be reverted back to a regular local account on the Mac

Still have questions? Click here to log a technical support case, or collaborate with your peers in Centrify's Online Community.