-
Notifications
You must be signed in to change notification settings - Fork 0
6. The WebAuthN Ceremonies
Authentication with the Web Authentication API (WebAuthN) is achieved by proving ownership of a private key - watch the video linked on the main page for more information, and read below to see how it is implemented in dotnetflix.
WebAuthN is part of two key components that make up the FIDO2 standard (the other one is the Client to Authenticator Protocol, or CTAP; more on this below). FIDO2 allows you to securely log in to a web site or app using an authenticator instead of a password. 'Authenticator' in this context means a FIDO2 authenticator, such as a Yubikey (known as a roaming authenticator) or a security chip in your device, usually combined with a biometric sensor (known as a platform authenticator), as opposed to an OTP authenticator app.
WebAuthN is made up of two ceremonies: attestation and assertion. Attestation is the process of registering an authenticator for passwordless authentication. Assertion is the process of authenticating with that authenticator.
Attestation is used to register for WebAuthN authentication. During attestation, the authenticator generates a new public-private key pair and provides an attestation statement to the server. The core part of this statement is the public key, which is registered on behalf of the user and can be used later to authenticate the user, by proving ownership of the corresponding private key.
The registration ceremony is comprised of two calls from the browser to the Relying Party (RP), in this case IdentityServer.
ℹ️ NOTE: In OIDC the term 'Relying Party' refers to the client application, while Authority or Identity Provider (IDP) refers to the authorising server. In WebAuthN, the RP is the authorising server.
The first call requests options from the RP that will define how the attestation is constructed. This can include certain parameters that can be unique to each application, but most importantly includes a "challenge". A challenge is a randomly generated cryptographic block that is used to identify the specific interaction and prevent replay and pre-play attacks (for more details on this process, there's an interesting discussion in an issue on the W3 docs repo on this topic).
The second call actually makes the attestation. It sends a registration request to the RP that includes the original challenge, signed by a private key, and includes the corresponding public key. The RP can verify that the attestation it has received has been signed by the private key that corresponds to the public key it has received. These are then stored for use in the assertion ceremony.
The server-side implementation of the Registration ceremony in WebAuthn is accomplished through the RegistrationController class. The class depends on [[the IFidoCredentialStore|5.-The-FIDO-Credential-Store]] and IFido2 instances in the constructor. The IFidoCredentialStore defines methods that provide access to the FIDO2 entities in the database, and IFido2 provides access to the cryptographic methods that support the WebAuthN ceremonies provided by the Fido2.Net library.
The methods in this controller are minimally adapted from the DemoController in the example provided in the Fido2.Net library (updated to use the IFidoCredentialStore and derived entities instead of the in-memory store and base classes).
The MakeCredentialOptions method prepares a set of options required for the navigator's credentials.create() method and stores these options in the session for later verification. It retrieves the user and the user's existing keys, constructs AuthenticatorSelection and AuthenticationExtensionsClientInputs objects based on the input parameters, and finally, calls RequestNewCredential on the _fido2 object to generate credential creation options.
The MakeCredential method handles the response from the credentials.create() method. It retrieves the options and user from the session, constructs an AuthenticatorAttestationRawResponse object from the received attestation response, and uses the _fido2.MakeNewCredentialAsync method to create and verify the credentials. Once verified, the credentials are added to the user in the credential store.
The CreateCallback method is a helper function that ensures the uniqueness of the credential ID for the user.
The AttestationResponse and related classes at the bottom of the controller represent the response structure from the navigator.credentials.create() method, allowing the FIDO2 library to properly deserialize and process the data. The response includes the credential ID, type, raw response, and possible extensions.
In the event of an error during either method, an appropriate error response is returned to the client.
The assertion ceremony occurs during user authentication and serves as the main activity of proving a user's identity (more specifically, proving ownership of the private key that corresponds to the public key registered during attestation). The authenticator signs a challenge from the server using its private key, and the server, using the public key stored during the attestation, verifies the signature. Successful validation of this signature asserts the user's identity, providing a secure and passwordless authentication experience.