Documentation: macOS SmartCard information is incorrect and incomplete

[jamierrichardson]

Filing an issue- anything else you want added?

Describe the bug The macOS directions have several discrepancies and omissions with Apple's documentation. Please revise current documentation to facilitate smartcard setup on macOS, including all setup options, troubleshooting your setup, etc

To Reproduce Steps to reproduce the behavior:

1. Directory pairing should be directory attribute mapping- the card is not paired to the directory, so this is incorrect.

2. Local directory mapping is omitted and is typically the best option for government customers, when paired with certificate pinning.

3. Deployment options: steps option 3 Pushing a profile to the device only sets up mdm controls. Additionally a script or package must be used to install the plist. For local directory mapping, a script must be used to populate the directory.

4. Nothing is explained about what is needed for the smartcardlogin.plist or what it does, other than providing an oversimplified example of some context of what it is mapping. Nothing is mentioned of case sensitivity. Nothing is mentioned on how to confirm the NT Principal Name and AltSecID match.

5. Nothing is explained about ownership or permissions required for the plist.

6. smartcard services in macOS also has a man page. Open terminal and type man SmartCardServices to gain access to additional deployment information and card/ setup requirements and options.

7. No mention of additional tools for troubleshooting like SmartCard Utility (third party) or how to confirm attributes are matching

8. No mention of how to get additional support (AppleCare or Apple Professional Services)

9. No mention how to change PIN on card.

Expected behavior Documentation provided should facilitate actual deployment by a government agency. Please have someone perform the necessary steps to accomplish this task for each option provided in order to deliver proper documentation. Explain differences and requirements of each approach.

Please contact Apple GSA support team if there are any questions.

Screenshots Add more Screenshots as you document the process required to enable smartcard services

Desktop (please complete the following information):

• OS: macOS 15
• Browser Safari

[claytonjbarnette]

The Configure Smart Card Logon for MacOS, was based on the 2018 implementation guidance provided by NASA (https://www.idmanagement.gov/implement/scl-macos/) in 2021. Additionally, @maxwellfunk addressed a few of these items in this issue in #1149 and PR #1159. He is working on finalizing the Network Smart Card Authorization playbook that will address a few of the items regarding Windows directory attribute mapping mentioned in the To Reproduce section of this Issue:

• Items 1 and 4 will be partially addressed as part of the Network Smart Card Authorization playbook, which is already linked in the current version of the Mac OS playbook.

• Item 2 is already partially addressed in the local account parking section, we may need more information from the commenter to be fully addressed.

• Item 3 uncertain of how to address and if they are referring to a local directory or a windows directory, additional information required from commenter.

• Item 5 should be apparent to organizations that incorporate Mac devices in their networks and is already partially addressed in the last step of the current playbook.

• Item 6 may be relevant for an alert, but not sure if this is for local configuration or by group device administrators.

Items 7 & 8, are out of scope as they include third party resources, and links are provided under Helpful Resources on the page.

Item 9 is out of scope for the playbook as it does not impact smart card login and is generally performed by middleware that varies from system to system.

Items in this issue addressed in #1149 by @maxwellfunk

[jamierrichardson]

Leveraging 2018 documentation in 2024 is problematic- many features have changed, as has best practices.

Apple releases a deployment guide with full documentation of SmartCard services. Please consider leveraging vendor documentation:

https://support.apple.com/guide/deployment/intro-to-smart-card-integration-depd0b888248/web

Additionally, the system engineer at Apple that supports GSA should be a well versed resource that you can also leverage if there are any questions on implementation.

Re - item 2- Please feel free to contact me directly and I can provide greater detail.

Re - item 3 - i am referring to the local directory implementation in macOS that is responsible for local account management. In order to perform local account pairing, an attribute must be added to the user account record, as would exist in Active Directory. AD binding on macs is no longer a best practice promoted by Microsoft or Apple. The local attribute mapping approach is fully documented by Apple, and is used by most federal agencies.

Re - item 5 - the goal of a playbook is to provide instruction to those new to the game. Having ownership/permissions information alongside the plist creation details guarantees a new admin does not miss a step- SmartCard mapping will not work without the correct permissions. This page https://www.idmanagement.gov/implement/scl-macos/ does not reference the ownership or permissions for the plist.

Re - item 6 - it's for both- the man page and deployment guide cover very specific elements of provisioning requirements, deployment, and additional configuration options. Local or directory based, many of these options should be documented in your playbook or referenced back to the source material.