Article

Configuring Smart Card Authentication

Set preferences for smart card authentication operations, including those on managed devices.

Overview

When you use the CryptoTokenKit framework to manage hardware tokens as two-factor authentication devices, as described in Authenticating Users with a Cryptographic Token, the authentication process is subject to certain configuration options.

Set Values in com.apple.security.smartcard Preferences

You configure Smart Card authentication by setting values in the com.apple.security.smartcard preferences domain. For each setting, the framework first tries to read from Mobile Device Management (MDM) settings. Next, it looks at systemwide preferences. Finally, it falls back on default values for anything still unspecified.

The framework looks for and responds to the following preference keys:

checkCertificateTrust

An integer that defaults to 0.

Indicates how the framework should handle certificates, with settings ranging from least to most secure.

0

Trust every certificate. Although this setting is the default, it’s only suitable for users with self signed certificates. Corporate systems should typically use a more secure setting.

1

Test that certificates are within their validity period and that the issuer is trusted by the system.

2

Like 1, but with a soft revocation check. That is, as long as the certificate is not explicitly rejected by certificate revocation check, it remains valid. When a check can‘t be completed, the certificate remains valid.

3

Like 1, but with a hard revocation check. Unless a certificate revocation check explicitly validates the certificate, it‘s considered invalid.

UserPairing

A Boolean that defaults to true.

If this is set, when a user inserts an unpaired card into the system and the card appears suitable for authentication, the user is prompted to associate the card with the current user. This action must be authorized by an administrative user.

You can use the UserSelector command line utility when you need to manage bindings generated as a result of such a pairing, as described in Managing User-to-Smart Card Bindings.

allowSmartCard

A Boolean that defaults to true.

When disabled, the system does not attempt to use smart cards for user authentication (login, keychain unlock, and so forth). However, smart cards are still accessible for other purposes, like signing emails.

oneCardPerUser

A Boolean that defaults to false.

When enabled, the system only allows a user to be newly paired with a single smart card. Enabling this feature does not affect any existing pairings in the system. A user already paired with multiple smart cards doesn‘t become unpaired.

enforceSmartCard

A Boolean that defaults to false.

When enabled, the system requires smart card authentication for login, authorization, or screensaver unlock. Other authentication methods like passwords and Touch ID fail. In some cases, such as preference sheets which always require a password, the user may receive two prompts: one for the smart card followed by one for the password.

See Also

Smart Card App Extensions

class TKSmartCardTokenDriver

The driver that acts as an entry point for smart card app extensions.

class TKSmartCardToken

A representation of a smart card based cryptographic token.

class TKSmartCardTokenSession

A token session that is based on a smart card token.