macOS Smart Card Login with Certificates configuration guide

Overview

This guide covers how to configure macOS to use smart card certificates for user login, including pre-boot FileVault unlock on Apple Silicon. It addresses both manual and automatic certificate pairing, deployment options via MDM (e.g., Jamf), and important FileVault considerations.

Requirements

For smart card pairing on macOS, the following conditions must be met:

• Encryption certificate required. macOS will not initiate the pairing process unless an encryption certificate is present on the card. This has been verified with Apple's deployment documentation: https://support.apple.com/en-ca/guide/deployment/depc705651a9/web

• PIV profile required. The card must use a PIV profile. macOS looks for the PIV Authentication slot (9A) and the Key Management slot (9D) for keys and certificates.

Pairing Mechanisms

There are two main ways macOS pairs a smart card to a user so it can be used for login, including pre-boot authentication with FileVault (available only on Apple Silicon).

1. Manual Pairing (Default Behavior)

By default, macOS detects when a smart card with certificates is inserted and prompts the user to pair it. If the user accepts:

• macOS maps the authentication certificate to the user for OS login.

• macOS encrypts the FileVault key using the Key Management public key.

Important: macOS does not verify that the certificates on the smart card actually match the user who is logged in. It only checks that valid certificates are present in the expected PIV slots.

2. Automatic Pairing

Instead of relying on a user to manually pair an inserted token, macOS can leverage a SmartCardLogin.plist file to match a certificate field (on the inserted token) with a directory attribute. Directory accounts can be either local accounts or directory-bound accounts (AD/LDAP).

When automatic pairing is configured correctly, the end-user experience requires no manual pairing steps — if a token with a certificate field matching the defined attribute is found, it can be used for PIN login (and FileVault unlock) automatically.

The examples below assume local accounts are being used.

Configuring Automatic Pairing

Step 1 — Define the Pairing Attribute

The first step is to decide which attribute on the directory account to match with a certificate field. Ideally, the attribute should be unique and not change over time.

For local accounts, no built-in attribute is typically suitable out of the box. Instead, you can create a new custom attribute (e.g., mapping) and match it against the certificate's SAN field — RFC 822 Name.

To create the attribute:

1. Open Directory Utility.

2. Create a new Native attribute with the name mapping.

3. Set the attribute value to the target user's RFC 822 Name (the certificate field you will be matching against).

Step 2 — Create the SmartCardLogin.plist

Next, tell macOS to map smart card certificates against this attribute. This is done by defining the field to match in a .plist file (see the SmartCardLogin man page in the References section below).

Example SmartCardLogin.plist that matches dsAttrTypeNative:mapping from the user account with RFC 822 Name on the certificate:

<?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>dsAttrTypeNative:mapping</string>
          <key>fields</key>
          <array>
                <string>RFC 822 Name</string>
          </array>
          <key>formatString</key>
          <string>$1</string>
     </dict>
     <key>NotEnforcedGroup</key>
     <string>EXEMPT_GROUP</string>
</dict>
</plist>

Tip: To find a field to match in an existing certificate, tools such as Smart Card Utility can be helpful for inspecting certificate fields.

Deployment Methods

Method 1 — Automated Deployment via Jamf

The SmartCardLogin.plist file can be deployed automatically to /private/etc as a bash script through Jamf.

1. Navigate to Settings → Computer Management → Scripts and create a new script with the following content:

#!/bin/bash
/bin/cat >"/private/etc/SmartcardLogin.plist" << 'attrib'
<?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>dsAttrTypeNative:mapping</string>
          <key>fields</key>
          <array>
                <string>RFC 822 Name</string>
          </array>
          <key>formatString</key>
          <string>$1</string>
     </dict>
     <key>NotEnforcedGroup</key>
     <string>EXEMPT_GROUP</string>
</dict>
</plist>
attrib

2. Bind the script to a configuration policy: navigate to Computer → Policies and create a new policy. Select Scripts and pick the script created above.

3. Select your deployment preferences — either install on next reboot, or interactively through the Self Service console.

Once deployed, SmartCardLogin.plist will be written to /private/etc on the Mac. An inserted token will be automatically paired (if the attribute is correctly matched) and PIN login will be available on next reboot.

Method 2 — Manual Deployment

To deploy the .plist file manually:

1. Verify the file using Terminal:

   plutil -lint SmartcardLogin.plist
   

2. Copy the file to /private/etc/:

   sudo cp SmartcardLogin.plist /private/etc
   

3. Update the permissions:

   sudo chown root:wheel /private/etc/SmartcardLogin.plistsudo chmod 644 /private/etc/SmartcardLogin.plist
   

After a token device is plugged in and the field is correctly matched with the defined user attribute, pairing will be automatic. Note that a device paired via automatic pairing will not show up when running sc_auth list, but can nonetheless be used for smart card login on next reboot.

FileVault Considerations

Automatic pairing carries important considerations when FileVault is enabled:

On Apple Silicon Macs, only the last-used token can unlock FileVault on the next boot. Each time the computer shuts down, macOS uses the last-used smart card to lock the disk with FileVault. This means:

• Only the last smart card used to log in will work to unlock the disk at next startup.

• Backup tokens cannot be used to unlock the disk — they are effectively locked out until used as the primary login card again.

• Requiring smart cards for login on Apple Silicon Macs also requires the use of smart cards to unlock FileVault.

Because of this behavior, this solution is primarily targeted at enterprise environments that have both a centrally managed CA for certificate lifecycle management and an endpoint management system that provides an account recovery process for locked-out users.

Emergency access: When enforcement is configured, the EXEMPT_GROUP value in the .plist file can reference a group of accounts exempted from smart card enforcement. These can be local accounts used to unlock FileVault in an emergency scenario.

Token Replacement Procedure

When replacing a token device (e.g., due to expiration, loss, or hardware refresh):

1. Enroll the new token with the appropriate certificates.

2. Remove the new token and re-insert it.

3. Run sc_auth identities to verify the new certificate is mapped. If automatic mapping is configured, you should see the new certificate listed.

4. Remove the old token from the system (unpair if needed).

5. Log off and log back on. You will be prompted for the keychain password on first login with the new token.

6. Reboot to verify FileVault authentication works with the new token.

Useful Commands

View card readers and certificates for connected devices:

system_profiler SPSmartCardsDataType

Unpair a device from a user (useful for retesting):

sudo sc_auth unpair -u <mac_username>

View identities and manually pair:

sc_auth identities

This shows unpaired identities with their public key hashes. To manually pair:

sudo sc_auth pair -v -u "username" -h <public_key_hash>

After manual pairing you will see a confirmation message. The user password will be required after the next smart card login to unlock the Login keychain.

References & Resources

• Apple Deployment Guide — Smart Card: https://support.apple.com/en-ca/guide/deployment/depc705651a9/web

• SmartCardLogin.plist Man Page: https://www.manpagez.com/man/7/SmartCardServices/

• Jamf Guide for macOS Smart Card Deployment: https://resources.jamf.com/documents/technical-papers/macos-smart-card-overview.pdf

• Automated Pairing Script (GitHub): https://github.com/gjbundy/macOS_Scripts/blob/main/smartcardAttributeMappingSetup.sh