Create a FIDO Relying Party for WebAuthn

Introduction

In this guide you will learn how to create a FIDO2 Relying Party definition for use with the WebAuthn browser API. A Relying Party definition is required for each web site (top-level DNS domain) where you want users to be able to register and authenticate with FIDO2 authenticators.

👍

Pre-defined Relying Party

An IBM Security Verify tenant comes with a pre-defined FIDO2 Relying Party definition which covers the DNS domain of the tenant itself. This enables FIDO2 authentication for the tenant web interfaces and any application integrated via browser single sign-on.

Additional Relying Party definitions are needed to allow custom web applications integrated with IBM Security Verify to support direct registration and authentication with FIDO2-based authenticators using WebAuthn.

Pre-requisites

There are no pre-requisites to creating a FIDO2 Relying Party definition.

Gathering Information

The following will be needed in order to complete this guide:

🚧

localhost cannot be used

You cannot use localhost as the DNS domain for the FIDO2 Relying Party. If you are setting up a test application, you can use a local hosts file to map a fake qualified host name to your test system.

Navigate to FIDO2 Settings

In the Admin UI, navigate to the Security page and select the FIDO2 tab.
Select the Relying Parties + button.

Define Relying Party

Display Name

This is a human-readable name used for administration and reporting only.

Relying party identifier

The Relying party identifier must be a DNS domain which covers all origins where FIDO2 will be used on the site covered by this definition. Usually it will be the site DNS domain (e.g. example.com) but can be a sub-domain (e.g. sales.example.com) if you want to limit the scope of the Relying Party.

Devices

If you have loaded metadata, this is where you can specify which metadata files are valid for this Relying Party. Usually you will use the Include all device metadata option rather than impose restrictions on which authenticator types can be registered.

Device criteria

If you have loaded metadata, you can enforce the validation of device attestation certificates against the metadata files you have enabled in this definition. Use this option to limit the authenticator types that can be used.

Allowed origins

For WebAuthn, these are the base URLs where FIDO2-based authenticators can be registered and used. The scheme must be https. Each origin URL must fall within the DNS domain set as the Relying Party identifier. The port must be included if not 443.

📘

Relying party identifier and Origins

For more information on the requirements for, and relationship between, the Relying Party identifier and origins, please check out https://www.w3.org/TR/webauthn.

For each origin, enter the URL and select the Add button. Added origins show in the URL list.

When you are done, select Save.