Skip to main content

FIDO2 (Passkey) Registration

Before a user can authenticate with a passkey, a FIDO2 credential has to be registered: a public/private key pair is created on the user's authenticator, and the public key is stored against the user in nevisIDM.

This page assumes that a nevisFIDO FIDO2 Instance is already deployed, with Relying Party ID and Relying Party Origins configured for your domain. It also assumes the user has already authenticated some other way, since registering a passkey requires an existing session to attach the credential to.

Registering a passkey with nevisAuth​

Add a FIDO2 Onboarding pattern as an authentication step and fill in its fields:

  • nevisFIDO FIDO2: assign the nevisFIDO FIDO2 Instance pattern that provides the FIDO2 services.
  • User Name: choose whether nevisFIDO looks the user up by extId or loginId. This must match the User Name setting on the nevisFIDO FIDO2 Instance pattern; nevisAdmin 4 rejects the configuration otherwise.
  • On Success: the step to continue with once the passkey is registered.
  • On Unsupported: the step to continue with if the user's browser does not support WebAuthn.
  • On Cancel: optional, assign a step to let the user skip registration for now.
  • Authenticator Type: restrict to platform (built-in authenticators such as Face ID or Windows Hello) or cross-platform (roaming security keys), or leave any to accept both.
  • Resident Key: set to required if the credential must be discoverable, which is a prerequisite for Usernameless Authentication. Leave unspecified if you only need a regular second factor.
  • User Verification: unspecified, preferred or required, defaulting to unspecified.
  • Attestation: none, indirect or direct. Set direct only if you plan to restrict authenticators by metadata; see Authenticator Allow-listing.

This step is typically assigned as the follow-up of Not Found in a nevisIDM Second-Factor Selection pattern, so that a user without a passkey is routed straight into onboarding.

Reference guide correction pending

The Pattern Reference Guide currently lists discouraged, preferred and required for User Verification on this pattern. That is a documentation defect in the generated reference (tracked as PAT-1178): the values above are verified directly against the nevisAdmin4-plugins source and are what the pattern actually accepts.

One typical use of Registration is where nevisAuth is the relying party

This page covers registering a passkey through nevisAuth with the FIDO2 Onboarding pattern. If your relying party is a custom web application that talks to nevisFIDO directly, see Registration with Web Application instead; that path does not use nevisAdmin 4 authentication step patterns.

Testing registration with the FIDO2 Management Demo pattern​

To try passkey registration before you have built a production relying party, add a FIDO2 Management Demo pattern. It serves a small page with a bare-bones FIDO2/WebAuthn JavaScript client.

Demo and testing only

FIDO2 Management Demo is explicitly not for production use. It only works when extId is the configured username, and it requires the nevisFIDO FIDO2 Instance to be exposed on the same virtual host via a nevisFIDO FIDO2 REST Service pattern. Build your own registration page for production, adapted to your integration.

What registration creates​

Successful registration creates a FIDO2 Authenticator credential for the user in nevisIDM, holding the public key of the authenticator that was used. The nevisIDM unit policy must allow this credential type, or credential creation fails even though the WebAuthn ceremony itself succeeds.

To learn how the ceremony works at the protocol level, and for a JavaScript client to adapt, see Registration with nevisAuth.

Next steps​