Managing Passkey Lifecycle with Entra ID

Introduction

vSEC:CMS enables passkey lifecycle management for Entra ID, integrating via the Microsoft Graph API. Using a credential management system to manage your passkeys allows you to:

Enforce passkey usage: Require passkeys for authentication within your Entra ID environment.
Delegate passkey management: Offload the complexities of passkey storage, synchronization, and recovery to specialized third-party providers.
Centralize policy enforcement: Maintain control over authentication policies and user access through Entra ID.
Improve security: Benefit from the enhanced security of passkeys while simplifying user experience.

FIDO management - overview - white.png

FIDO2 credentials typically use HID interface for communicating with the device. If attempting to use/manage the FIDO2 credential over an RDP connection then this will not be possible as USB forwarding of HID supported devices is not possible out of the box. Therefore, when managing such credentials with vSEC:CMS you need to do this directly on a host where the device is attached.

It is required to install the RSDM service on any client where self-service FIDO2 operations are to be allowed. The RSDM service will allow for administration operations to be performed when issuing a FIDO2 credential or setting/changing the FIDO2 PIN.

Using an NFC reader for your credentials? You'll need to make sure the reader supports extended APDUs. Check your NFC reader's documentation or with the manufacturer to confirm this feature is supported.

Configure IdP

It will be required that a connection to an Entra ID user directory is already in place. See article here that describes how you can set this up. Additionally, as the Entra ID is in public preview for now the URL for the MS Graph used should be beta, for example https://graph.microsoft.com/beta.

Navigate to Options - Connections and select FIDO2 (IdP) if it exist, otherwise click Add and add FIDO2 (IdP).

Click Add and enter a name for the template and select Entra Id IdP (Preview) from the Type drop-down list.

In the Host Parameters section select the Entra ID user directory that you should have already setup for the Entra ID Connection. Click the Check Connection button to ensure connectivity.

Enable Set Challenge Timeout if it is required to have a timeout period for the challenge to be signed and responded to. You can set the value, in minutes, between 5 and 43200 minutes (30 days). In vSEC:CMS the signed challenge is sent to Entra ID when the token PIN is activated.

What is the Challenge Timeout?
The passkey authentication flow in Entra ID involves the following key steps:
1. vSEC:CMS gets a "challenge" (a nonce/random data) from Entra ID and sends to the user's token.
2. The user's authenticator (e.g., a FIDO2 token) signs the challenge using their private passkey.
3. The signed challenge is sent back to Entra ID for verification when vSEC:CMS activates the user's token PIN.
The challenge timeout is the maximum time a user has to successfully complete step 2 and 3—that is, to interact with their authenticator (token) (activate PIN) and transmit the signed response back to Entra ID.
If the user takes too long to activate the token, then it will not be possible to use the token to authenticate. You will need to restart the entire process in this case.

If you do not enable this setting the default value of 5 minutes will be applied.
For example, an operator may issue the credential on behalf of a user and then ships the token to the user. You may want to ensure that the user sets the PIN within a specified period of time. If the user does not perform the PIN activation within the configured period then the activation with Entra ID will fail and the token would need to be reissued to the end user.

Configure Credential Template for Central Issuance

If you plan to have operators/helpdesk persons issue credentials on behalf of users then follow the instructions in this section to configure such a template.

It will be required to perform the next steps from a client that has the vSEC:CMS Admin application installed (see the article Install Admin Application on how to set this up if you don't have this setup already).

We need to create a FIDO2 passkey template to begin with. Navigate to Templates - FIDO2 - FIDO2 Passkey Templates and click Add.

Enter a template name. In the Select FIDO2 IdP select the IdP already configured in your system from the drop-down field. You can click Manage to double check that you are going to use the correct one.

In the Display Name field either enter a static value or click the Configure button to use an already configured internal variable that maps to an attribute from the user directory. This might be required to set a more precise name for the display name, such as the users actual name.

The maximum length for the display name is 30 characters. This is enforced by Entra ID.

The Force Discoverable Credential checkbox is enabled and cannot be disabled and shown for information purposes here. This feature, which is supported by Entra ID, stores your username within the credential, eliminating the need to type it during authentication.

In the Relying Party section the Origin should match the endpoint the user is provided to access the signing service, as is the case in a standard WebAuthn service. For Entra ID this is typically https://login.microsoft.com.

Click Save to save and close.

Navigate to Templates - Credential Templates and click Add. Click the Edit link beside General.

Enter a template name and click the Detect button. Make sure that you have the FIDO2 token attached and selected from the reader drop-down list and click Ok. You should see something similar to below.

Enable the Enable FIDO2 check box and leave all other settings as is and click Ok at the bottom of the dialog.

In the Issue Credential section enable Assign user ID and select the Entra ID user directory that you wish to use from the drop-down list.

In the FIDO2 Options section click the Manage button. Click Add and enter a name for the template.

In the FIDO2 Configuration section the following settings can be configured:

Perform FIDO2 Reset Before Issuance: Reset the device's FIDO2 applet to its default state before issuance by enabling this setting. This option is only available for devices that do not require detachment and reattachment during a FIDO2 reset.
Always Require User Verification: User verification during authentication is optional for some IDPs. To require user verification, enable this setting. This feature is only available for devices supporting CTAP 2.1.
Enable BIO Enrollment: Enable this setting if the device supports FIDO2 BIO enrolment.
- Number of Enrollments: This is the minimum number of finger prints you need to enrol.
- Enrollment Timeout(ms): This is time (in milliseconds) you have to enrol at least one finger print.

The setting Enable BIO Enrollment is not yet fully implemented. Depending on the version of vSEC:CMS the settings will be shown or they will be hidden. This feature will be available in a future version of vSEC:CMS.

Enable FIDO2 PIN: A FIDO2 PIN is required. This setting is for informational purposes only and cannot be disabled.
Set Minimum PIN Length: If configured, this will be the device's minimum PIN length, which will be set within the FIDO2 applet extension minPinLength. This applies to CTAP 2.1 compatible devices.
Minimum PIN Length RP ID List: Only specify Relying Party (RP) IDs here if the minPinLength extension is supported. This parameter is strictly prohibited when the extension is not supported. For example, to put this RP ID login.microsoft.com double click the label and enter the value. To delete an entry, right click and select Delete. To edit the RP ID double click the entry.

In the Passkey(s) to Issue section enable the check boxes for the IdP(s) used in your environment that you want passkeys issued to.

Click the Edit link for Initiate Credential and enable Update Credentials at FIDO2 IdP. This will push the passkey for the user to Entra ID when setting the FIDO2 PIN on the credential.

Click the Edit link for Inactivate Credential and enable Update Credentials at FIDO2 IdP. This will remove the passkey on the IdP. You might do this if a user is on leave and you want to disable their passkey.

You cannot temporarily disable a passkey with the IdP. Therefore, if you disable a credential, you must reissue it entirely, i.e. revoke - retire - unregister and issue again.

Click the Edit link for Revoke Credential and enable Update Credentials at FIDO2 IdP. This will update the IdP when the authenticator is revoked. Additionally, enable Force FIDO2 Authenticator data deletion at IdP which will cancel the credential revocation process if the FIDO2 passkey could not be removed from the IdP.

Click Ok so save and close the configuration for the template.

Issue Passkey Credential Centrally

The credential can be issued either using the vSEC:CMS Admin or Agent applications. For either of these application refer to these articles Install Admin Application and Install Agent Application for instructions on how to set these up.

In this guide we will use the Agent Application.

Navigate to the Life Cycle tab and with a credential attached select the Issued oval along with the template from the available drop-down list and click Execute.

This will trigger the issuance flow. You will be prompted to select a user from your directory who the token will be issued to.

At the end of the issuance the token will be Issued. You can activate the token by selecting Active and setting a FIDO2 PIN that can then be used by the end used.

Alternatively, the end user can set the FIDO2 PIN using the vSEC:CMS User application. The vSEC:CMS User application needs to be online and connected to the backend vSEC:CMS service to perform setting a FIDO2 PIN (see below for more detailed example of this).

Now the user, for example, can try to login to their Entra ID account. Select the external key option.

Then enter your PIN and touch the token when prompted.

From the vSEC:CMS Admin console you can see details about the managed credential from Repository - Credentials by selecting a credential and clicking the Details button.

If you then need to revoke the credential, for whatever reason, the credential will be revoked on the IdP. For example, from the Life Cycle tab search for a user who you wish to revoke and you can then verify that the credential is revoked on the IdP by trying to log in with the hardware credential.

Set FIDO2 PIN via Self-Service

In dispersed environments it can be common for end users to set the FIDO2 PIN of their credential through the self-service application. In this section we will describe how this can be done with vSEC:CMS. We will build on the already created template from the section Configure Credential Template for Central Issuance above and extend this so it can be used in self-service operations.

Setting FIDO2 PIN via Self-Service

If you issued your credentials centrally via a team of operators who issue on behalf of the end users it maybe that the credentials are sent out via post to the end user where the FIDO2 PIN is not already set. In this case the end user can set their PIN using the vSEC:CMS User application. Please refer to the article Installing the vSEC:CMS User Application for instructions on how to install the application.

Additionally, when setting the PIN from the vSEC:CMS User application the user will need to authenticate. In this article we presume that you have the ability to leverage on OAuth2.0 support in Entra ID. Please refer to the article Configure OIDC Support for details on how you can configure support for OAuth.

Extending the existing template we created above navigate to the General section. Click the Manage button in the Self-service using the following template section.

Click Add and enter a template name. In the User Authentication for PIN Unblock select the Entra ID OAuth template that you already created. Leave all other settings like below and click Save to close and save.

Enable Self-service using the following template and select the template from the drop-down list. Click Ok to save and close. Then click Ok again to complete the template changes.

Issue a credential from Agent application. At the end of the issuance the credential will be in an Issued state.

Now lets presume that the credential has been provided to the end user. The end user can open vSEC:CMS User application and navigate to the PIN tab and select Unblock PIN (Crypto). Enter a PIN and confirm, then select Unblock to initiate the setting of the PIN.

You should be prompted to authenticate using your OAuth credential. In the background the PIN will be applied after successfully authenticating the user.

You should now be able to leverage the passkey credential when authenticating to your Entra ID.

Configure Credential Template for Self-Service Issuance

It maybe required for end users to perform self-service issuance. In this case an end user would be provided with never used before credentials in their default state. Then from the vSEC:CMS User application they can self issue the credential and set a PIN. In this section we will describe how this can be done. We will build on the already created template from the section Set FIDO2 PIN via Self-Service above and extend this so it can be used for self-service issuance operations.

Add Self-Service Issuance

You can extend the existing template we created in the section Configure Credential Template for Central Issuance above and navigate to the General section. Click the Manage button in the Self-service using the following template section.

Select the template created earlier and click Edit. Enable Self-issuance enabled check box and click Save to close and save. Close the dialog and select Cancel at the bottom of the General dialog.

Select Edit in the Issue Credential section.

Enable Automatically initiate credentials after issuance and Issue by User(s). Click the Configure button. In the User ID from drop-down select the Entra ID template where the user will be selected from. In the Authenticate user using drop-down select the Entra ID OAuth template that will be used to authenticate the user during credential issuance. Click Ok to save the changes and close.

Click Ok to save and close.

Click Ok to complete and close the template configuration.

Issue from vSEC:CMS User Application

On a client open the vSEC:CMS User application that is already configured to connect to the backend service. Navigate to the Credential tab and select the correct reader that the credential is connected to and click Issue.

From the Credential template select the template created earlier and click Issue.

You will be required to provide your Entra ID account and authenticate using OAuth before the issuance will commence.

Follow the on screen prompts and at the end of the issuance you will be prompted to enter a FIDO2 PIN and confirm to complete the issuance.

You can now use your credential to authenticate to your Entra ID services.

Enable Logging

If you’re having trouble with Entra, you can enable logging to help diagnose the problem. Follow the instructions below to get started. If the issue persists, you may need to open a support ticket.

On the host where vSEC:CMS is installed, open File Explorer and navigate to the root of the installation folder (typically here: C:\Program Files\Versasec\vSEC_CMS).
Go into the plugins folder. Make a copy of the file named EntraIdPluginDll.cfg and name it EntraIdPluginDll.cfg.BACKUP.
Open the file EntraIdPluginDll.cfg with Notepad (open Notepad as administrator).

Look for the section below

<logging>
  <file>
   <enable>00000000</enable>
   <level>00000005</level>
   <filename>c:\3\EntraIdPluginDll#e#_#p#_#s#.xml</filename>
  </file>
</logging>

Change the value in the enable tag to 1 to enable the logging such that the section now looks like below:

<logging>
  <file>
   <enable>00000001</enable>
   <level>00000005</level>
   <filename>c:\3\EntraIdPluginDll#e#_#p#_#s#.xml</filename>
  </file>
</logging>

The tag <filename> is the location where the log file will be written to. By default the log will be written to a folder named 3 on the root of the c:\ drive. If you wish to write to a different location then change the folder where you wish the logs to be written to, for example, if you wish to write to temp folder then change the location to <filename>c:\temp\EntraIdPluginDll#e#_#p#_#s#.xml</filename>. Note that the folder needs to exist and that the vSEC:CMS application needs to be able to write to the folder.
Save the changes and recreate the issue(s) you are encountering. Check the log to see if the root cause is determinable.
Once you have completed the investigation you should disable the logging. Navigate to the plugins folder and delete the file EntraIdPluginDll.cfg. Rename the file EntraIdPluginDll.cfg.BACKUP to EntraIdPluginDll.cfg.

Search