Introduction
From version 6.3 vSEC:CMS has the ability to manage the life cycle of FIDO2 authenticators. Below is an architectural diagram showing how FIDO2 fits into vSEC:CMS.
Using vSEC:CMS you can register and manage FIDO2 credentials on behalf of a user with an IdP. When a supported FIDO2 credentials is issued with vSEC:CMS, the credential (public key) is sent to the IdP which will use this when authenticating the user post issuance. If the supported FIDO2 credential also has a PKI application then you can leverage on this to issue and manage certificates for other use cases using vSEC:CMS as part of the issuance process.
This article will describe how you can:
- Configure vSEC:CMS to connect to a supported IdP;
- Configure a template to issue a supported FIDO2 credential that can be issued centrally using vSEC:CMS Admin application;
- Configure a template to issue a supported FIDO2 credential that can be issued by an end-user using vSEC:CMS User application.
FIDO credentials typically use HID interface for communicating with the device. If attempting to use/manage the FIDO 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 to.
Configure IdP Connector
The first step will be to setup a connection to your IdP. Currently vSEC:CMS supports Safenet Trusted Access (STA), Okta, Entrust Identity and Gluu IdPs.
In this article we will show how to configure a connection with Okta and Gluu Server IdP. For whatever IdP you have in your environment it is expected that you have access to these services.
Setup Okta Connector
From Options - Connections click Add. Select FIDO2 (IdP) and add it to the Selected pane and click Ok. Enter a name for the template and select OKTA IdP for the Type.
In the Host Parameters section enter the Client ID applicable to your Okta setup. Browse to the location of the Private Key used when authenticating to Okta OAuth API. This key should have been created when setting up your OAuth API in Okta. This private key is encrypted internally by vSEC:CMS with an AES key. Enter the appropriate URLs for the Authentication URL and Api URL in the fields provided.
In the Relying Party section for the Name enter the human-palatable name of the relaying party. The Id should be a valid domain string identifying the WebAuthn relying party on whose behalf a given registration or authentication ceremony is being performed. The Origin should match the endpoint the user is provided to access the signing service, as is the case in a standard WebAuthn service. The Icon URL is an optional field for the URL of the relaying party icon.
When all the configurations are set click the Check Authentication and Check API buttons to ensure connectivity and settings are valid.
Setup Gluu Connector
From Options - Connections click Add. Select FIDO2 (IdP) and add it to the Selected pane and click Ok. Enter a name for the template and select Gluu Server IdP for the Type.
vSEC:CMS will connect to the IdP by establishing an SSH tunnel to the IdP. Enter the host name and port for the SSH tunnel along with the LDAP protocol. Enable SSL/TLS (if this is to be used) and enter the credential that you will use to connect to your IdP. Click the Test Connection button to ensure connectivity.
It is expected that you have setup an SSH tunnel using Putty or similar tool.
In the Relying Party for the Name enter the human-palatable name of the relaying party. The Id should be a valid domain string identifying the WebAuthn relying party on whose behalf a given registration or authentication ceremony is being performed. The Origin should match the endpoint the user is provided to access the signing service, as is the case in a standard WebAuthn service. The Icon is an optional field for the URL of the relaying party icon.
Configure Template
We will break this section into 2 different parts depending on whether you want to issue centrally via the Admin or Agent application as an operator who will issue on behave of (see below Configure Template for Central Issuance) OR if you want the end-user to issue themselves via the self-service application (see below Configure Template for Self-Service Issuance).
Configure Template for Central Issuance
From Templates - Card Templates click Add and select Edit for General. Attach a supported FIDO 2 authenticator and click the Detect button to allow vSEC:CMS to determine that you wish to use this template for managing such an authenticator. You should see the FIDO2 support in the Card type drop-down field. Enable Enable FIDO2 check box and leave all other settings as is and Ok.
Click Edit for Issue Card. Enable Assign user ID and select the user directory you wish to use for the provisioning.
vSEC:CMS will use the user's common name (cn attribute) and email address (mail attribute) when provisioning a user.
In the FIDO2 Options section click the Manage button and then the Add button.
Enter a name and from the IdP Connection select the connector created earlier.
Enable Requires Resident Key if your IdP is configured to support this feature.
Enable Use Default Password or Password defined by Operator and enter a complex password.
These password configurations will only be applicable if a new user is being added to your IdP. If you are issuing a credential to an already existing user in your IdP then vSEC:CMS will not override the user's existing password.
The Password defined by Operator will only be applicable when an operator is issuing on behave of from Admin or Agent application.
Enter the complex password into the Default Password for User field.
The password will be encoded according to RFC 8259, therefore you need to make sure that you provide a password that meets these requirements.
You can configure how the authenticator name will be shown in the IdP (if the IdP supports this), either use default or enter a custom name in the Token Name field.
In the FIDO2 PIN section setting of the FIDO PIN will be automatically set as this is required in order to be able to use the FIDO credential.
The FIDO credential used needs to be in default state, i.e. a PIN cannot already be set. If a PIN is already set then you will be prompted to provide this PIN during the issuance flow.
Click Save to close.
Select the template in the drop-down field and enable the checkbox FIDO2 Enrollment. Click Ok to save the settings for Issue Card.
In the Initiate Card section enable Update Credentials at FIDO2 IdP. This will write the FIDO2 credentials to the IdP when the authenticator is initiated.
In the Activate Card section enable Update Credentials at FIDO2 IdP. This will update the IdP when the authenticator is activated.
In the Inactivate Card section enable Update Credentials at FIDO2 IdP. This will update the IdP when the authenticator is inactivated.
In the Revoke Card section 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 to close and save the template configuration.
Configure Template for Self-Service Issuance
It is required to install the RSDM service on any client where self-service FIDO operations are to be allowed. The RSDM service will allow for administration operations to be performed when issuing a FIDO credential or setting/changing the FIDO PIN.
For self-service template you can use the template configuration above (Configure Template for Central Issuance) and make the additional adjustments (suggestion is to make a clone of the template above).
Edit the template and select Edit for General.
Click the Manage button and Add a template and configure it similar to below and Save.
Enable Self-service using the following template and select the template in the drop-down list.
Click Ok to save the changes.
Click Edit for Issue Card. Select the checkbox Automatically initiate cards after issuance and Issue by user(s) radio button. Click the Configure button in the User ID Options section. Select the AD connection already configured from User ID from drop down list and select Supplied domain credentials from Authenticate user using drop down list. Click Ok to save and close.
Click Ok and save the template updates to complete the changes.
Issue Credential
In this section we will describe how you can issue a FIDO credential both centrally or self-service.
As Microsoft Webauthn library is used for the FIDO2 feature in Windows environments it is required that you perform issuance directly on the PC/laptop and not on a virtualized machine.
Central Issuance
Navigate to the Lifecycle page and with the FIDO 2 authenticator attached click the Issued oval and select the template and Execute. Some dialogs will popup with information you need to ok.
You will be prompted to touch or remove and reinsert the authenticator.
At the end a summary dialog will appear. The authenticator will now be issued.
Next a PIN should be set. Click the Active button and set a PIN.
Self-Service Issuance
From vSEC:CMS User select the Credential tab.
Attach a FIDO2 credential and click Issue. Select the credential template and Issue.
You will be asked to select the user you want to issue the credential to.
You will then be asked to setup the FIDO2 credential and set a PIN.
At the end of the flow you can now use the credential as an authenticator.
For example, using the issued authenticator you could try to log into your Okta IdP. Enter your credential and then you will be prompted to authenticate with your vSEC:CMS managed authenticator.
Then you would be prompted to authenticate using your FIDO2 credential.