Introduction
From version 6.12 it is possible to manage the lifecycle of FIDO2 Enterprise credentials. In this article we will describe how you can configure and manage such credentials using vSEC:CMS. We will describe this in a generic form and use simple use cases for this.
There will be 2 use cases in this article where an end user resides in Entra ID:
- The credential will be issued on-behalf of the user centrally by a vSEC:CMS operator using the vSE:CMS Agent application;
- The credential will be issued by the end user themselves using the vSEC:CMS User application.
Prerequisites
We will use Microsoft Entra ID in this article as the IdP. Therefore you will need to have already setup connectors for this.
Additionally, the credential that is to be used will need to be added to your existing repository of supported credentials if it is not already added.
Please refer to the articles below for details on how to configure these connectors for your environment and add credential to your system:
- Connector for Entra ID see here;
- Connector for Entra ID FIDO2 (IdP) see here;
- Connector for Entra ID OAuth Identity Provider (IdP) see here;
- Add credential support see here.
Configure Template for Central Issuance
As an operator who has a role that allows them to configure templates open the Admin console. Navigate to Templates - Card Templates and click Add.
Click the Edit link beside General. Enter a name for the template and click Detect button. Make sure to attach the credential that is to be managed by this template and select the correct reader, if more than one credential is attached to your system, and click Ok.
If the credential is one that has support for FIDO2 Enterprise then you will see 2 checkboxes - Enable FIDO2 and Enable FIDO2 Enterprise both of which should be enabled.
Leave all other settings as is and click Ok at the bottom of the dialog to save and close the settings.
Click the Edit link beside Issue Card. In the User ID Options section enable the check box Assign user ID and select the Entra ID template that would have been configured as per the prerequisites as mentioned above.
Scroll down the dialog and in the FIDO2 Options section click the Manage button for FIDO2 Enrollment. Click Add. Enter a name for the template and select the Entra ID FIDO2 (IdP) template (this would have been configured as per the prerequisites as mentioned above) from the Select IdP drop down list. Leave all other settings as is and Save to save and close out.
Enable FIDO2 Enrollment check box and select the template just created from the drop down list.
Click the Manage button beside FIDO2 Enterprise. Click Add. Enter a name for the template. Select Type from the available list of support credentials. Below is the configuration that will be available if you are using Thales FIDO2 Enterprise credential.
From FIDO2 Reset by User you can configure whether the user is allowed to reset the FIDO2 credential or not. If you enable Not Blocked then it will be possible to reset the FIDO2 credential using third party tools. If you enable Blocked then it will not be possible for the end user to reset the FIDO2 credential using 3rd party tools.
If the IDP that you are using supports Always Require User Verification (this feature is from the CTAP 2.1 specification) then enable this check box which will required the user to always provide their FIOD2 PIN or fingerprint when authenticating.
In the RP ID Allow List enter the IDPs that the token can be registered with. This list should be the same value used for the ID and Name when configuring the connector from Options - Connections - FIDO2 (IdP).
Enable Set Minimum PIN Length (this feature is from the CTAP 2.1 specification) and set a value that will be applied, then when setting a FIDO2 PIN this enforcement will be applied.
The Minimum PIN Len RP ID List is an implementation of the CTAP 2.1 specification for Minimum PIN Length Extension. If the IDP(s) that you are using support this enter them here. This list should be the same value used for the ID and Name when configuring the connector from Options - Connections - FIDO2 (IdP). An example use case for this extension is where an organization supplies configured tokens to their users, with a current minimum PIN length value tailored to the organization’s requirements. Upon users registering their credentials with the organization’s systems using the token, the organization may use this extension to determine whether the current minimum PIN length continues to meet the organization’s requirements.
Enable FIDO2 Enterprise check box and select the template just created from the drop down list.
Leave all other settings as is and click Ok at the bottom of the dialog to save and close the settings.
Click the Edit link for Initiate Card and enable Update Credentials at FIDO2 IdP. This will push the public key credential for the user to Entra ID when setting the FIDO2 PIN on the credential.
Click the Edit link for Activate Card and enable Update Credentials at FIDO2 IdP and click Ok.
Click the Edit link for Revoke Card 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 remove the authenticator at the IdP when the credential is revoked.
Click Ok so save and close the configuration for the template.
Issue FIDO2 Enterprise Credential
The FIDO2 Enterprise credential can be issued either using the vSEC:CMS Admin or Agent applications (recommend that the Agent application is used). 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 FIDO2 Enterprise 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 Entra ID 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 Enterprise PIN that can then be used by the end used.
Alternatively, the end user can set the FIDO2 Enterprise 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 - Smart Cards 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 FIDO2 Enterprise credential is revoked on the IdP by trying to log in with the hardware credential.
Configure 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 FIDO2 Enterprise credential in its 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 Configure Template for Central Issuance above and make a clone so it can be used for self-service issuance operations.
Select the existing template we created in the section Configure Template for Central Issuance above from Templates - Card Templates and click Clone. Edit the cloned template and navigate to the General section. Change the name to a more appropriate name. Click the Manage button in the Self-service using the following template section.
Click Add. Enter a template name. Enable Self-issuance enabled check box. Select the OAuth configured, as described in the Prerequisite section above (OAuth Identity Provider (IdP)), from the drop down list for User Authentication for PIN Unblock. Enable User can choose smartcard challenge/response check box. Leave all other settings as is 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 the changes made in the General section.
Select Edit in the Issue Card section.
Enable Automatically initiate cards 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.
Unblock FIDO2 Enterprise Credential PIN
The FIDO2 Enterprise credentials have a management key which vSEC:CMS manage. With this capability it means it is possible to perform FIDO2 PIN unblocks. This can be done centrally or via self-service.
Central FIDO2 PIN Unblock
When a user blocks or forgets their FIDO2 PIN they can go and visit a helpdesk operator who has permissions to perform such an operation. From the Agent application navigate to the Unblock User Credential tab and attach the credential. Select the FIDO2 PIN from PIN drop down list and have the user enter a new PIN and confirm. Click the Unblock to complete the PIN reset.
Self-Service FIDO2 PIN Unblock
There are 2 ways in which an end user can perform FIDO2 PIN reset.
Online
When the user is logged onto a client which is connected to the backend vSEC:CMS service and the template that was used to issue the credential is configured for online FIDO2 PIN reset then they can perform FIDO2 PIN resets.
Open the vSEC:CMS User application and navigate to the PIN tab. Select Unblock PIN (Crypto) and attach the credential. Select the credential from the reader list and FIDO2 PIN from the drop down list. The user can then enter a new PIN and confirm. Click the Unblock button to start the reset. The user will need to authenticate to complete the reset, for example the user could authenticate with their Entra ID OAuth credential.
Offline
When a user is not connected to the backend vSEC:CMS service then an offline FIDO2 PIN reset can be performed. In this case the user would need to interact with a helpdesk person who has permissions to perform this operation.
Open the vSEC:CMS User application and navigate to the PIN tab. Select Unblock PIN (Crypto) and attach the credential. Select the credential from the reader list and FIDO2 PIN from the drop down list. Click the Get button to generate a challenge code. This code needs to be provided to the helpdesk person. It is important that the credential is not removed until the entire process is completed as there is a one-to-one relationship between the generated challenge and the cryptogram that is returned by the helpdesk person.
The helpdesk person opens the Agent application and navigates to the Unblock User Credential tab and clicks the Search button to retrieve the user who is attempting the FIDO2 PIN reset. Enter the challenge into the field and click Cryptogram button to generate the unblock code and provide this back to the end user.
The end user enters the cryptogram provided and enters a new and confirm FIDO2 PIN and clicks Unblock button to complete the reset. The 4 digit values at the end of the challenge and cryptogram are checksums to validate that the correct values have been exchanged during the process.