Overview

This tool allows you to register FIDO2 security keys for multiple users by processing their details from a CSV file. It supports setting random PINs, managing keys, and logging operations. The script is created using PowerShell and is based on the DSInternals.Passkey module, which leverages the new FIDO2 provisioning APIs within Microsoft Entra ID. The tool provides a graphical interface for user-friendly interaction.

Prerequisites

• Required Hardware: While the solution works with any compatible FIDO2.1 key, some features are specific to certain revisions. Setting PINs and forcing PIN changes are only available for keys with FIDO2.1 Final firmware, and serial numbers of keys are available only with the PIN+ series.
• Required Software: PowerShell 5.1 or later, Microsoft.Graph module, and DSInternals.PassKeys module. The script will install the required modules automatically.
• Required Files:
  • read_serial_t2.exe: Utility to read the serial number of FIDO keys.
  • fido2-manage.exe: Tool to manage FIDO2 keys.
    (both are included in the archive along with the PowerShell script)
• Input File: A CSV file with a column named UPN (User Principal Name).
• Permissions: The script needs to run as Administrator (due to Windows OS FIDO2 Native API limitations). The Entra account needs relevant Graph API permissions (UserAuthenticationMethod.ReadWrite.All).
• Entra Account with Proper Permissions:
  • An account with proper permissions to launch the Graph API is needed.
  • If the account to be used is FIDO2/Passkey protected, the PowerShell window cannot be used to log in.
  • Instead, log in to an application (e.g., MS Teams, even if the account is unlicensed for it) with Passkey.
  • Choose "Sign in to all your apps" (instead of "Sign in to this app only").
    
  • This action will add the account to the list of logged-in credentials, allowing you to simply choose a logged-in account when prompted.

Features

• Set random or custom PINs for FIDO2 keys.
• Force PIN change after provisioning (if enabled, users will be required to set a new PIN upon first use)
• Automatically copy generated PINs to the clipboard.
• Log results to a specified file.
• Handle errors gracefully with visual prompts.

Using the Tool

1. Launch the Tool

Run the PowerShell script (EnrollFIDO2.ps1). A graphical interface will appear. Ensure that your PowerShell execution policy allows script execution. If needed, run Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted or similar before executing the script.

2. Configure Tenant ID

Enter the Tenant ID (e.g., tenantname.onmicrosoft.com) in the input field. This value will be remembered for the next run.

3. Select the Input CSV

Click the "Select File" button and choose a valid CSV file containing user UPNs. See an example of how that file should look like below:

UPN
[email protected]
[email protected]

4. Configure PIN Options

• Set Random PIN: Check this box to generate a random 6-digit PIN for each key.
• Copy PIN to Clipboard: Check this box to copy each generated PIN to the clipboard automatically.
• Force PIN Change: Check this box to enforce a PIN change on the key.

5. Set Log File Path

Click the "Set Log File" button to choose where to save the operation logs.

6. Proceed with Registration

Click the "Proceed" button to start the registration process. The tool performs the following for each user:

• Reads the FIDO key serial number.
• Optionally sets a random PIN.
• Shows a dialog window with the above information for verification. If all is correct, click "Add key" to proceed further:
  
• Clicking "Add key" registers the FIDO key for the user using Graph API. This part relies on standard Windows OS native FIDO passkey creation dialogs and cannot be fully automated.
  
  For easier provisioning, the script can copy each new PIN to the clipboard, allowing you to press Ctrl+V on the relevant window. The PIN will also be displayed in a resized window to ensure the native dialog does not overlap.
  
• Logs results to the specified file. Note: If you have selected the random PIN option, you may need to refer to this log file later to communicate the PIN to the end user.

Interactive Prompts

After processing each user, the tool displays a prompt:

"Prepare the next key and click OK to continue."

Insert the next key and click OK to proceed. If the last user is reached, the tool finishes without additional prompts.

Error Handling

• Missing Tenant ID: Displays an error if the Tenant ID is not provided.
• Invalid CSV: Prompts the user to select a valid CSV file if the selected file is missing or invalid.
• Key Read Errors: Alerts the user if no valid serial number is detected.
• Provisioning Errors: Provides detailed error messages if an issue occurs during key registration.

Logs

The tool creates or appends to a log file with the following details for each user:

• UPN (User Principal Name)
• Serial Number of the FIDO key
• PIN (if set)
• Forced PIN Change status

UPN,Serial Number,PIN,ForcePINChange
[email protected],86109200000021,142375,True
[email protected],86109400000020,497210,True

Troubleshooting

• No Serial Number Detected: Ensure the FIDO key is connected properly and retry the operation. Only PIN+ keys have the API to read the serial number.
• Error Connecting to Graph API: Verify the provided Tenant ID and check your Graph API permissions.
• Tool Doesn't Launch: Ensure required modules are installed and run the script with appropriate permissions.

Advanced Features

• PIN Complexity: Random PINs avoid sequential numbers, repeated digits, or palindromes.
• Clipboard Integration: Automatically copies PINs for quick use.

Contact Support

If you encounter issues or need assistance, contact us with the following information:

• Error messages displayed during operation.
• A copy of the generated log file for analysis.