Before a user can authenticate with the FIDO2 protocol, FIDO2 credentials must be created and stored both on the user's device and on the FIDO2 Server. This ceremony is called Registration.
- The user's device and browser must support FIDO2.
- The user already has existing credentials (a password, for instance) that can be used to authenticate, which is referred to as legacy authentication.
- Nevis is configured in such a way that only authenticated clients can register FIDO2 credentials.
- The user successfully executes a legacy authentication before starting the registration flow.
- The user performs an initial login using legacy authentication with existing credentials.
- The login is executed against the Nevis backend and the user is authenticated.
- The user starts the FIDO2 registration.
- The browser prompts the user, who uses a FIDO2 capable authenticator to register the credentials via the WebAuthn API.
The initial authentication depends on the custom integration as well as the existing means of authentication the end user possesses. Thus, the initial authentication steps are not explained in detail but only referenced.
The technical flow in the following figure explains the component interaction in detail. The step numbers in the next figure do not correlate with the simplified example above.
The following flow is a simple compact example. Depending on requirements, changes or different approaches might be required. The key fix points are:
- WebAuthn API in the browser.
- FIDO2 HTTP API in nevisFIDO.
- nevisAuth must be aware of the status of the FIDO2 registration.
The user initiates the FIDO2 registration.
The ScriptState returns a GuiDescriptor configuring the nevisLogRend template to include the JS client.
The JS client submits an empty form POST to get the
ServerPublicKeyCredentialCreationOptionsResponse. In this example implementation the
ServerPublicKeyCredentialCreationOptionsRequestis generated by the Groovy ScriptSate.
ServerPublicKeyCredentialCreationOptionsRequestis created by
ScriptStateand calls the nevisFIDO Options endpoint.
nevisFIDO queries the FIDO2 credentials from nevisIdm.
Challenge is generated and the
A direct response is prepared using the
JS client receives the
JS client initiates a registration using the received Options response via the WebAuthn API.
Dialog presented to the user by the browser to confirm the credential creation.
The user approves the credential creation
The WebAuthn API generates the keys and returns an attestation to the JS client.
JS client submits attestation to the backend.
ScriptStatein nevisAuth assembles a
ServerPublicKeyCredentialForRegistrationJSON payload from the form submit and calls the nevisFIDO REST API.
nevisFIDO session lookup. (This session is independent of the nevisAuth session)
Incoming request validated according to the WebAuthn specification.
nevisFIDO stores the FIDO2 credential in nevisIDM, such that it is related to the username.
FIDO2 session is updated to reflect the current status.
ServerResponse is returned stating the status of the FIDO2 authentication. At this point the FIDO2 registration is completed.