Skip to main content
Version: 2.3.x.x RR

Registration

Description​

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.

Prerequisites​

  • 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.

Example​

  1. The user performs an initial login using legacy authentication with existing credentials.
  2. The login is executed against the Nevis backend and the user is authenticated.
  3. The user starts the FIDO2 registration.
  4. The client JavaScript starts the FIDO2 registration ceremony by contacting the Nevis backend.
  5. The backend responds with information the client JavaScript uses to call the WebAuthn API in the browser.
  6. The browser prompts the user, who uses a FIDO2 capable authenticator to register the credentials via the WebAuthn API.
  7. The client JavaScript sends the result of the registration - containing the public key - to the backend.
  8. The backend stores the FIDO2 credential and replies back the result to the client JavaScript.
  9. The client JavaScript informs the user regarding the successful registration.
FIDO2 Registration

Technical Flow​

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.

note

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.

  1. The user initiates the FIDO2 registration.

  2. The ScriptState returns a GuiDescriptor configuring the nevisLogRend template to include the JS client.

  3. The JS client submits an empty form POST to get the ServerPublicKeyCredentialCreationOptionsResponse. In this example implementation the ServerPublicKeyCredentialCreationOptionsRequest is generated by the Groovy ScriptSate.

  4. The ServerPublicKeyCredentialCreationOptionsRequest is created by ScriptState and calls the nevisFIDO Options endpoint.

    Endpoint: https://<nevisFIDO-host>:<nevisFIDO-port>/nevisfido/fido2/attestation/options

    References:

  5. nevisFIDO queries the FIDO2 credentials from nevisIdm.

  6. Challenge is generated and the ServerPublicKeyCredentialCreationOptionsResponse is built.

  7. A direct response is prepared using the ServerPublicKeyCredentialCreationOptionsResponse.

  8. JS client receives the ServerPublicKeyCredentialCreationOptionsResponse.

  9. JS client initiates a registration using the received Options response via the WebAuthn API.

  10. Dialog presented to the user by the browser to confirm the credential creation.

  11. The user approves the credential creation

  12. The WebAuthn API generates the keys and returns an attestation to the JS client.

  13. JS client submits attestation to the backend.

  14. The ScriptState in nevisAuth assembles a ServerPublicKeyCredentialForRegistration JSON payload from the form submit and calls the nevisFIDO REST API.

    Endpoint: https://<nevisFIDO-host>:<nevisFIDO-port>/nevisfido/fido2/attestation/result

    References:

  15. nevisFIDO session lookup. (This session is independent of the nevisAuth session)

  16. Incoming request validated according to the WebAuthn specification.

  17. nevisFIDO stores the FIDO2 credential in nevisIDM, such that it is related to the username.

  18. FIDO2 session is updated to reflect the current status.

  19. ServerResponse is returned stating the status of the FIDO2 authentication. At this point the FIDO2 registration is completed.

  20. ScriptState transitions to ok.

Last updated on