XCreds: How XCreds maps cloud authentication to local user account and resetting XCreds authentication DB

XCREDS MAPPING

When a user signs in for the first time to a Mac running XCreds, XCreds will create a macOS user account for them. XCreds does this using the authentication event returned from the cloud authentication provider. After a successful cloud login event XCreds will receive data from the cloud provider containing several values about the cloud user account. If the user identified already exists on the Mac, the user is signed in. Otherwise XCreds creates a new macOS user account for them.

Default Behavior

When creating or finding this macOS user account, XCreds by default will look in the cloud authentication data for a field named email. If the email field is found, XCreds will strip off the @ and domain and use the first part. If email is not there, it will do the same thing with the field called unique_name. If that does not exist, then sub is used. Once the username is figured out, the local system will be checked to see if that user exists. If not, it will be created. If it does, that will be used for the local user. For most organizations the first part of the email is unique. If that is the case there will be no conflicts.

Customized Mapping

If an organization administrator needs to change default behavior, XCreds provides a field called map_username that can be set using Profile Creator as explained in the XCreds Admin Guide. This field can be set to a different field name in the cloud authentication event data. The field name specified will be used instead of the email field when XCreds determines the macOS username to find or use for creating a new macOS account.

RESETTING

When doing a macOS migration, reinstall, or for resolving issues, it is sometimes beneficial to reset the authentication database back to factory default. The authentication db is responsible for determining if the login window is shown, and is also responsible for when the user is prompted for admin credentials.

Resetting the database

To reset the database, boot to recovery, open terminal and run this command (substitute /Volumes/”Macintosh HD” for your disk name):

mv /Volumes/"Macintosh HD"/var/db/auth.db to /Volumes/"Macintosh HD"/var/db/auth.db.aside        

Reboot after running this command. At reboot, macOS will recreate the auth.db. Note that this does not delete the database, but moves it aside to a file named auth.db.aside. Once everything is verified to work, you can remove auth.db.aside.