About

In this tutorial, you are going to learn how to set up your Yubikey with Mac OS, so that Mac OS requires your Yubikey and its corresponding pin number when logging into your mac on boot, unlocking your mac from it’s screensaver, or waking it from sleep. This will also teach you how to force your Mac to lock itself as soon as remove your Yubikey from it. This has been tested and working on MacOS Big Sur and above using Intel Macs. Instructions for this may be different if you are using an ARM based Mac with the M1 or M2 chips. So without further ado, lets begin, starting at step 1.

1) Download Software:

First, download Yubikey Manager at https://developers.yubico.com/yubikey-manager-qt/Releases/yubikey-manager-qt-latest-mac.pkg

2) Install Software:

Double click on the package in your downloads folder, and when it opens click continue, and then install.

3) Open Software:

Once installed, double click Yubikey Manager in your applications folder to open it up.

4) Insert Yubikey:

Insert your main Yubikey (or backup Yubikey if your are creating a backup) into your Mac’s USB drive, and watch Yubikey Manager recognize your Yubikey by displaying its model, Firmware version, and Serial Number.

Yubikey Manager for MacOS with Yubikey inserted

5) Select PIV

In Yubikey Manager, select the “Applications” menu, and then select “PIV” from the pulldown menu.

6) Select Configure PINs

On the “PIV” window, select the “Configure PINs” button.

7) Change PIN

In the “Configure PINs” menu, select the “Change PIN” button. Checkmark the “Use default” (unless you already created a pin, which in that case, you can skip this step) checkbox on the “Current PIN” line, then enter a new secret pin number in the second and third line. Hit the “Change PIN” button again to confirm your new pin.

Yubikey Manager for MacOS – “Change PIN”

8) Change PUK

You should now be back on the “Configure PINs” window of Yubikey Manager. Now click the “Change PUK” button. Now, in the “Change PUK” window, checkmark the “Use default” (unless you already created a PUK, which in that case, you can skip this step) checkbox on the “Current PUK” line, then enter a new secret PUK number in the second and third line. Hit the “Change PUK” button again to confirm your new PUK.

Yubikey Manager for MacOS – “Change PUK”

9) Change Management Key

Back in the “Configure PINs” window, click the “Change Management Key” button. Now, in the “Change Management Key” window, checkmark the “Use default” (unless you already created a Management Key, which in that case, you can skip this step) checkbox on the “Current Management Key” line. Click on the “Algorithm” pull down menu, and select AES256. Then click the “Generate” button. A New Management Key will be generated in the “New Management Key” line. Write this management key down in a VERY SAFE PLACE so you don’t forget it. If this is your backup Yubikey then be sure to use the same “Management Key” as your first Yubikey, instead of using the “Generate” button. Finally, click the “Protect with PIN” checkbox, and then click on the “Finish” button. Enter your PIN to confirm.

Yubikey Manager for MacOS – “Change Management Key”

10) Begin Setup for MacOS

Back on the “Configure PINS” window, you will see a “Back” button in the bottom left of the window. Click it to arrive back on the “PIV” window. Here, in the top right corner above the “Reset” button, you will see a small computer icon with the words “Setup for macOS” next to it. Click those words to be brought to the “Setup for macOS” window. In the bottom right corner of this new window, you will see a “Setup for macOS” button. Click it, and enter your PIN in the popup window, then hit “ok”.

Yubikey Manager on MacOS – “Setup for MacOS”

11) Pair Yubikey with MacOS

Finally, in the next window at the bottom of the window, you will see a message that says “remove and re-insert your Yubikey to pair with macOS”. Do as it says. Once you do, you will see a notification box in the upper right hand corner of macOS that says “Yubico Yubikey OTP+FIDO+CCID Unpaired SmartCard inserted: Personal Identity Verification token driver”.

Mac OS Yubikey Pairing – “Yubico Yubikey OTP+FIDO+CCID Unpaired SmartCard inserted: Personal Identity Verification token driver”

Below that it will have a “Pair” button. Click that “pair” button, and a new popup will appear that reads “Do you want to connect the inserted SmartCard with the current user?”.

Mac OS Yubikey Pairing – “Do you want to connect the inserted SmartCard with the current user”

Again, click the “Pair” button in that popup box. Enter your password in the password popup, and click “Pair” once again. Finally, enter your keychain password (your Mac OS admin password) in the final pair box and click “OK”.

NOTE: You have now paired your Yubikey with macOS. Unless you still need to pair your backup Yubikey, you may now close Yubikey Manager.

12) Create Backup Yubikey

Create a backup Yubikey by repeating steps 4 through 11. Skip this step if you have already created and paired a backup Yubikey with Yubikey Manager.

NOTE: At this point, your Yubikey (and your backup Yubikey) should be paired with macOS, and you should be able to use it to unlock your mac with your Yubikey pin number while your Yubikey is inserted.

13) Test and Verify Your Paired Yubikey

To test your paired Yubikey, open up system preferences and click the “Security & Privacy” setting. Then click on the “General” tab, and select the checkmark next to “Require password immediately after sleep or screen saver begins”.

Mac OS System Preferences – “Require password immediately after sleep or screen saver begins”

Then go back to the main “System Preferences” screen, and click on “Desktop & Screen Saver”. Now click on the “Screen Saver” tab. Then click on the “Hot Corners” tab in the bottom right of the window, and choose the bottom left hot corner tab, and select the “Start Screen Saver” option. Then click “OK”.

MacOS System Preferences – Enabling Screensaver on bottom left hot corner for paired Yubikey testing

Now drag your mouse to the bottom left corner of your screen and your screen saver should activate. Then move your mouse to get back into your mac desktop. If your Yubikey is inserted, a pin number prompt will appear asking you to enter the pin number for your yubikey. Enter your Yubikey’s pin number there, and get back to your Mac OS desktop. This confirms that your Yubikey works for logging into your mac from a screensaver or sleep.

NOTE: There is a problem with this setup now. If your Yubikey is not inserted, you may still use your password to login to your Mac from the screensaver or from sleep when the Yubikey is not inserted. Furthermore, when you first log into your mac upon system boot, your mac will also allow a password to be used as opposed to ONLY allowing your Yubikey and its pin number. If filevault is enabled (which it should be for security purposes), Mac OS will require your admin password to unlock filevault, and will then pass that same password to your Mac OS system, to unlock your desktop. We need to fix these things, so that you can unlock filevault with your Mac password, and then you are forced to insert your Yubikey and enter it’s PIN number to unlock your Mac desktop. As of now, there is no way to unlock filevault using a yubikey, so we still need to use a password for filevault. However, we can change things to be sure that if filevault is unlocked, still nobody can get into your mac without using your Yubikey (or possibly the recovery mode terminal, see here for more info). This requires changing your Mac’s settings so that it offers 2 password prompts (1 for filevault password, and 1 for your Yubikey PIN number while your Yubikey is inserted), and rejects any other password/PIN from being valid without your Yubikey being inserted. Continue to step 14, to fix these issues and force Mac OS to require your Yubikey PIN upon login.

WARNING! Before proceeding with the next step, be ABSOLUTELY SURE you have paired your Yubikey and a backup Yubikey with MacOS, or you may completely lock yourself out of your Mac.

14) Backup MacOS Configuration Files

First we need to create backups of your original “login“, “sudo” and “su” configuration files located in your /etc/pam.d/ directory of MacOS. This way, if you ever lose both Yubikeys, you can still recover your Mac by restoring these original files in MacOS recovery mode. Lets now back these files up by opening your terminal application in MacOS and entering the following command exactly as it is written below:

sudo cp /etc/pam.d/login /etc/pam.d/login_backup_`date "+%Y-%m-%d_%H:%M"` && sudo cp /etc/pam.d/sudo /etc/pam.d/sudo_backup_`date "+%Y-%m-%d_%H:%M"` && sudo cp /etc/pam.d/su /etc/pam.d/su_backup_`date "+%Y-%m-%d_%H:%M"`

Now, in your terminal, navigate to your /etc/pam.d/ folder and check that your files were properly backed up.

cd /etc/pam.d/ && ls -la

You should see a “login_backup...” file, a “su_backup...” file, and a “sudo_backup...” file listed in your terminal. If you don’t, then your backups weren’t created, and you didn’t enter my command correctly.

15) Setup Yubikey Authentication for su

Now, lets make your Mac enforce Yubikey authentication when using the su command. Enter the following command in your terminal to open up your su config file in nano text editor:

sudo nano /etc/pam.d/su

Once you are in nano editor hold the “control” button and the “k” key to erase every line in that file. Then copy the following text

# su: auth account password session
auth        sufficient    pam_smartcard.so
auth        required      pam_rootok.so
auth        required      pam_group.so no_warn group=admin,wheel ruser root_only fail_safe
account     required      pam_permit.so
account     required      pam_opendirectory.so no_check_shell
password    required      pam_opendirectory.so
session     required      pam_launchd.so

and paste it into your nano editor by pressing the “command” and “v” key at the same time. Then hit the “control” and “x” key at the same time. Then press the “y” key. Then press the “enter” key to save the file.

16) Setup Yubikey Authentication for sudo

Now, lets make your Mac enforce Yubikey authentication when using the sudo command. Enter the following command in your terminal to open up your sudo config file in nano text editor:

sudo nano /etc/pam.d/sudo

Once you are in nano editor hold the “control” button and the “k” key to erase every line in that file. Then copy the following text

# sudo: auth account password session
auth        sufficient    pam_smartcard.so
auth        required      pam_opendirectory.so
auth        required      pam_deny.so
account     required      pam_permit.so
password    required      pam_deny.so
session     required      pam_permit.so

and paste it into your nano editor by pressing the “command” and “v” key at the same time. Then hit the “control” and “x” key at the same time. Then press the “y” key. Then press the “enter” key to save the file.

17) Setup Yubikey Authentication for login

Now, lets make your Mac enforce Yubikey authentication when logging on boot. Enter the following command in your terminal to open up your login config file in nano text editor:

sudo nano /etc/pam.d/login

Once you are in nano editor hold the “control” button and the “k” key to erase every line in that file. Then copy the following text

# login: auth account password session
auth        sufficient    pam_smartcard.so
auth        optional      pam_krb5.so use_kcminit
auth        optional      pam_ntlm.so try_first_pass
auth        optional      pam_mount.so try_first_pass
auth        required      pam_opendirectory.so try_first_pass
auth        required      pam_deny.so
account     required      pam_nologin.so
account     required      pam_opendirectory.so
password    required      pam_opendirectory.so
session     required      pam_launchd.so
session     required      pam_uwtmp.so
session     optional      pam_mount.so

and paste it into your nano editor by pressing the “command” and “v” key at the same time. Then hit the “control” and “x” key at the same time. Then press the “y” key. Then press the “enter” key to save the file.

18) Check and Enable Smartcard Login State

At this point, you have configured the enforcement of Yubikey authentication for 1) logging into your mac, 2) using the sudo command, and 3) using the su command. However, you still need to activate the enforcement of these new settings in Mac OS by enabling the smartcard login state. To check your current smartcard login state, enter the following command

sudo security authorizationdb smartcard status

It should return

Current smartcard login state: disabled (system.login.console disabled, authentication rule disabled)
YES (0)

Now, enter the following command to fully enable the smartcard login state and force smartcard authentication with your Yubikey.

WARNING! If your Yubikey is not paired with your mac before entering the next terminal command, you will completely lock yourself out of your Mac. Verify your Yubikey is paired before proceeding.

sudo security authorizationdb smartcard enable

It should return

Enter PIN for 'Certificate For PIV Authentication (Yubico PIV Authentication)':
YES (0)

19) Download and Inspect the Configuration Profile

Next we need to install a configuration profile to your System Preferences pane, which will tell your Mac not to allow a password on login, wake, or deactivation of your screensaver. For your convenience, I have created a configuration profile myself in which you can download directly from my website by clicking here. If you don’t trust the file, you may 1) inspect it by opening it up in a text editor such as “text edit” or “nano”, and inspect the code in it, or 2) you may create your own configuration profile yourself from scratch using Apple’s sample smart card-only configuration profile. For the sake of ease, we are going to just use my pre-configured custom configuration profile that is based off of Apple’s sample smart card-only configuration profile. But for the sake of security, we are going to start by looking at both Apples sample profile, and comparing it with my custom profile.

First, lets look at Apples sample profile which you can find at https://support.apple.com/en-us/HT208372. The contents are as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>PayloadContent</key>
	<array>
		<dict>
			<key>PayloadDescription</key>
			<string>Configures smart card-only</string>
			<key>PayloadDisplayName</key>
			<string>Smart card-only</string>
			<key>PayloadIdentifier</key>
			<string>com.apple.configprofile.78.</string>
			<key>PayloadOrganization</key>
			<string>Apple</string>
			<key>PayloadType</key>
			<string>com.apple.security.smartcard</string>
			<key>PayloadUUID</key>
			<string>5A15247B-899C-474D-B1D7-DBD82BDE5678</string>
			<key>PayloadVersion</key>
			<integer>1</integer>
			<key>UserPairing</key>
			<false/>
			<key>allowSmartCard</key>
			<true/>
			<key>checkCertificateTrust</key>
			<false/>
			<key>enforceSmartCard</key>
			<true/>
		</dict>
	</array>
	<key>PayloadDescription</key>
	<string>Smartcard profile.</string>
	<key>PayloadDisplayName</key>
	<string>Smart card-only</string>
	<key>PayloadIdentifier</key>
	<string>com.apple.configprofile.77</string>
	<key>PayloadOrganization</key>
	<string></string>
	<key>PayloadRemovalDisallowed</key>
	<false/>
	<key>PayloadScope</key>
	<string>system</string>
	<key>PayloadType</key>
	<string>Configuration</string>
	<key>PayloadUUID</key>
	<string>7D34CC86-C707-44D2-9A9F-C5F6E347BD77</string>
	<key>PayloadVersion</key>
	<integer>1</integer>
</dict>
</plist>

Then lets look at the downloaded “www.danran-rocks-yubikey-only-authentication.mobileconfig” file, which you can and should download here if you haven’t already.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>ConsentText</key>
	<dict>
		<key>default</key>
		<string>WARNING! Before doing anything, be sure that you have successfully paired your Yubikey, and backup Yubikey to MacOS. If you have not, and you proceed with this installation and further instructions, you may permanently lock yourself out of your Mac and MacOS. For more information and instructions go to https://danran.rocks/2022/09/how-to-use-a-yubikey-smart-card-to-force-passwordless-and-smart-card-only-login-and-authentication-on-macos</string>
	</dict>
	<key>PayloadContent</key>
	<array>
		<dict>
			<key>PayloadDescription</key>
			<string>Configures smart card-only</string>
			<key>PayloadDisplayName</key>
			<string>Enforce Yubikey authentication</string>
			<key>PayloadIdentifier</key>
			<string>com.apple.security.smartcard.8B66E145DC14483C9F1C176A31CDA948</string>
			<key>PayloadOrganization</key>
			<string>Apple</string>
			<key>PayloadType</key>
			<string>com.apple.security.smartcard</string>
			<key>PayloadUUID</key>
			<string>8B66E145DC14483C9F1C176A31CDA948</string>
			<key>PayloadVersion</key>
			<integer>1</integer>
			<key>UserPairing</key>
			<true/>
			<key>allowSmartCard</key>
			<true/>
			<key>checkCertificateTrust</key>
			<false/>
			<key>enforceSmartCard</key>
			<true/>
			<key>tokenRemovalAction</key>
			<integer>0</integer>
		</dict>
	</array>
	<key>PayloadDescription</key>
	<string>This profile will do the following: 1) Enforce Yubikey only authentication on MacOS login 2) Enforce Yubikey only authentication upon wake from sleep 3) Enforce Yubikey only authentication upon wake from screensaver 4) Allow the pairing of new Yubikeys when MacOS is unlocked. This profile needs extra configurations in system preferences to do the following: 1) Activate the screen saver lock upon removal of your Yubikey from your Mac. For the most up-to-date instructions see my guide by going to https://danran.rocks/2022/09/how-to-use-a-yubikey-smart-card-to-force-passwordless-and-smart-card-only-login-and-authentication-on-macos </string>
	<key>PayloadDisplayName</key>
	<string>Yubikey Only Authentication</string>
	<key>PayloadIdentifier</key>
	<string>com.apple.configprofile.15249132DB014BF78EF4297215C16238</string>
	<key>PayloadOrganization</key>
	<string>www.danran.rocks</string>
	<key>PayloadRemovalDisallowed</key>
	<false/>
	<key>PayloadScope</key>
	<string>system</string>
	<key>PayloadType</key>
	<string>Configuration</string>
	<key>PayloadUUID</key>
	<string>ED3BDA51-147C-47AF-AB06-9BBEC7DDDBB4</string>
	<key>PayloadVersion</key>
	<integer>1</integer>
</dict>
</plist>

As you can see, the only changes/modifications I made to Apple’s official sample profile, were changing some UUID’s, adding an installation consent text with a warning, added a “tokenRemovalAction” option (in case you want to change it to a “1” to force your mac to lock whenever your Yubikey is removed. Otherwise, you can activate this option in system preferences under the Security pane), changed the organization name to www.danran.rocks, and changed “UserPairing” to <true> (in case you want to pair other Yubikeys to your mac while it is unlocked. NOTE: If you don’t want to allow anyone to ever pair their Yubikeys to you mac again, change this to <false>). If you don’t want to trust my download, you may copy and paste my sample profile into a text editor and save it as a file named “whatever-you-want-to-name-it.mobileconfig”. If you haven’t already, go ahead and download my sample configuration profile here.

20) Install My Custom Configuration Profile

Once you have downloaded my sample configuration profile ( to your downloads folder, go ahead and double click on it. This will create a new pane in system preferences called “Profiles”. Go ahead and open up system preferences, then click on the “Profiles” pane.

MacOS System Preferences – Profiles Pane for enforcing Yubikey only authentication

Once you are in the profiles window, click the Install button, then click the install button again, and finally click the install button one last time to install this configuration. Enter your password or PIN, and vualá. You now have your Yubikey set up to enforce authentication on boot/login, when using the sudo command, or when using the su command. However there is one more thing we need to do before finishing this tutorial.

21) Lock Your Mac When Your Yubikey is Removed

Go back to the main system preferences pane, and click on “Security & Privacy”. Click on the “Advanced” button in the bottom right of the “Security & Privacy” pane. Then select the “Turn on screen saver when login token is removed”, and hit “OK”. This option will force your Mac to lock itself anytime your Yubikey is removed from it. With this option selected, you can only use your Mac while the Yubikey is inserted. Go ahead and test this by removing your Yubikey. Your mac will unlock, and you must re-insert your Yubikey to unlock it again.

22) Hardenening Your Mac With Firmware Password & Recovering From Lockout

If you don’t have a firmware password on your mac, then anyone with your MacOS password can boot your Mac into Recovery mode, and modify your Yubikey configuration files from the terminal in order to disable required Yubikey login into your Mac. The recovery mode is also a way for you to disable forced Yubikey login if you lose both of your Yubikeys and locked yourself out of your mac. For more recovery information you can find the instructions to recover your mac after lockout in the “Disable smart card-only authentication” section of this page.

Since we have both of our Yubikeys, we want to prevent any users with our MacOS password from modifying our configuration files to allow password only login to your Mac. Fortunately, since MacOS Big Sur, setting a firmware password is easy and possible. You can set this firmware password by simply booting up into Recovery mode (hold “Command & R” on boot), and selecting the “Set a firmware password” option from the recovery mode utilities menu. Once you do, enter a password that only you know, and be sure it isn’t the same password that you use to log into MacOS. REMEMBER THIS PASSWORD! This password will be required every time you boot your mac, thus preventing any malicious users from even getting into Recovery mode, in an attempt to modify your Yubikey config files. There we have it folks, a very private and secure Mac, which can’t be unlocked without a Yubikey!

23) DONATE!

If this tutorial it worked for you (which it should have), you could spread the love back and donate some change to my paypal, bitcoin address, or altcoin addresses.

PAYPAL:

BITCOIN (BTC) ADDRESS: bc1qxsqy0nl8f2rqsgpzzr8eh3c67vz7kjr2djyku4

BITCOIN CASH (BCH) ADDRESS: qzdkv8sz8zf57urafd8urhg7jdej6u892v3z088nvr

ETHEREUM (ETH) ADDRESS: 0x8C33CD44a083D605DBb65Ba4eC201f30Af88705c

ZCASH (ZEC) ADDRESS: t1dxu9KN1pSYNoMNxYMzCNhcHJhGZmwPW9n

MONERO (XMR) ADDRESS:
4A2p4k6vSGviUxoZvwQkAX8VBQE6tQncmZUS5mZ8YS9cZ2BQ4cc2CZXdMVg4vtFoxh3XrXQECWm95Gq2FpyRtvFz2yNZuYy

24) Finished!

Congratulations! You have FINISHED and you now have set up your Mac for Yubikey authentication only! Go ahead and try rebooting your mac and logging in with your Yubikey!