--- title: "macOS Smart Card Login with Certificates configuration guide" slug: "macos-smart-card-login-with-certificates-configuration-guide" updated: 2026-03-13T16:24:58Z published: 2026-03-13T16:24:58Z canonical: "docs.axiad.com/macos-smart-card-login-with-certificates-configuration-guide" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.axiad.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](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     AttributeMapping              dsAttributeString          dsAttrTypeNative:mapping          fields                          RFC 822 Name                    formatString          $1         NotEnforcedGroup     EXEMPT_GROUP ``` **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: ```bash #!/bin/bash /bin/cat >"/private/etc/SmartcardLogin.plist" << 'attrib'     AttributeMapping              dsAttributeString          dsAttrTypeNative:mapping          fields                          RFC 822 Name                    formatString          $1         NotEnforcedGroup     EXEMPT_GROUP attrib ``` 1. Bind the script to a configuration policy: navigate to **Computer → Policies** and create a new policy. Select **Scripts** and pick the script created above. 2. 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: ```plaintext plutil -lint SmartcardLogin.plist ``` 2. Copy the file to `/private/etc/`: ```plaintext sudo cp SmartcardLogin.plist /private/etc ``` 3. Update the permissions: ```plaintext 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:** ```plaintext system_profiler SPSmartCardsDataType ``` **Unpair a device from a user (useful for retesting):** ```plaintext sudo sc_auth unpair -u ``` **View identities and manually pair:** ```plaintext sc_auth identities ``` This shows unpaired identities with their public key hashes. To manually pair: ```plaintext sudo sc_auth pair -v -u "username" -h ``` 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](https://support.apple.com/en-ca/guide/deployment/depc705651a9/web) - **SmartCardLogin.plist Man Page:** [https://www.manpagez.com/man/7/SmartCardServices/](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](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](https://github.com/gjbundy/macOS_Scripts/blob/main/smartcardAttributeMappingSetup.sh)