Introduction
From version 7.2.2 vSEC:CMS supports the ability to order and ship supported Yubico FIDO2 tokens to end users directly from vSEC:CMS. This guide will describe how you can configure and use this feature in vSEC:CMS.
Add Pre-Reg Connector
Log onto the vSEC:CMS Admin console and navigate to Options - Connections. Click the Add button. Select Credential Order Provider and enter a name for Template name.
Leave the preconfigured URL as is.
Enter the authentication key as generated from your YubiEnterprise web console into the Authentication Key field.
Click the Test button to test that the connection is operational.
Select a key from the Yubico Key drop-down list. These are the available keys from Yubico that will be used to encrypt information sent to the Yubico factory during the ordering communication.
Click the Generate button to generate a Versasec Key that is used by vSEC:CMS to decrypt information sent from the Yubico factory during the ordering communication.
Click Save to close and save the settings.
Create Order
Navigate to Templates - Credential Order. Click Add.
Enter a template name. Select the pre-reg connector already created from the drop-down list.
In the Delivery Type select the appropriate delivery type -
- Normal - this will be cheaper to send the item (compared to expediate option) and delivery timelines will depend on the country where the token(s) are to be shipped to.
- Expediate - this will be more expensive and delivery timelines will be shorter compared to the normal option.
Click Configure for Recipient. Here you configure the contact information about the person who the token is going to be shipped to. This will be used to update the person during the delivery stage.
Click the Fields button. It is recommended to add all fields from Available to Selected and click Ok.
Click in the Value field to configure how the user specific information is retrieved.
The user data would typically be retrieved from a user directory, Entra ID in this case. Therefore it would be typical to map vSEC:CMS variables to Entra ID attributes to retrieve the actual user information. For example, the vSEC:CMS variable ${UserMobile} maps to the Entra ID attribute mobile. This would then be retrieved when required. Additionally, if you have static values for a user field then enable Use free text and enter the value. For details on how to configure mapping vSEC:CMS variables to directory attributes see the guide here.
Perform mapping for all fields and click Ok to save and close.
Click Configure for Mailing Address. Here you configure the shipping address information about the person who the token is going to be shipped to.
Click the Fields button. It is recommended to add all fields from Available to Selected and click Ok.
Click in the Value field to configure how the user specific information is retrieved.
The user data would typically be retrieved from a user directory, Entra ID in this case. Therefore it would be typical to map vSEC:CMS variables to Entra ID attributes to retrieve the actual user information. For example, the vSEC:CMS variable ${EntraCountryCode} maps to the Entra ID attribute usageLocation. This would then be retrieved when required. Additionally, if you have static values for a user field then enable Use free text and enter the value. For details on how to configure mapping vSEC:CMS variables to directory attributes see the guide here.
Perform mapping for all fields and click Ok to save and close.
For Connection select the ... button and select the already configured pre-reg connector.
Click the Add button.
Select the Customization ID which is specific to Yubico. See here for more details.
Select the appropriate Inventory Product ID from the drop-down list.
- 122 Compliance - Plus - Primary
- 124 Compliance - Plus - Primary - Replacement
From Product ID select the supported Yubikey token from the drop-down list.
In the Product Quantity the number of allowed tokens is shown for information purpose. It is only possible to order 1 token per order for a user.
Click Ok to save and close.
Enable Bypass address validation checkbox if you want to skip Yubico performing an address validation before shipping the token. If you do this and the recipient's mailing address is invalid then you will be charged for the shipping even though the token was not successfully delivered to the end user.
Click Save to close and save.
Create Templates
Several steps need to be performed in this section.
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 to set 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. It is recommended to set this to a high value of 7 days as it can take time for the ordered token to be shipped to the end user when the PIN activation takes place.
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 (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.
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.
We will require to have an email data export template in place that will be used to send the FIDO2 PIN that is set on the credential when issued at the Yubico factory. This will be sent by vSEC:CMS when the credential has been marked as delivered to the end user.
An SMTP connection will need to have been setup before completing the data export template. See the guide here and look in the Email section for details.
From Options - Connections - Data Export click the Add button. Enter a name and click the Configure email button. Enter details similar to below and for the FIDO2 PIN use the variable ${UserPin}. Click Ok to save and close.
Click Save to complete.
Navigate to Templates - Credential Template and click Add.
Click the Edit link beside General and enter a name for the template. Click the Detect button and attach a Yubico token that is to be managed from this template and select it from the reader drop down list. You should see something similar to below. Click Ok to close and continue.
Select Enable FIDO2 checkbox and leave all other settings as is. Scroll down to the bottom of the dialog and click Ok to save and close.
Click the Edit link for Issue Credential. In the General section enable Automatically initiate credentials after issuance checkbox.
In the User ID Options section enable Assign user ID and select the Entra ID connection already configured.
Scroll down to the section FIDO2 Options and click the Manage button.
Click the Add button. Enter a name and enable Always Requires User Verification. It is mandatory to enable Set Minimum PIN Length and set a value that you wish to apply. In Passkey(s) to Issue select the Entra ID template already created. Leave all other settings as is and click Save.
Enable FIDO2 Enrollment and select the template from the drop-down list.
Leave all other settings as is and click Ok button at bottom of dialog to save and close.
Click the Edit link for Initiate Credential and click the Configure button. Enable all checkboxes as indicated below. For PIN length enter the length of the FIDO2 PIN. The length should, at minimum, be the same as what you configured in the FIDO2 Options in Issue Credential section above. Click the Characters button and we recommend that you select the options below to ensure users are not set with Ascii characters in their PIN. Click Ok to save and close.
In the Send PINs to section select the email data export template already created and click Add. Click Ok to save and close.
Additionally, enable Update Credentials at FIDO2 IdP.
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.
Submit Order
Navigate to Repository - Credential Order - Orders. Click Add/Clone.
Click the ... button for Credential Order and select the already created order template.
Click the ... button for Credential Template and select the already created credential template.
Click the ... button for User ID and select the user who the order will be submitted on behalf of.
You can click the View Address button to review the end users delivery details.
Leave all other details as is and click Submit.
The order will now be transmitted.
You can review the status of the order by selecting the order and clicking Edit.
Order Received
When the end user receives the order they can immediately start to use the FIDO2 credential. The end user should have received an email with the pre-set FIDO2 PIN. Then they can, for example, log onto Microsoft 365 Copilot and they should be prompted to set a new FIDO2 PIN.
On the vSEC:CMS management side the FIDO2 token will be in the credential repository with its lifecycle fully manageable.