This article describes the process required to configure IBM Security Verify Access (ISVA) to use the FIDO Alliance Metadata Service (MDS) in FIDO2 device attestation.

The scenario has been tested using ISVA 10.0.6.0. For more information please see: FIDO2 Configuration

FIDO2 Metadata

A metadata statement file describes one or more FIDO2 devices such that they can be used by the relying parties to validate authenticator attestation and prove the genuineness of the device model. A metadata service is a repository from which metadata statements can be downloaded. ISVA allows a relying party to be configured to use both:

• One or more static metadata statement files; and/or
• One or more metadata services.

The FIDO Alliance MDS provides a centralized repository that includes the metadata for a significant number of trusted FIDO2 devices.

The following steps will show how to configure a relying party that uses the FIDO Alliance MDS.

1. Import the required signer certificates

ISVA requires the import of 2 different certificates:

• The certificate that is used to create an SSL connection with the FIDO alliance MDS.
• The certificate that is used to validate the JWS that is returned by the FIDO alliance MDS.

The certificates can be loaded into the same or different keystores. For the purpose of this article the single existing keystore rt_profile_keys will be used.

1. In the ISVA LMI open the SSL Certificates page:

       System —> SSL Certificates

2. Select rt_profile_keys in the list and click:

       Manage —> Edit SSL Certificate Database

3. The first certificate can be loaded directly from FIDO Alliance. 

   1. On the Signer Certificates tab click:

          Manage —> Load

   2. Set the following fields on the dialog:

      Name	Value
      Server	mds.fidoalliance.org
      Port	443
      Certificate Label	fidoalliance

   3. Click the Load button.

4. The second certificate needs to be imported manually. 

   1. In browser go to the page:  https://valid.r3.roots.globalsign.com/

   2. Copy the Base64 encoded certificate from the loaded page. It will look something like:

      -----BEGIN CERTIFICATE-----
      MIIDX …
      …
      WD9f…
      -----END CERTIFICATE-----

   3. Create a new local file jws.crt with the content of the certificate.

   4. Back on the ISVA LMI on the Signer Certificates tab click:

          Manage —> Import

   5. Set the following fields in the dialog:

      Name	Value
      Certificate file	Browse to find and select the local jws.crt file created above.
      Certificate Label	mdsjws

   6. Click the Import button.

   7. Close the dialog and deploy the changes.

2. Create the metadata service

The next step is to create the global configuration for the FIDO Alliance MDS. Once created this can be used in multiple different relying parties.

1. In the ISVA LMI open the FIDO2 Configuration page:

       AAC —> FIDO2 Configuration

2. Select the Metadata link at the top of the page.

3. Click the Add button in the Metadata Services section of the page.

4. The Add Metadata Service dialog contains a number of different properties.

   The 2 properties that are required for this scenario:

   Name	Value	Description
   URL	https://mds3.fidoalliance.org	The location to retrieve the MDS. This property is required.
   SSL Truststore	rt_profile_keys	The keystore that contains the SSL certificate used to connect to the MDS. It is also used as the keystore that contains the certificate used to validate the retrieved JWS but only if the JWS Truststore property has not been set.

   The remaining unused/unchanged properties are:

   Metadata Service Properties: Properties specific to the MDS usage

   Name	Value	Description
   Retry Interval	3600 (seconds)	The metadata statement retrieved from the MDS has an expiration time. Once this is reached any subsequent device attestations will attempt to retrieve a new version of the metadata. This interval is used if there is a failure in the retrieval. If a failure happens the current metadata will be used and further attestation requests will not attempt to retrieve a new version until the retry interval has been reached.
   JWS Truststore		The keystore that contains the certificate used to validate the JWS retrieved from the MDS. If not specified, the SSL Truststore will be used instead.

   Request Overrides: Properties that will override the global HTTPClientV2 settings when making a HTTP request to the configured MDS. If not specified the global HTTPClientV2 settings are used.

   Name	Value	Description
   Protocol		The SSL protocol used for the HTTP connection.
   Timeout	5 (seconds)	The request timeout.
   Username		The basic authentication username.
   Password		The basic authentication password.
   SSL Keystore		The client authentication keystore.
   Certificate Label		The client authentication key alias.
   Proxy		The URL for a proxy server through which to make the connection.
   HTTP Request Headers		Any required HTTP headers.

5. Once the URL and SSL Truststore fields have been set click the Save button.

6. Deploy the changes.

Note: This LMI page also included the Static Metadata. This is where we could import additional metadata statements that exist locally.

3. Create the Relying Party

The final step is to create the relying party with reference to the new MDS.

1. In the ISVA LMI go to the page at:

       AAC —> FIDO2 Configuration

2. In the Relying Parties page click the Add Relying Party button.

3. On the Name tab set the properties:

   Name	Value
   Display Name	test
   Relying Party ID	www.test.ibm.com
   Configuration ID	Leave as is.
   Advanced Configuration	Select this radio button to show advanced options.

4. Traverse to the Metadata tab.

   This tab contains the metadata configuration that is specific to this relying party. For this scenario select the checkbox in the Metadata Services list for the https://mds3.fidoalliance.org entry.

   The remaining unused/unchanged properties on this page:

   • Enable metadata enforcement: If this field is selected, any device registrations must be validated correctly against the configured metadata. If the validation fails the device cannot be registered.

   • Prefer metadata service over static metadata The configured metadata for a relying party can include:

     • One or more static metadata statement files; and/or

     • One or more metadata services.

     The ordering of the artifacts is important. Attestation validation will step through the metadata until a match is found. This entry will be used in the validation. Ordering is set on both:

     • Multiple static metadata entries; and

     • Multiple metadata services.

     This property sets the additional ordering of whether to check static metadata of metadata services first.

5. Traverse to the Summary tab.

   Ensure that the summary includes the required metadata service and click the Save button.

6. Deploy the changes.

4. Try it out

Now that the relying party configuration has been completed we can test it to ensure that the MDS is working as expected.

There is an assumption that a reverse proxy instance exists with a junction to the runtime server but if there isn’t:

1. Create a reverse proxy instance.

2. On that reverse proxy instance run the Authentication and Context Based Access Configuration wizard in:

   Manage —> AAC and Federation Configuration

Test the configuration

1. Access the device selection page:

   https://www.test.ibm.com/mga/sps/mga/user/mgmt/html/device/device_selection.html
   

   Note: The host in the URL must match the relying party ID created above.

2. Click the Register new authenticator button in the FIDO2/WebAuthn Registrations section.

3. Follow the process to register a device listed in the FIDO Alliance metadata. This test will use the YubiKey 5 Series with NFC.

4. Upon successful registration that device selection page will show the new registration.

   

   • Note the information shown in the Brand field. This has been extracted from the FIDO Alliance metadata and shows that the MDS is working as expected. If the device was not listed in the metadata this field would be empty.

   • The Test button on this page allows the device authentication flow to be tested.

   • If we had checked the Enable metadata enforcement property when creating the relying party and the device was not listed in the FIDO alliance metadata, it would fail registration.

Congratulations, you have successfully registered and tested a device using the FIDO Alliance metadata service for attestation validation.

5. Troubleshooting

If the scenario did not complete as expected, the best option is to enable tracing to see what went wrong.

1. In the ISVA LMI open the page:

   AAC —> Runtime Parameters —> Runtime Tracing
   

2. Set the trace specification:

   com.tivoli.am.fim.fido.config.*=ALL:com.ibm.iam.isfs.v2.*=ALL:com.ibm.security.access.httpclient.*=ALL

   This will show all of the tracing for the FIDO component and also the HTTPClientV2 that is used to make the call to the MDS.

3. Deploy the changes

4. Try the registration again.

5. View the trace file

   Monitor —> Application Log Files —> access_control —> runtime —> trace.log

6. Look at the trace for any errors or issues in the FIDOConfig or HttpClientV2 trace entries. There should be a lot of entries like:

   addMetadata Adding metadata { AAGUID: [D91C5288-0EF0-49B7-B8AE-21CA0AA6B3F3], Description: [KEY-ID FIDO2 Authenticator], KeyIds: [[]], source: FIDO2], attestationTypes: [[Basic]}