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 management fits into vSEC:CMS.
Using vSEC:CMS you can register and manage FIDO2 credentials on behalf of a user with an IdP. In this document we will focus on using Okta as the 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 Okta support for FIDO2;
- Configure vSEC:CMS to connect to Okta 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.
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 that the device is attached to.
Okta Configuration Steps
We will describe step-by-step on the basic configuration needed for using Okta in order to register a supported FIDO2 token into Okta.
1. From Applications select Create App Integration
2. Select API Services and Next
3. Enter a name for the application and Save
4. From the General tab select Edit
5. Select Public key/Private key, Save keys in Okta and Add key
6. Select Generate new key, PEM and Copy to clipboard. Save the private key to a secure file location. This file will be required later what configuring the vSEC:CMS Okta connector.
Click Done to complete.
7. Click Save
8. Click Save
9. In the Okta API Scopes tab grant consent to the below scopes
And
10. From Security - Authenticators make sure that FIDO2 (WebAuthn) is in list of authenticators.
Configure Okta Connector
Next you need to setup a connection to your Okta IdP.
From vSEC:CMS Admin console navigate to Options - Connections and 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.
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 FIDO2 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 the 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 FIDO2 PIN will be automatically set as this is required in order to be able to use the FIDO2 credential.
The FIDO2 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 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.
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 FIDO2 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 FIDO2 authenticator attached click the Issued oval and select the template and Execute.
Follow the onscreen prompts to complete the issuance.
At the end a summary dialog will appear similar to below. 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.