entraYK

ℹ️ About

entraYK is a PowerShell module for managing YubiKeys as device-bound passkeys (FIDO2) in Microsoft Entra ID.
Functionality includes the ability to:

• Configure the "Passkey (FIDO2)" authentication method,
• Create a custom authentication strength definition,
• Register a YubiKey as device-bound passkey on behalf of a user¹
• List YubiKey attributes for all or select user(s)²

¹This Cmdlet is making use of Oscar Virot's powershellYK module.
²Output includes YubiKey nickname, firmware version and Fido certification level.

⚠️ Disclaimer

The PowerShell module provided herein is made available on an "as-is" basis, without any warranties or representations, whether express, implied, or statutory, including but not limited to implied warranties of merchantability, fitness for a particular purpose, or non-infringement.

💻 Prerequisites

Use of the powershellYK module requires the following prerequisites be met:

• PowerShell 7 (pwsh)

💾 Installation

To install entraYK:

1. Open PowerShell
2. Execute command: Install-Module entraYK
3. Press Y when prompted to proceed with installation
4. Execute command: Import-Module entraYK

📖 Usage

Configure the "Passkey (FIDO2)" authentication method

This Cmdlet (Set-YubiKeyAuthMethod) configures the "Passkey (FIDO2)" authentication method in Microsoft Entra ID. Importantly it configures the method for all users and it enforces FIDO device attestation with white-listing of YubiKeys. The Cmdlet can whitelist either all(!) FIDO2-capable YubiKeys or select YubiKey models as defined by their AAGUID. The Cmdlet will reject non Yubico AAGUIDs.

Enable the Passkey method defining all YubiKey models:

Set-YubiKeyAuthMethod -All

Enable the Passkey method defining a specific YubiKey model by AAGUID:

Set-YubiKeyAuthMethod -AAGUID "fa2b99dc-9e39-4257-8f92-4a30d23c4118"

Resulting Entra ID configuration:

NOTE: You can find YubiKey AAGUIDs here: https://yubi.co/aaguids

Create a custom authentication strength definition

This Cmdlet (Set-YubiKeyAuthStrength) adds a custom authentication strength to Microsoft Entra ID. The Cmdlet can either add all(!) FIDO2-capable YubiKeys or select YubiKey models as defined by their AAGUID. In addition to any defined YubiKey the Cmdlet will also add support for Temporary Access Pass (TAP) as a single use authenticator. The method created will be named "YubiKey" and can be selected in Conditional Access policies to require phishing-resistant MFA using YubiKeys as device-bound passkeys. An optional user-selected name can be provided using the -Name parameter.

Add a custom authentication strength using all FIDO2 passkey-capable YubiKey models:

Set-YubiKeyAuthStrength -All

Add a custom authentication strength using only select YubiKey model(s) by their AAGUID(s):

Set-YubiKeyAuthStrength -AAGUID "fa2b99dc-9e39-4257-8f92-4a30d23c4118"

Add a custom authentication strength with your name of choice

Set-YubiKeyAuthStrength -All -Name "AAL3"

Resulting Entra ID configuration:

NOTE: You can find YubiKey AAGUIDs here: https://yubi.co/aaguids

Register a YubiKey as device-bound passkey on behalf of a user

This Cmdlet (Register-YubiKey) performs Enrollment On Behalf Of (EOBO) with Microsoft Entra ID. The Cmdlet uses powershellYK for YubiKey configuration and credential creation. It will generate a random PIN, name the YubiKey to contain Serial Number for assett tracking purposes, and where supported it will set the ForceChangePin flag and enable Restricted NFC.

Register a YubiKey on behalf of a user:

Register-YubiKey -User "[email protected]

Sample output:

UPN           : [email protected]
Nickname      : YubiKey with S/N: 23616243
Serial Number : 23616243
PIN           : 5144

List YubiKey attributes for all or select user(s)

This Cmdlet (Get-YubiKeys) lists properties about enrolled YubiKeys in Microsoft Entra ID. It can perform this listing either for all accessible users or for select user(s) by User Principal Name (UPN). Information presented includes firmware version, nickname as well as Fido certification level.

Get YubiKey information for all users you have access to in the tenant:

Get-YubiKeys -All

Get YubiKey information for a single user:

Get-YubiKeys -User "[email protected]" 

Sample output:

UPN                Nickname        Firmware      Certfication
-------------------------------------------------------------
[email protected]    YubiKey 5 Nano  5.7           L2
[email protected]      YubiKey 5 NFC   5.7           L2
[email protected]     YubiKey 5C NFC  5.2 / 5.4     L1

NOTE: The logic to present firmware version is dependant on Entra ID storing YubiKey AAGUID. Because AAGUIDs does not necessarily change with firmware version it is possible that a YubiKey is either one firmware or another as shown above (5.2 / 5.4).

📖 Roadmap

Possible improvements includes:

• Passkey "EOBO" enrollment using powershellYK
• Add -Name param for Set-YubiKeyAuthStrength
• Ability to fetch last used authenticator by UPN
• Configuration by Certification level (e.g.: "L2 only YubiKeys")
• Configuration by Firmware version (e.g: "all 5.7+ YubiKeys)

🥷🏻 Contributing

You can help by getting involved in the project, or by donating (any amount!).
Donations will support costs such as domain registration and code signing (planned).

📜 Release History

• 2025.02.01 v0.4.0
• 2025.02.01 v0.3.0
• 2025.01.28 v0.2.0
• 2025.01.26 v0.1.0