How to Use the sc_auth Command in macOS Terminal to Manage SmartCard and Hardware Key Pairing

In high-security enterprise environments and government organizations, authenticating to macOS endpoints using physical hardware tokens—such as PIV (Personal Identity Verification) cards, CAC (Common Access Cards), or YubiKeys configured with cryptographic certificates—is mandatory. SmartCard authentication replaces standard passwords with asymmetric cryptographic challenges. While macOS automatically detects compatible card readers, administrators frequently need to pair specific hardware certificates to local user accounts, audit paired identities, or unpair lost tokens.

In macOS Terminal, Apple provides the native sc_auth (SmartCard Authentication) utility to manage hardware token pairing directly from the command line.

How SmartCard Pairing Works in macOS

When you insert a cryptographic token into a Mac, the macOS CryptoTokenKit subsystem reads the X.509 certificate stored in the card’s PIV authentication slot (slot 9A). To allow that token to unlock a specific macOS user account:

• Account Association: The certificate’s public key hash and identity mapping must be linked to the target user account within the macOS Open Directory database (dscl).
• Kerberos / FileVault Unlocking: Once paired, inserting the card prompts for the card’s PIN instead of a user password, granting access to FileVault and the login keychain.
• Multi-Card Support: A single user account can have multiple physical SmartCards paired simultaneously (such as a primary card and a backup hardware token).

Checking Connected SmartCards and Certificates

Before pairing, insert your SmartCard or YubiKey into a USB port. To verify that macOS detects the card and can read its onboard certificates:

sc_auth identities

The terminal will output the detected cryptographic identities along with their hashes:

Available cryptographic identities:
1. 8F4D3C2E1B... "John Doe (PIV Authentication)"
   Algorithm: RSA 2048
   Card Serial: 10492819

Copy the alphanumeric identity hash string corresponding to your PIV authentication certificate.

Command Syntax and Sub-Commands

The table below summarizes common sc_auth operations:

Command Invocation	Required Privileges	Operational Role
sc_auth identities	Standard User	Lists all certificates and hashes found on currently inserted SmartCards.
sc_auth list [user]	Standard User	Displays all SmartCard hashes currently paired with a specific macOS user.
sc_auth pair -u <user> -h <hash>	Administrative (sudo)	Pairs a specific SmartCard certificate hash with a target user account.
sc_auth unpair -u <user> -h <hash>	Administrative (sudo)	Unpairs a specific card from the user account.
sc_auth unpair -u <user>	Administrative (sudo)	Purges all paired SmartCards from the specified user account.

Pairing a SmartCard to Your macOS Account

To pair the detected card with your active user account:

1. Open Terminal (Applications > Utilities).
2. Identify your username:

   whoami

3. Execute the pairing command using the hash copied from sc_auth identities:

   sudo sc_auth pair -u $(whoami) -h 8F4D3C2E1B...

4. Enter your macOS administrator password when prompted.
5. Verify the pairing was committed to Open Directory:

   sc_auth list $(whoami)

   Terminal will list the paired identity hash confirming association.

Unpairing Lost or Revoked SmartCards

If a hardware token is lost, stolen, or expired, immediately unpair it to revoke authentication privileges:

sudo sc_auth unpair -u username -h 8F4D3C2E1B...

To wipe all paired cards from an account simultaneously:

sudo sc_auth unpair -u username

Frequently Asked Questions

Does sc_auth work with standard YubiKey OTP or FIDO2 keys?

sc_auth operates specifically on the PIV (SmartCard) applet of YubiKeys and hardware tokens. Standard WebAuthn/FIDO2 passkeys or Yubico OTP strings are handled via browser APIs and PAM modules rather than the macOS SmartCard subsystem.

What happens if a paired SmartCard is removed while logged in?

In macOS System Settings (or via configuration profile), administrators can configure the SmartCard Token Removal Action to automatically lock the screen or log out the user whenever the physical card is detached.