Forked from synthetic-intelligence/More Helpful Commands
Last active
January 29, 2026 11:41
-
-
Save Pcw-Life/9e11432e307a7108d5a6619610f67f72 to your computer and use it in GitHub Desktop.
Smart Card Config MacOS
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # Apple smart card config | |
| ## Prerequisites | |
| macOS High Sierra or later | |
| an administrator account with a password configured | |
| a YubiKey with the PIV application. Make sure you go through the device setup. | |
| YubiKey Manager CLI installed | |
| ## Steps | |
| Generate certificates on your YubiKey to be paired with macOS. | |
| Generate key pairs for slot 9a and 9d, save public part to files. | |
| ykman piv keys generate 9a --algorithm ECCP256 /tmp/9a.pub | |
| ykman piv keys generate 9d --algorithm ECCP256 /tmp/9d.pub | |
| Generate self-signed certificates, anything can be used as subject. You may also set the expiration, default is one year.: | |
| ykman piv certificates generate 9a --subject miniC.a /tmp/9a.pub | |
| ykman piv certificates generate 9d --subject miniC.d /tmp/9d.pub | |
| ## Pair the the YubiKey with macOS | |
| The public key hash should now be listed as an unpaired identity. | |
| sc_auth identities | |
| Use the listed hash to pair the YubiKey with your user. | |
| sc_auth pair -h HASH -u USERNAME | |
| Verify that your user is paired: | |
| sc_auth list | |
| You may now use your YubiKey for login, but your password still works as well. | |
| ### Install a configuration profile | |
| To enforce the use of smart card a configuration profile needs to be installed. A sample profile can be found here. Save the sample profile as sample.mobileconfig | |
| Install the profile by double-clicking on the profile and following the OS prompts. | |
| The YubiKey is now required for all authentication tasks on the system. | |
| Additional options | |
| Note that even though this guide uses self-signed certificates, any pair of certifcates stored in slot 9a and 9d may be used for pairing. To also verify that the certificates used are trusted, configure the checkCertificateTrust option in the profile. | |
| The tokenRemovalAction may be added to the profile to automatically start the screensaver when the YubiKey is removed. | |
| --- | |
| # Admin's when --Enable smart card-only login | |
| Make sure that you carefully follow these steps to ensure that users will be able to log in to the computer. | |
| Pair a smart card to an admin user account or configure Attribute Matching. | |
| If you’ve enabled strict certificate checks, install any root certificates or intermediates that are required. | |
| Confirm that you can log in to an administrator account using a smart card. | |
| Install a smart-card configuration profile that includes "<key>enforceSmartCard</key><true/>," as shown in the smart card-only configuration profile below. | |
| Confirm that you can still log in using a smart card. | |
| For more information about smart card payload settings, see the Apple Configuration Profile Reference. | |
| For more information about using smart card services, see the macOS Deployment Guide or open Terminal and enter man SmartCardServices. | |
| ### Disable smart card-only authentication | |
| If you manually manage the profiles that are installed on the computer, you can remove the smart card-only profile in two ways. You can use the Profiles pane of System Preferences, or you can use the /usr/bin/profiles command-line tool. For more information, open Terminal and enter man profiles. | |
| If your client computers are enrolled in Mobile Device Management (MDM), you can restore password-based authentication. To do this, remove the smart card configuration profile that enables the smart card-only restriction from the client computers. | |
| To prevent users from being locked out of their account, remove the enforceSmartCard profile before you unpair a smart card or disable attribute matching. If a user is locked out of their account, remove the configuration profile to fix the issue. | |
| If you apply the smart card-only policy before you enable smart card-only authentication, a user can get locked out of their computer. To fix this issue, remove the smart card-only policy: | |
| Turn on your Mac, then immediately press and hold Command-R to start up from macOS Recovery. Release the keys when you see the Apple logo, a spinning globe, or a prompt for a firmware password. | |
| Select Disk Utility from the Utilities window, then click Continue. | |
| From the Disk Utility sidebar, select the volume that you're using, then choose File > Mount from the menu bar. (If the volume is already mounted, this option is dimmed.) Then enter your administrator password when prompted. | |
| Quit Disk Utility. | |
| Choose Terminal from the Utilities menu in the menu bar. | |
| Delete the Configuration Profile Repository. To do this, open Terminal and enter the following commands. | |
| In these commands, replace <volumename> with the name of the macOS volume where the profile settings were installed. | |
| rm /Volumes/<volumename>/var/db/ConfigurationProfiles/MDM_ComputerPrefs.plist | |
| rm /Volumes/<volumename>/var/db/ConfigurationProfiles/.profilesAreInstalled | |
| rm /Volumes/<volumename>/var/db/ConfigurationProfiles/Settings/.profilesAreInstalled | |
| rm /Volumes/<volumename>/var/db/ConfigurationProfiles/Store/ConfigProfiles.binary | |
| rm /Volumes/<volumename>/var/db/ConfigurationProfiles/Setup/.profileSetupDone | |
| When done, choose Apple () menu > Restart. | |
| Reinstall all the configuration profiles that existed before you enabled smart card-only authentication. | |
| #### Configure Secure Shell Daemon (SSHD) to support smart card-only authentication | |
| Users can use their smart card to authenticate over SSH to the local computer or to remote computers that are correctly configured. Follow these steps to configure SSHD on a computer so that it supports smart card authentication. | |
| Update the /etc/ssh/sshd_config file: | |
| Use the following command to back up the sshd_config file: | |
| sudo cp /etc/ssh/sshd_config /etc/ssh/sshd_config_backup_`date "+%Y-%m-%d_%H:%M"` | |
| In the sshd_config file, change | |
| "#ChallengeResponseAuthentication yes" to "ChallengeResponseAuthentication no" | |
| and change | |
| "#PasswordAuthentication yes" to "#PasswordAuthentication no." | |
| Then, use the following commands to restart SSHD: | |
| sudo launchctl stop com.openssh.sshd | |
| sudo launchctl start com.openssh.sshd | |
| ##### authenticate SSH sessions using a smart card | |
| Use the following command to export the public key from their smart card: | |
| ssh-keygen -D /usr/lib/ssh-keychain.dylib | |
| Add the public key from the previous step to the ~/.ssh/authorized_keys file on the target computer. | |
| Use the following command to back up the ssh_config file: | |
| sudo cp /etc/ssh/ssh_config /etc/ssh/ssh_config_backup_`date "+%Y-%m-%d_%H:%M"` | |
| In the/etc/ssh/ssh_config file, add the line "PKCS11Provider=/usr/lib/ssh-keychain.dylib." | |
| ##### add the private key to their ssh-agent: | |
| ssh-add -s /usr/lib/ssh-keychain.dylib | |
| #### Enable smart card-only for the SUDO command | |
| Use the following command to back up the /etc/pam.d/sudo file: | |
| sudo cp /etc/pam.d/sudo /etc/pam.d/sudo_backup_`date "+%Y-%m-%d_%H:%M"` | |
| Then, replace all of the contents of the /etc/pam.d/sudo file with the following text: | |
| ``` bash | |
| # 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 | |
| ``` | |
| #### Enable smart card-only for the LOGIN command | |
| Use the following command to back up the /etc/pam.d/login file: | |
| sudo cp /etc/pam.d/login /etc/pam.d/login_backup_`date "+%Y-%m-%d_%H:%M"` | |
| Then, replace all of the contents of the/etc/pam.d/login file with 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 | |
| #### Enable smart card-only for the SU command | |
| Use the following command to back up the /etc/pam.d/su file: | |
| sudo cp /etc/pam.d/su /etc/pam.d/su_backup_`date "+%Y-%m-%d_%H:%M"` | |
| Then, replace all of the contents of the/etc/pam.d/su file with 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 | |
| #### smart card-only example profile | |
| ``` plist | |
| <?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>PayloadType</key> | |
| <string>Configuration</string> | |
| <key>PayloadScope</key> | |
| <string>system</string> | |
| <key>PayloadUUID</key> | |
| <string>7D34CC86-C707-44D2-9A9F-C5F6E347BD77</string> | |
| <key>PayloadVersion</key> | |
| <integer>1</integer> | |
| </dict> | |
| </plist> | |
| ``` | |
| --- | |
| # Local account pairing | |
| The steps below describe the local account pairing process: | |
| +Insert a PIV smart card or hard token that includes authentication and encryption identities | |
| +Select “Pair” at the notification dialog | |
| +Provide administrator account credentials (user name/password) | |
| +Provide the 4–6 digit Personal Identification Number (PIN) for the inserted smart card | |
| +Log out and use the smart card and PIN to log back in | |
| Local account pairing can also be accomplished with the command-line and an existing account. See Advanced smart card options for details regarding this method of pairing. | |
| ## Attribute mapping with Active Directory | |
| Smart cards can be authenticated against Active Directory using attribute mapping. This method involves having an Active Directory-bound system and setting appropriate information in the file /private/etc/SmartcardLogin.plist. This file must have world readable permissions in order to function properly. | |
| Before the user can take advantage of this feature, macOS must be configured with the appropriate attribute mapping and the local pairing user interface must be disabled. To disable the local pairing dialog, open the Terminal app, then type | |
| ``` | |
| sudo defaults write /Library/Preferences/com.apple.security.smartcard UserPairing -bool NO | |
| ``` | |
| and enter your local administrator password when prompted. | |
| As soon as macOS is configured, a user simply inserts a smart card or token to create a new user account. They are prompted to enter their pin and create a unique keychain password that is wrapped by the encryption key in the smart card. Accounts can be configured for network user accounts or mobile user accounts. | |
| Note: The presence of the /private/etc/SmartcardLogin.plist file takes precedence over paired local accounts. | |
| Network user account with attribute mapping example | |
| The following is an example SmartcardLogin.plist where mapping correlates the NT Principal Name on the PIV Authentication certificate to the userPrincipalName attribute in Active Directory: | |
| ``` | |
| <?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>AttributeMapping</key> | |
| <dict> | |
| <key>fields</key> | |
| <array> | |
| <string>NT Principal Name</string> | |
| </array> | |
| <key>formatString</key> | |
| <string>$1</string> | |
| <key>dsAttributeString</key> | |
| <string>dsAttrTypeNative:userPrincipalName</string> | |
| </dict> | |
| </dict> | |
| </plist> | |
| ``` | |
| ### Mobile user account with attribute mapping example | |
| When binding to Active Directory, selecting the “Create mobile account at login” preference allows the creation of mobile accounts for offline login. This mobile user feature is supported with the Kerberos attribute mapping, and it should be configured in the Smartcardlogin.plist. This configuration is also useful in environments where a Mac may not always be able to reach directory server. | |
| Note: Initial account setup requires machine binding and access to the directory server. | |
| The following example SmartcardLogin.plist file matches the Subject Alternative Name type, NT Principal Name, in the identity on the smart card against the Directory Server’s altSecurityIdentities field (Kerberos), allowing for offline login and authentication: | |
| ``` | |
| <?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>AttributeMapping</key> | |
| <dict> | |
| <key>fields</key> | |
| <array> | |
| <string>NT Principal Name</string> | |
| </array> | |
| <key>formatString</key> | |
| <string>Kerberos:$1</string> | |
| <key>dsAttributeString</key> | |
| <string>dsAttrTypeStandard:AltSecurityIdentities</string> | |
| </dict> | |
| </dict> | |
| </plist> | |
| ``` | |
| ### Enabling screen saver on token removal | |
| The screen saver can be configured to start automatically when a user removes their token. This option appears only once a smart card has been paired. | |
| There are two main ways to accomplish this: | |
| Using the Security and Privacy preference pane on the Mac, using the Advanced button and selecting “Turn on screen saver when login token is removed.” Make sure the screensaver settings are configured and select “Require a password immediately after sleep or screen saver begins.” | |
| With a mobile device management (MDM) solution by using the tokenRemovalAction key. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # MacOS smartcard | |
| List tokens available in the system | |
| pluginkit -m -p com.apple.ctk-tokens | |
| ex: com.apple.CryptoTokenKit.setoken(1.0) | |
| com.apple.CryptoTokenKit.pivtoken(1.0) | |
| Enable, disable or list disabled smart card tokens | |
| sudo security smartcards token [-l] [-e token] [-d token] | |
| Unpair the smart card | |
| sudo sc_auth unpair -u jappleeed | |
| Display available smart cards | |
| sudo security list-smartcards | |
| Export items from a smart card | |
| sudo security export-smartcard | |
| Smart card logging | |
| sudo defaults write /Library/Preferences/com.apple.security.smartcard Logging -bool true | |
| Disable built-in PIV tokens | |
| sudo defaults write /Library/Preferences/com.apple.security.smartcard DisabledTokens -array com.apple.CryptoTokenKit.pivtoken | |
| ## Smart card–only authentication using machine based enforcement | |
| macOS 10.13.2 or later support smart card–only authentication for the mandatory use of a smart card, which disables all password-based authentication. This configuration is enforced across all of macOS and is often called Machine Based Enforcement. To leverage this feature, mandatory smart card enforcement must be established using a mobile device management (MDM) solution or by using the following command: | |
| ``` | |
| sudo defaults write /Library/Preferences/com.apple.security.smartcard enforceSmartCard -bool true | |
| ``` | |
| ## Managing smart card payloads | |
| Suppress prompt to pair on token insertion | |
| sudo defaults write /Library/Preferences/com.apple.security.smartcard UserPairing -bool false | |
| Limit user account pairing to a single smart card | |
| sudo defaults write /Library/Preferences/com.apple.security.smartcard oneCardPerUser -bool true | |
| Disable smart card user for login and authorization | |
| sudo defaults write /Library/Preferences/com.apple.security.smartcard allowSmartCard -bool false | |
| Note: When disabling allowSmartCard, smart card certificates identities can still be used for other operations such as signing and encryption and in supported third-party apps. | |
| Manage smart card certificate trust behavior | |
| sudo defaults write /Library/Preferences/com.apple.security.smartcard checkCertificateTrust -int <value> | |
| The value can be one of the following: | |
| 0: Smart card certificate trust isn’t required. | |
| 1: Smart card certificate and chain must be trusted. | |
| 2: Certificate and chain must be trusted and not receive a revoked status. | |
| 3: Certificate and chain must be trusted and revocation status is returned valid. | |
| Certificate pinning | |
| It’s possible to specify the Certificate Issuing Authorities used for the trust evaluation of smart card certificates. This trust works in conjunction with Certificate Trust settings (1, 2, or 3 required) and is also referred to as Certificate Pinning. Place SHA-256 fingerprints of Certificate Authorities (as string values, comma delimited, and without spaces) in an array named TrustedAuthorities. Use the example /private/etc/SmartcardLogin.plist file below as guidance. When Certificate Pinning is used, only SmartCard certificates issued by Certificate Authorities in this list are evaluated as trusted. Please note that TrustedAuthorities are ignored when the checkCertificateTrust setting is set to 0 (off). Verify ownership is root and permissions are set to world readable after editing. | |
| <?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>AttributeMapping</key> | |
| <dict> | |
| <key>dsAttributeString</key> | |
| <string>dsAttrTypeStandard:AltSecurityIdentities</string> | |
| <key>fields</key> | |
| <array> | |
| <string>NT Principal Name</string> | |
| </array> | |
| <key>formatString</key> | |
| <string>Kerberos:$1</string> | |
| </dict> | |
| <key>TrustedAuthorities</key> | |
| <array> | |
| <string>SHA256_HASH_OF_CERTDOMAIN_1,SHA256_HASH_OF_CERTDOMAIN_2</string> | |
| </array> | |
| </dict> | |
| </plist> | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| You can configure Smart Card settings for Mac computers enrolled in a mobile device management (MDM) solution. Use the Smart Card payload to manage specific settings for Smart Cards. User overrides aren’t permitted. | |
| OS and channel | |
| Supported enrollment types | |
| Interaction | |
| Duplicates | |
| macOS device | |
| Device | |
| Automated Device | |
| Exclusive | |
| Single | |
| Setting | |
| Description | |
| Required | |
| Smart Card use | |
| Specify whether users can use a smart card for logins, authorizations, and screensaver unlocking. Smart cards can still be used for signing mail messages, web access, and other services. The Mac must be restarted for this change to take effect. | |
| No | |
| User pairing | |
| Specify whether users can see any new pairing dialogs. Existing pairings will still work. | |
| No | |
| Restrict one smart card per user | |
| Specify whether users can pair with only one smart card. Existing pairings for that user will still work. | |
| No | |
| Enable screen saver | |
| When a smart card is removed, the screensaver is automatically enabled. | |
| No | |
| Check the certificate trust | |
| Configure one of these options: | |
| Certificate trust check is turned off. | |
| Certificate trust check is turned on. | |
| Certificate trust check is turned on and revocation check is set to the soft level (unreachable OCSP/CRL means success). | |
| Certificate trust check is turned on and revocation check is set to the hard level (verified positive response is needed to succeed). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| SmartCard | |
| The payload for configuring a smart card. | |
| Availability | |
| macOS 10.12.4+ | |
| Framework | |
| Device Management | |
| On This Page | |
| Properties | |
| Discussion | |
| See Also | |
| Properties | |
| allowSmartCard | |
| boolean | |
| If false, disables the SmartCard for logins, authorizations, and screen saver unlocking. It is still allowed for other functions, such as signing emails and accessing the web. A restart is required for a setting change to take effect. | |
| Default: true | |
| checkCertificateTrust | |
| integer | |
| Valid values are 0 to 3: | |
| 0: Turns off certificate trust check. | |
| 1: Turns on certificate trust check. A standard validity check is performed but doesn't include additional revocation checks. | |
| 2: Turns on certificate trust check. A soft revocation check is also performed. Until the certificate is explicitly rejected by CRL/OCSP, it's considered valid. This setting means that unavailable or unreachable CRL/OCSP allow this check to succeed. | |
| 3: Turns on certificate trust check. A hard revocation check is also performed. Unless CRL/OCSP explicitly says "This certificate is OK," it's considered invalid. This option is the most secure. | |
| Default: 0 | |
| Possible values: 0, 1, 2, 3 | |
| enforceSmartCard | |
| boolean | |
| If true, a user can only log in or authenticate with a SmartCard. Available in macOS 10.13.2 and later. | |
| Default: false | |
| oneCardPerUser | |
| boolean | |
| If true, a user can pair with only one SmartCard, although existing pairings are allowed if already set up. | |
| Default: false | |
| tokenRemovalAction | |
| integer | |
| If 1, enables the screen saver when the SmartCard is removed. Available in macOS 10.13.4 and later. | |
| Default: 0 | |
| Possible values: 0, 1 | |
| UserPairing | |
| boolean | |
| If false, users don't get the pairing dialog, although existing pairings still work. | |
| Default: true | |
| Discussion | |
| Specify com.apple.security.smartcard as the payload type. | |
| Profile Availability | |
| Device Channel | |
| macOS | |
| User Channel | |
| - | |
| Allow Manual Install | |
| macOS | |
| Requires Supervision | |
| - | |
| Requires User Approved MDM | |
| - | |
| Allowed in User Enrollment | |
| - | |
| Allow Multiple Payloads | |
| - | |
| See Also | |
| Security | |
| object Passcode | |
| The payload for configuring a passcode policy. | |
| object SecurityPreferences | |
| The payload for configuring security preferences. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # Configuring macOS for smart card–only authentication | |
| macOS supports smart card–only authentication for the mandatory use of a smart card, which disables all password-based authentication. This policy is established across all of macOS, and can be changed on a per-user basis using an exemption group, in the event that a user doesn’t have a working smart card available. | |
| ## Smart card–only authentication using machine based enforcement | |
| macOS 10.13.2 or later support smart card–only authentication for the mandatory use of a smart card, which disables all password-based authentication. This configuration is enforced across all of macOS and is often called Machine Based Enforcement. To leverage this feature, mandatory smart card enforcement must be established using a mobile device management (MDM) solution or by using the following command: | |
| ``` | |
| sudo defaults write /Library/Preferences/com.apple.security.smartcard enforceSmartCard -bool true | |
| ``` | |
| ## Smart card–only authentication using per-user enforcement | |
| Per-user enforcement is accomplished by specifying a user group that will be exempted from smart card login. NotEnforcedGroup contains a string value that defines the name of an local or Directory group that won’t be included in mandatory smart card enforcement. This is sometimes referred to as User Based Enforcement and provides per-user granularity to smart card services. To leverage this feature, machine based enforcement must be established using a mobile device management (MDM) solution or by using the following command: | |
| ``` | |
| sudo defaults write /Library/Preferences/com.apple.security.smartcard enforceSmartCard -bool true | |
| ``` | |
| In addition, the system must be configured to allow users who aren’t paired with a smart card to log in with password: | |
| ``` | |
| sudo defaults write /Library/Preferences/com.apple.security.smartcard allowUnmappedUsers -int 1 | |
| ``` | |
| Use the example /private/etc/SmartcardLogin.plist file below as guidance. The EXEMPT_GROUP should be the name of the group used for exemptions. Any user added to this group is exempt from smart card login, as long as they are a specified member of the group or the group itself is specified for exemption. Verify ownership is root and permissions are set to world readable after editing. | |
| ``` | |
| <?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>AttributeMapping</key> | |
| <dict> | |
| <key>dsAttributeString</key> | |
| <string>dsAttrTypeStandard:AltSecurityIdentities</string> | |
| <key>fields</key> | |
| <array> | |
| <string>NT Principal Name</string> | |
| </array> | |
| <key>formatString</key> | |
| <string>Kerberos:$1</string> | |
| </dict> | |
| <key>NotEnforcedGroup</key> | |
| <string>EXEMPT_GROUP</string> | |
| </dict> | |
| </plist> | |
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # **Requirements** | |
| macOS High Sierra (10.13) or newer | |
| Admin account | |
| YubiKey Manager | |
| Personalizing the YubiKey PIV application | |
| ## Note: The default settings on the YubiKey PIV application are as follows: | |
| PIN: 123456 (6-8 characters allowed, macOS requires numeric-only) | |
| PUK: 12345678 (6-8 characters allowed) | |
| Management Key: 010203040506070801020304050607080102030405060708 | |
| If you have forgotten your PIN and need to reset the PIV application to default, refer to this article. | |
| # **Initial Setup** | |
| ## Setting a new PIN | |
| In YubiKey Manager, click Applications > PIV | |
| Click Configure PINs | |
| Click Change PIN | |
| Current PIN: Assuming the default PIN has not been changed, enter the default PIN of 123456 or simply click Use default. | |
| New PIN: Use a 6-8 digit number for your new PIN and note it for future reference. Do not use letters or other characters in your PIN when configuring for macOS login. macOS does not accept non-numeric characters. | |
| Confirm new PIN: Confirm the PIN entered in the previous field. | |
| Click Change PIN | |
| ## Setting a new PUK | |
| On the Configure PINs screen, click Change PUK | |
| Current PUK: Assuming the default PUK has not been changed, enter the default PUK of 12345678 or simply click Use default. | |
| New PUK: Use a 6-8 digit number for your new PUK and note it for future reference. | |
| Confirm new PUK: Confirm the PUK entered in the previous field. | |
| Click Change PUK | |
| ## Setting a new Management Key | |
| On the Configure PINs screen, click Change Management Key | |
| Current Management Key: Assuming the default Management Key has not been changed, enter the default Management Key of 010203040506070801020304050607080102030405060708 or simply click Use default. | |
| New Management Key: Enter a new 48 character Management Key, or choose Generate to create a randomized Management Key. | |
| Protect with PIN: Choose this option if you prefer the Management Key to be encrypted using the PIN. When prompted for the Management Key in the future, the PIN can be provided in place of entering a 48 character Management Key. Considering the Management Key must be entered when configuring your YubiKey for macOS account login, this option is highly recommended. | |
| Click Finish. If you chose Protect with PIN, enter your PIN in the PIN field and click OK. | |
| # **Configuring your YubiKey for macOS account login** | |
| In YubiKey Manager, click Applications > PIV | |
| Click Setup for macOS | |
| Click Setup for macOS. If you chose Protect with PIN when setting the Management Key, enter your PIN in the prompt. If you set a custom Management Key and did not protect with PIN, enter the Management Key in the prompt. | |
| Click OK. | |
| Remove your YubiKey and plug it into the USB port | |
| In the SmartCard Pairing macOS prompt, click Pair. Note: If this prompt doesn't appear, see the Troubleshooting and Additional Topics section below. | |
| In the password prompt, enter the password for the user account listed in the User Name field and click Pair | |
| In the SmartCard Pairing prompt, enter the PIN for your YubiKey (refer to the Setting a new PIN section above) and click OK | |
| In the "login" keychain prompt, enter your keychain password (typically the password for the logged in user account) and click OK | |
| To test the configuration, lock your Mac (Ctrl+Command+Q), and make sure the password field reads PIN when your YubiKey is inserted. Try unlocking your session with your YubiKey by entering your PIN. | |
| # **How to Unpair Your YubiKey and PIV Login from macOS** | |
| **Warning:** Unpairing your YubiKey from macOS does not disable the smart requirement, so if you enabled this requirement, you should first disable it before unpairing your YubiKeys, to ensure you do not get locked out. The profile that enables the smart card requirement can be removed via System Preferences > Profiles (note that Profiles will not appear unless you have a profile installed). For more information, see this Apple article under the section Disable smart card-only authentication. If you did not enable the smart card requirement, disregard this warning. | |
| To unpair your PIV login from macOS, follow the procedures below. You can choose to delete all certificates that were installed on your YubiKey when you paired the device with macOS, or only the certificates that were added for logging in to macOS. Also included are reset instructions so that macOS will no longer prompt you to pair your YubiKey or a smart card whenever the device(s) are detected. | |
| # **Removing Certificates from the YubiKey** | |
| ## To delete all of the certificates on the YubiKey | |
| Use this procedure if you want to reset the PIV application, which will remove all certificates and reset the PIN, PUK, and Management Key to default values. If you want to keep your certificates, skip to the next procedure. | |
| In YubiKey Manager, click Applications > PIV | |
| Click Reset PIV | |
| Click Yes to confirm | |
| ## To delete only the certificates created after completing the macOS login instructions | |
| Use this procedure if you want to remove only the certificates created for macOS login. | |
| In YubiKey Manager, click Applications > PIV | |
| Click Configure Certificates | |
| On the Authentication tab, click Delete | |
| Click Yes to confirm certificate deletion. If prompted for the PIN, enter the PIN and click OK. If prompted for the Management Key, provide the Management Key and click OK. | |
| On the Key Management tab, click Delete | |
| Click Yes to confirm certificate deletion. If prompted for the PIN, enter the PIN and click OK. If prompted for the Management Key, provide the Management Key and click OK. | |
| Removing the Smart Card Pairing from macOS | |
| ## To remove a single YubiKey or smart card from macOS login | |
| Open Terminal. | |
| Run: '''sc_auth list [username]''' | |
| ex: '''sc_auth list john''' | |
| Highlight and copy (Command+C) the hash listed for your user. | |
| If multiple YubiKey smart cards are paired with your account and you aren't sure which hash is which, you can check the hash of a particular YubiKey by running sc_auth identities with the key in question plugged in. | |
| Run: '''sc_auth unpair -h [hash]''' | |
| ## To remove all paired YubiKeys and smart cards for a single user | |
| Open Terminal. | |
| Run: '''sc_auth unpair -u [username]''' | |
| ex: '''sc_auth unpair john''' | |
| ## To remove all paired YubiKeys and smart cards for the currently logged in user | |
| Open Terminal. | |
| Run: '''sc_auth unpair -u $(whoami)''' | |
| # To turn off the pairing user interface in macOS | |
| Use this option if you want to insert your YubiKey that contain certificates, and you do not want macOS to prompt you to pair it to your account. | |
| Open Terminal | |
| Run: '''sc_auth pairing_ui -s disable''' | |
| Note: The pairing UI can be re-enabled with the command '''sc_auth pairing_ui -s enable''' | |
| #**Troubleshooting and Additional Topics** | |
| ##SmartCard pairing prompt does not appear | |
| Sometimes, the pairing prompt referenced in step 6 under Configuring your YubiKey for macOS account login will not appear. If this happens, follow the steps below in order. | |
| The Pairing UI in macOS may be disabled. | |
| To try enabling it, run the following command in Terminal: '''sc_auth pairing_ui -s enable''' | |
| To check the status of the Pairing UI, '''run sc_auth pairing_ui -s status''' | |
| Once the UI has been enabled, reinsert your YubiKey. | |
| If that doesn't help, try reinserting your YubiKey a few additional times and see if that causes the pairing prompt to appear. | |
| If the pairing prompt still does not appear, with your YubiKey inserted | |
| Try running the following command in Terminal: '''sc_auth pairing_ui -f''' | |
| If the above command does nothing, still with the YubiKey inserted | |
| Try running '''sc_auth identities''' (in Terminal) | |
| This will check whether you Mac detects any unpaired smart cards. | |
| If it does, the output of the command should look something like the following. | |
| '''SmartCard: com.apple.pivtoken:2D2248DE2F337A1F99C34BE4DCF44B61 Unpaired identities: A205691C39CBE2FF81F72070C8FEE6B27DF4E527 Certificate For PIV Authentication (Yubico PIV Authentication)''' | |
| If you see this, you can manually initiate pairing of your smart card | |
| Using the following (Terminal) command, replacing <hash> with the long string from the sc_auth identities output (A205691C39CBE2FF81F72070C8FEE6B27DF4E527 in the above example): | |
| '''sudo sc_auth pair -h <hash> -u $(whoami)''' | |
| If sc_auth identities doesn't yield any output on the other hand, consider resetting your YubiKey's PIV smart card application and following through the steps in this article again from the beginning. | |
| #**Requiring your YubiKey Smart Card** | |
| **Apple silicon users:** Because of some differences in the way smart card authentication works on Macs with Apple silicon CPUs (versus those with Intel), consumers and individuals should understand that requiring a smart card for MacOS login can result in a system lockout if performed incorrectly. Additionally, requiring smart cards for login on Apple silicon Macs also requires the use of smart cards to unlock FileVault. Each time the computer is shut down, macOS uses the last used smart card to lock the disk with FileVault. In this scenario, only the last smart card used to login will work to unlock the disk upon next startup, effectively making any smart cards set up as backups incapable of unlocking the disk. As such, this solution is targeted primarily towards corporate enterprises that have implemented both a centrally managed CA for certificate lifecycle management and an endpoint management system that provides an account recovery process for locked-out users. | |
| **Warning:** Requiring a smart card for authentication can result in a system lockout if performed incorrectly. Yubico is not responsible for any system lockout that occurs as a result of requiring smart cards on your Mac. If you have locked yourself out of your Mac by requiring a smart card and the resources on this page have not helped to get you back in, you will need to contact Apple for further assistance. Before making any configuration changes, please: | |
| Read the two Apple articles linked below, especially the section Disable smart card-only authentication in the second link. | |
| [Configure macOS Smart Card-only Authentication](https://support.apple.com/guide/deployment/configure-macos-smart-cardonly-authentication-depfce8de48b/1/web/1.0) | |
| [Apple Support Article HT208372](https://support.apple.com/en-us/HT208372) | |
| Register at least two smart cards and verify that both are working for authentication (to log in to/unlock your account), and refer to the special considerations described when using Apple silicon Macs under the FileVault Configuration > Apple silicon-based Macs section in this article. | |
| By default, a paired smart card can be used as an alternative way to log in (instead of a password), but it is not required. This article from our Developers site covers configuring your Mac for smart card-only authentication. | |
| #**FileVault Configuration** | |
| FileVault is macOS' built-in full-disk encryption solution. | |
| ##Intel-based Macs | |
| On Intel-based Macs, FileVault does not support smart cards for pre-boot authentication, | |
| meaning you will still need to use your password to unlock your FileVault-encrypted disk. | |
| This is the first password prompt you receive after starting your Mac from a powered-off state. | |
| By default, when a user enters their password to decrypt the FileVault disk at boot, | |
| this password will be passed through and a smart card will not be used for login, | |
| even if you configure it to be required. | |
| To change this so that the user will not automatically be logged in and will be shown the login screen | |
| (a second authentication prompt), run the command below in Terminal. | |
| '''sudo defaults write /Library/Preferences/com.apple.loginwindow DisableFDEAutoLogin -bool YES''' | |
| ##**Apple silicon-based Macs** | |
| On Apple silicon-based Macs, smart cards are now supported for pre-boot FileVault authentication. | |
| Since a Mac's encrypted data has yet to be unlocked during this authentication, | |
| only the smart card that was used most recently to authenticate will work. | |
| This effectively makes any smart cards set up as backups incapable of unlocking the disk. | |
| As such, this solution is targeted primarily towards corporate enterprises that have implemented | |
| both a centrally managed CA for certificate lifecycle management and an endpoint management system | |
| that provides an account recovery process for locked-out users. | |
| Consumers and individuals should understand that requiring a smart card for MacOS login | |
| **can result in a system lockout if performed incorrectly.** | |
| If you are not sure whether your Mac has an Intel or Apple silicon processor, please [see this article](https://support.apple.com/en-us/116943). | |
| #**Multiple YubiKeys, Macs, etc.** | |
| ##Using the same YubiKey smart card on multiple Macs for logging in: | |
| Once you have set up your YubiKey on the first Mac, on each other Mac, | |
| simply plug in your YubiKey and follow steps 6-9 in the section Pairing your YubiKey with macOS. | |
| ##Using the same YubiKey smart card for multiple accounts on a single Mac: | |
| On a single Mac, macOS only allows you to associate a given YubiKey with one user account. | |
| ##Using multiple YubiKeys with the same user account on a single Mac: | |
| For any additional YubiKeys beyond the first, simply follow through the steps in this guide again. | |
| Once this has been done for all YubiKeys, any of them should be able to log you in to/unlock your Mac | |
| when you provide the PIN. Note that the PIN may be different for each YubiKey, depending on how you set them up. | |
| #**Lost or stolen YubiKey** | |
| If you followed these instructions to require a paired smart card for login, | |
| follow the steps in the same article under Disable smart card-only authentication. | |
| If you have not set up your Mac to require a smart card, then the YubiKey is not required, | |
| so you should still be able to log in to your Mac without a YubiKey by entering your normal account password | |
| (following the steps in this guide will not change your normal account password). | |
| **To unpair the lost or stolen YubiKey, follow the section above titled How to Unpair Your YubiKey and PIV Login from macOS.** | |
| #**Note:** | |
| The YubiKey Bio Multi-protocol Edition supports using fingerprint | |
| verification in lieu of the PIN when performing cryptographic operations. | |
| In the case of PIV smart card however, to provide users with this fingerprint | |
| option, client software or middleware is required. Yubico has implemented | |
| support for this in the Yubico Minidriver from version 4.6.1. If users | |
| attempt to use PIV smart card on the YubiKey Bio Multi-protocol Edition | |
| without supporting middleware, they will encounter limitations. | |
| In scenarios where supporting middleware is not available or not utilized, | |
| users can still access the PIV application on the YubiKey Bio Multi-protocol | |
| Edition. However, they will not have the option to utilize fingerprint | |
| authentication for cryptographic operations. Instead, they will need to rely | |
| on traditional methods such as entering a PIN. | |
| While users can still access the PIV application and perform cryptographic | |
| operations, they miss out on the convenience and potentially enhanced | |
| security offered by biometric authentication. Without the fingerprint | |
| option, users may need to rely on the PIN. | |
| #**Acknowledgments:** | |
| Source: [Using your YubiKey as a smart card in macOS](https://support.yubico.com/hc/en-us/articles/360016649059-Using-your-YubiKey-as-a-smart-card-in-macOS) | |
| Credit: Clay Degruchy |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment