Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal Government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a Federal Government site.


The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

Configure Smart Card Logon for MacOS

As federal IT networks and systems expand, especially in light of recent Bring-Your-Own-Device (BYOD) models gaining popularity, it has become necessary to extend mandatory security controls to previously unsupported devices. This guide provides implementation resources to enable smart card authentication on Mac operating system (macOS) workstations and laptops for macOS-local and windows-domain accounts.

macOS Version Support

Smart card logon is natively supported on macOS Sierra 10.12 or later and Windows Server Directory logon since High Sierra 10.13. All instructions contained within this guide assume the implementer is leveraging High Sierra or a more recent macOS.

Compliance Support

Enablement of mandatory smart card login for all Mac workstations and laptops within your environment will help align to the NIST SP 800-53 Identification and Authentication family of controls to support FISMA compliance.

Choose an Authentication Option

Agencies have two options to enforce smart card authentication in macOS.

  1. Local Account Pairing - For a non-domain joined macOS account, an agency may enable local account pairing. This method pairs a smart card to the local macOS user account and requires its use for desktop authentication. No domain or Kerberos architecture is needed.
  2. Windows Domain User Account - For a windows domain-joined device, an agency can map smart card attributes to an Active Directory account. This method involves creating a plist configuration file and disabling local pairing on the macOS device.

Agencies may additionally choose a machine or user-based enforcement which disables all password-based authentication.

  1. Machine-Based Enforcement (MBE): This implementation removes the option for password-based authentication in favor of smart card-only authentication for any account accessible by the macOS device (local or network).
  2. User-Based Enforcement (UBE): This implementation creates an exception to smart card-only authentication for specific users or groups of users (e.g., network admins, device admins, and individuals waived from smart card requirements).

This Apple Platform Deployment guide provides some additional detail on MBE vs. UBE. Additional details on Windows authentication enforcement models can be found here.

Local Account Pairing

Local Account Pairing is a user-prompted process.

  1. Insert the PIV card into a card reader connected to the macOS device.
  2. A series of prompts direct the user to pair the PIV card to the local account. The user will need administrative access to complete the process.
  3. Provide the PIV PIN and then log out.
  4. Insert the PIV and provide the PIN to log back in.

See this Apple Platform Deployment guide for more information on local account pairing.

Windows Domain Account Pairing

Most departments and agencies already maintain processes to map PIV attributes to Active Directory domain accounts. This playbook also provides guidance on the different models that can be used to link domain accounts to PIV certificate attributes.

Ensure the following prerequisites are complete or ready:

  1. The person completing this process has administrative privileges on the macOS device.
  2. The macOS device is joined to the Windows domain.
  3. Federal PKI and domain controller certificates are distributed and installed on the macOS device key store.

Domain Controller Certificate Trust

Many organizations run internal device PKIs that issue their domain controller certificates. Ensure all certificates needed to conduct a smart card domain authentication are distributed to the macOS devices.

Step 1. Disable Local Account Pairing

The local pairing interface must be disabled. To disable the local pairing dialog:

  1. Open the Terminal app.
  2. Type the following:
    sudo defaults write /Library/Preferences/ UserPairing -bool NO
  3. When prompted, enter the administrator password.

Step 2. Write the Property List

A property list, or plist, maps smart card attributes to a Windows domain account. The most common configuration is to map the NT Principal Name in the PIV Authentication certificate Subject Alternative Name to the userPrincipalName attribute in Active Directory. The following image provides the contents of a configuration file that extracts the NT Principal Name from a PIV to match against a directory AltSecID in support of an authentication event.

PList configuration for extracting a domain account identifier from a PIV.

Agencies may want to apply additional smart card configuration settings. Additional options may include:

  • allowSmartCard - Must be set to TRUE to allow the device to leverage smart cards for multiple functions (authentication, digital signing).
  • enforceSmartCard - Can be set to TRUE to ensure that smart card authentication is made mandatory at initial logon, authorization, and unlocking from screensaver mode.
  • tokenRemovalAction - If set to “1,” enables the screensaver when a smart card is physically removed from the device.
  • UserPairing - Can be set to FALSE to prevent the pairing dialogue from appearing on smart card insertion.
  • oneCardPerUser - Can be set to FALSE for users who may have multiple acceptable smart cards (e.g., PIV and alternative tokens).
  • checkCertificateTrust - Can be an integer between 0 and 3:
    • 0 - turns off certificate trust checking
    • 1 - turns on trust checking, but does not conduct revocation checking
    • 2 - turns on trust checking, and a ‘soft’ revocation check is conducted where ‘valid’ and ‘unknown’ are treated the same
    • 3 - turns on trust checking, and a ‘hard’ revocation check is conducted where the response must contain a ‘valid’ status to allow the authentication to proceed

Step 3. Choose a Deployment Method

An agency may deploy a plist through various remote mechanisms.

  1. Employ third-party Mobile Device Management (MDM) tools
  2. Leveraging an Apple specific configuration tool via the App Store
  3. Direct configuration profile delivery via an email, webpage, or over-the-air profile delivery

If a remote deployment is not available, the administrator may also perform the configuration locally following Step 1 and 2.

Helpful References

  1. Apple Deployment Guide - Use a smart card in macOS
  2. Apple Deployment Guide - Configure macOS for smart card-only authentication
  3. Apple Deployment Guide - Advanced smart card options in macOS

An official website of the U.S. General Services Administration

Looking for U.S. government information and services?
Visit Edit this page