1. Yubico
  2. Phishing-resistant MFA
  3. Smart Card Deployment

macOS Native Smart Card Support for Logon with Windows Server

Avatar
Laura
Created - Updated

Intro

Beginning in macOS High Sierra, Apple integrated native support for Smart Card Authentication against a Windows AD or LDAP environment, allowing for a unified strong authentication deployment across both Windows and Mac computers. In such a deployment, the YubiKey can be used as an authentication device for accessing domain accounts on both platforms, without requiring additional hardware for each. With the YubiKey’s cross-platform support, a mixed environment can be secured safely, quickly, and simply.

Prerequisites

A compatible environment capable of providing Smart Card Authentication, as well as administrator access to the client Mac endpoints is required to enable Smart Card Authentication on macOS. This includes:

  • A Windows Server deployment running the following server roles
    • Active Directory (AD)
    • Active Directory Certificate Services (ADCS)
  • Client Macs must have macOS 10.13.4 or above
  • Local Admin account on macOS
  • Domain Admin credentials

Setting up the Environment for macOS

The High Sierra release of macOS was created to seamlessly merge into a Windows Server based domain, including the Windows Certification Authority. For setting up the Windows AD and CA environment, refer to the directions provided in the YubiKey Smart Card Deployment Guide. However, macOS does require specific templates for generating certificates. Specifically, an Encryption Certificate is required alongside an Authentication Certificate. The templates used to create the required certificates are detailed in this section, as well as the process required to provision the YubiKey to ensure the certificates are loaded to the correct location.

Creating a Smart Card Login Template for User Self-Enrollment

Perform the steps below on your issuing Certificate Authority to create a certificate template for smart card login.

  1. Right-click the Windows Start button and select Run. 
  2. Type certtmpl.msc and press Enter. 
  3. Click Certificate Templates, locate and right-click Smartcard Logon, and select Duplicate Template. 
  4. Select the Generaltab and make the following changes as needed: 
    1. For Template display name / Template name, we recommend that you choose a short name without spaces such as YKSC. 
    2. For Validity period, ensure the timeframe you specify does not exceed the restrictions for your Certification Authority. 
    3. Ensure the option to Publish certificate in Active Directory is selected. 
  5. . Select the Compatibility tab and make the following changes as needed: 
    1. Select the operating system (OS) that matches the OS of the Certification Authority. 
    2. For Certificate recipient, select the oldest Windows operating system in your Active Directory domain. 
  6. Select the Request Handling tab and make the following changes as needed: 
    1. For Purpose, select Signature and encryption. 
    2. Ensure the option for Include symmetric algorithms allowed by the subject is selected. 
    3. Ensure the option for Renew with the same key is selected. This option may be disabled if Windows 7 and below are included in the Compatibility settings. 
    4. Check the option For automatic renewal of smart card certificates, use the existing key if a new key cannot be created. 
    5. Select the option for Enroll subject without requiring any user input. 
  7. On the Cryptography tab make the following changes as needed: 
    1. Provider category: Select Key Storage Provider from the dropdown. 
    2. Algorithm name: Select RSA.
    3. Minimum key size: 2048. 
    4. Select the option for Requests must use one of the following providers. 
    5. Under Providers, select Microsoft Smart Card Key Storage Provider. 
    6. For Request hash, select SHA256 from the list displayed. 
  8. On the Security tab make the following changes as needed: 
    1. Group or user names: Confirm the domain group you want to allow access to the template is listed. If not, click Add, enter the name of the group, and then click OK. 
    2. Permissions for [group name]: Ensure Read and Enroll are checked. If users will be auto-enrolling using the built-in Windows functionality, also check Autoenroll. 
  9. Click Apply, and then click OK to close the template properties window. 
  10. Close the Certificate Templates window. 

Creating a macOS KeyChain Encryption Template for User Self-Enrollment

Perform the steps below on your issuing Certificate Authority to create a certificate template for encryption to unlock the macOS Keychain.

  1. Right-click the Windows Start button and select Run. 
  2. Type certtmpl.msc and press Enter. 
  3. Click Certificate Templates, locate and right-click Basic EFS, and select Duplicate Template. 
  4. Select the General tab and make the following changes as needed: 
    1. For Template display name / Template name, we recommend that you choose a short name without spaces such as YKEncryption. 
    2. For Validity period, ensure the timeframe you specify does not exceed the restrictions for your Certification Authority. 
    3. Ensure the option to Publish certificate in Active Directory is selected. 
  5. Select the Compatibility tab and make the following changes as needed: 
    1. Select the operating system (OS) that matches the OS of the Certification Authority.
    2. For Certificate recipient, select the oldest Windows operating system in your domain environment. 
  6. Select the Request Handling tab and make the following changes as needed: 
    1. For Purpose, select Encryption. 
    2. Ensure the option for Include symmetric algorithms allowed by the subject is selected. 
    3. Ensure the option for Renew with the same key is selected. This option may be disabled if Windows 7 and below are included in the Compatibility settings. 
    4. Uncheck Allow private key to be exported.
    5. Check the option For automatic renewal of smart card certificates, use the existing key if a new key cannot be created. 
    6. Check the option for Enroll subject without requiring any user input.
  7. On the Cryptography tab make the following changes, as needed: 
    1. Provider category: Select Key Storage Provider from the dropdown. 
    2. Algorithm name: Select RSA.
    3. Minimum key size: 2048. 
    4. Select the option for Requests must use one of the following providers. 
    5. Under Providers, select Microsoft Smart Card Key Storage Provider. 
    6. For Request hash, select SHA256 from the list displayed. 
  8. On the Security tab, make the following changes, as needed: 
    1. Group or user names: Confirm the domain group you want to allow access to the template is listed. If not, click Add, enter the name of the group, and then click OK. 
    2. Permissions for [group name]: Ensure Read and Enroll are checked. If users will be auto-enrolling using the built-in Windows functionality, also check Autoenroll. 
  9. Click Apply, and then click OK to close the template properties window. 
  10. Close the Certificate Templates window. 

Adding the Templates to the Certification Authority

Perform the steps below on your issuing Certificate Authority to publish the certificate templates so that they are available for enrollment.

  1. Right-click the Windows Start button and select Run. 
  2. Type certsrv.msc and press Enter. 
  3. Click Certification Authority, double-click your server, double-click Certificate Templates, right-click on the white space within the center pane, select New and then select Certificate Template to Issue. 
  4. Locate and select the recently created smartcard logon template, and then click OK. 
  5. Repeat steps 3 and 4 for the recently created encryption template.

Note: Allow Active Directory to update. Depending on environment, it could take up to eight hours for the templates to publish to Active Directory. 

Enrolling Certificates to the YubiKey

See the Using Auto-Enrollment to Enroll Users section of the knowledge base article Setting up Smart Card Login for User Self-Enrollment for enrolling certificates to the YubiKey. It is important there are no previous certificates on the YubiKey and that you enroll the smartcard logon certificate first, then the EFS certificate. This ensures the certificates will be written to the correct slots for macOS.

Configuring macOS for Smart Card Support

In order for the YubiKey as a smart card to authenticate to the Windows Certification Authority correctly, the macOS computer needs to trust the Windows Certificate Services. This requires the ADCS Root Public Certificate to be loaded into the macOS keychain as a trusted root.

Exporting the Root Public Certificate

To export the domain root public certificate, follow the steps below on the issuing Certificate Authority. 

  1. Right-click the Windows Start button and select Run. 
  2. Type certmgr.msc and press Enter.
  3. In the tree view, expand Trusted Root Certificate Authorities and then Certificates under that.
  4. Locate the certificate issued to your ADCS Root CA, right-click on it, and select All Tasks > Export...
  5. In the certificate export window, click Next.
  6. Select Base-64 encoded X.509 (.CER) and click Next.
  7. Click Browse… and select where to save the certificate and click Next.
  8. Click Finish to save the certificate and exit the wizard.
  9. Copy the certificate to a USB drive or network share where it will be accessible from the Mac.

Importing Root Public Certificate

Run the command below in Terminal to import the domain root public certificate into the macOS System KeyChain.

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /path/to/certificate.cer

Disabling Smart Card User Pairing

By default, macOS will ask users to bind a YubiKey with valid Authentication and Encryption certificates to local user accounts. To disable this dialog and utilize the user information in the issued certificates, run the command below in Terminal to disable the smart card user pairing UI.

sudo defaults write /Library/Preferences/com.apple.security.smartcard UserPairing -bool NO

Domain Binding macOS to the Windows Domain

Any macOS computer can be joined to a Windows or LDAP domain, allowing domain accounts and resources to be utilized. There are two options for doing so; either creating Workstation or Mobile Accounts on the macOS computer. Workstation accounts require a connection to the domain to authenticate every time, not just when adding new user accounts. Mobile accounts can authenticate to accounts already present on the macOS computer without requiring a connection, although communication to the domain is still necessary for adding to accounts. 

When deploying multiple macOS computers, each can be configured for the account type which is better for the intended usage - mobile accounts are ideal for laptops which connectivity is not assured, while workstation accounts ensure any access to network resources are authenticated by the domain.

Domain Binding macOS to the Windows Domain Workstation Clients

  1. Open Directory Utility.
  2. Click the lock icon, then enter an administrator’s username and password.
  3. Select Active Directory, then click Edit.
  4. Enter the FQDN in Active Directory Domain Name.
  5. Enter a computer name you wish to use to Bind to Active Directory.
  6. Click Bind.
  7. Enter your Active Directory Administrator username and password.
  8. Click OK.
  9. Verify the binding using the Directory Utility app
    1. Select Directory Editor from the toolbar.
    2. Using the pulldowns below the toolbar, select Viewing “Users” in node “/Active Directory/….”
    3. Type a Domain user into the Search field.
    4. Select the user from the list below the search field.
    5. Make note of the “AltSecurityIdentities” value and ensure it is formatted (case sensitive) as Kerberos:<username>@<domain.extension>
      (ie example@yubidemo.lab)

  10. As a final step, ensure the macOS device is connected to the domain when logging in as domain accounts for the first time. Subsequent logins can be performed when disconnected to the domain.

Note: macOS LDAP and Kerberos queries are case sensitive in stark contrast to Microsoft operating systems that are case insensitive. The “AltSecurityIdentities” must be identical, including capitalization, to the SAN / Common Name on the Authentication certificate for macOS to match a certificate to a Active Directory user account 

 

Domain Binding macOS to the Windows Domain Mobile Clients

  1. Open Directory Utility.

  2. Click the lock icon, then enter an administrator’s username and password.

  3. Select Active Directory, then click the Edit (pencil) icon.

  4. Enter the domain’s FQDN in Active Directory Domain.

  5. Enter a computer name you wish to use to Bind to Active Directory.

  6. If the advanced options are hidden, click the disclosure triangle.

  7. Click User Experience, then click Create mobile account at login. Do not click “Require confirmation before creating a mobile account.”

  8. Click Bind.

  9. Enter your Active Directory Administrator username and password.

  10. Click OK.

  11. Verify the binding using the Directory Utility app

    1. Select Directory Editor from the toolbar.

    2. Using the dropdown menu below the toolbar, select Viewing “Users” in node “/Active Directory/….”

    3. Type a Domain user into the Search field.

    4. Select the user from the list below the search field.

    5. Make note of the “AltSecurityIdentities” value and ensure it is formatted (case sensitive) as Kerberos:<username>@<domain.extension>
      (ie example@yubidemo.lab)

  12. As a final step, ensure the macOS device is connected to the domain when logging in as domain accounts for the first time. Subsequent logins can be performed when disconnected to the domain.

Note: macOS LDAP and Kerberos queries are case sensitive in stark contrast to Microsoft operating systems that are case insensitive. The “AltSecurityIdentities” must be identical, including capitalization, to the NT Principal Name on the Authentication certificate for macOS to match a certificate to a Active Directory user account 

Enabling Smart Cards for Domain Authentication Mobile Clients

macOS supports smart card binding via a plist file, which details for macOS which attributes common to a certificate and Active Directory credentials need to match identically to use a YubiKey for Smart Card Authentication. These instructions are based on the official Apple documentation for macOS smart card-only authentication as referenced here: https://support.apple.com/en-us/HT208372

  1. Create the “SmartcardLogin.plist” mapping file with the following contents:

<?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>

This file allows the Mac to identify the smart card user and map the user to an entry in Active Directory. This is done by mapping the “NT Principal Name” from the Key Management Certificate to the “AltSecurityIdentities” field in AD, and selecting the user with the matching value.
The line <string>Kerberos:$1</string> prepends “Kerberos:” to the NT Principal Name and the resulting string is used to match values.
The system is case sensitive, so the values must match exactly.
This file must also be plain text with unix style line breaks.

  1. Use Terminal to execute the following command to verify the file:
    plutil -lint SmartcardLogin.plist

  2. Using Terminal, copy the SmartcardLogin.plist file to the path “/private/etc/“ by executing the following command:
    sudo cp SmartcardLogin.plist /private/etc

  3. Using Terminal, update the permissions with the following commands:
    sudo chown root:wheel /private/etc/SmartcardLogin.plist 
    >sudo chmod 644 /private/etc/SmartcardLogin.plist

These commands will assign the SmartcardLogin.plist file to the root account and the root admin user group, as well as preventing the file from being edited by anyone but the root account.

At this point, smart card authentication should now be enabled. To confirm, log out of the current user session and verify that you are prompted for a PIN at the login screen when you insert the YubiKey.

Advanced Configurations

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. 

  1. Use the following command to backup the sshd_config file:

sudo cp /etc/ssh/sshd_config /etc/ssh/sshd_config_backup_`date "+%Y-%m-%d_%H:%M"`

  1. 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

If a user wants to authenticate SSH sessions using a smart card, have them follow these steps on their Mac.

  1. Use the following command to export the public key from their smart card:

ssh-keygen -D /usr/lib/ssh-keychain.dylib

  1. Add the public key from the previous step to the ~/.ssh/authorized_keys file on the target computer.

  2. Use the following command to backup the ssh_config file:

sudo cp /etc/ssh/ssh_config /etc/ssh/ssh_config_backup_`date "+%Y-%m-%d_%H:%M"`

  1. In the/etc/ssh/ssh_config file, add the line to the end of the file.

PKCS11Provider=/usr/lib/ssh-keychain.dylib

If the user wants to, they can also use the following command to add the private key to their ssh-agent:

ssh-add -s /usr/lib/ssh-keychain.dylib

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

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:

# 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

FileVault Configuration

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. To change this so that the user will not automatically be logged in and will be shown the login screen, run the command below in Terminal.

sudo defaults write /Library/Preferences/com.apple.loginwindow DisableFDEAutoLogin -bool YES

Pairing macOS to Legacy KeyChain

To pair to the legacy KeyChain (KeyChain.app) you will need to install a compatible TokenD Driver such as OpenSC (https://github.com/OpenSC/OpenSC/wiki). This is not required the current macOS Keychain service.

Managing macOS with Mobile Device Management (MDM)

For most larger macOS deployments, a Mobile Device Management (MDM) is utilized to automate setup and configuration tasks. MDMs can be utilized for enabling a macOS fleet to utilize the YubiKey as a Smart Card for authentication. Users should refer to the resources provided by their own MDM solution or Apple at: https://support.apple.com/en-us/HT208372#configsample

Troubleshooting

Ensure that permissions are properly set for that file per the instructions in the Enabling Smart Cards sections of this guide.

Test the SmartCard Reader driver is installed and the OS can read the certificates. Open Terminal and run the following commands.

sudo pcsctest
sudo system_profiler SPSmartCardsDataType

Known Issues

  • When attempting to make changes under System Preferences by clicking the padlock, you will need to use your username and password for authentication; smart cards are not supported for authentication in this case (this is a limitation of macOS).

Additional Resources

Apple has provided documentation on the macOS support pages linked below.

Join your Mac to a network account server: https://support.apple.com/guide/mac-help/join-your-mac-to-a-network-account-server

Smart card overview: https://help.apple.com/deployment/macos/#/apd1fa5245b2

Configure macOS for smart card-only authentication: https://support.apple.com/en-us/HT208372

Smart card payload settings: https://developer.apple.com/library/archive/featuredarticles/iPhoneConfigurationProfileRef/Introduction/Introduction.html