MacOS and Keychains

The most common function of Keychain in macOS is as a password manager, securely storing credentials which can be auto entered in to web pages and queried using the Passwords app. The Keychain is also used to store other sensitive data, such as WiFi credentials, certificates and passkeys. macOS keeps this data safe is by encrypting the contents of the Keychain so it's only available having authenticated at login.

How does the Keychain file get created?

When a new user is created on a Mac, the Keychain is created. At that point it's encrypted using the current password of the user account logging in. This sharing of credentials with the login process allows an automatic “unlock” of the keychain while logging in so accessing stored credential is seamless for the user.

Where is the Keychain stored?

The Keychain file is stored in the ~/Library/Keychains folder (where ~ replaces the name of the currently logged in user). The login.keychain file is the file that gets generated on first login and encrypted using the user’s password.

What happens if I delete the Keychain?

If you delete the Keychain file it will be re-created on the next login. All data, usernames and passwords stored in the deleted Keychain will be lost.

What issues can occur?

Most issues occur through the changing of user passwords. If you change a password for a local user account on a Mac using the standard macOS user interface the keychain will update to reflect that change. The original password will decrypt the Keychain and the new password will re-encrypt it.

Issues can occur with password changes if you're using an external identity provider (IdP) to authenticate when logging in to a Mac, for example where Macs are bound to a legacy Microsoft Active Directory Server for authentication. This allows a server administrator to reset or change the users password on the directory server so it no longer matches the password used to encrypt the users Keychain when it was created on a Mac.

In those circumstances the user logs in to a Mac they've used before, but this time logging in with their new directory password. They then see and error message informing that "The system was unable to unlock your login Keychain" which requires knowledge of the old password to overcome without having to abandon the old Keychain and create a new one.

What about Platform Single Sign On (PSSO)?

Most organisations using an external IdP to log in to a Mac will now be using cloud Entra ID services from Microsoft 365 to manage users. Microsoft's Enterprise SSO plug-in works in conjunction with macOS platform Single Sign On to allow users to sign in to Mac with their Microsoft Entra ID credntials.

Apple's integration of PSSO on macOS includes a password sync feature to stop issues with the Keychain. When a user changes their password in Microsoft 365 the new password is synchronised automatically with a Mac using Platform Single Sign On.