WebAuthn4J Reference

All attestation statement formats are supported:

All mandatory test cases and optional Android Key attestation test cases of FIDO2 Test Tools provided by FIDO Alliance are passed.

WebAuthn4J only depends on SLF4J and Jackson, offering very high portability. There should be almost no barriers to introducing webauthn4j into your Java application.

In short, WebAuthn authentication is a public key-based authentication method designed for web applications.

First, a key pair is generated, with the public key stored on the server and the private key kept on the authenticator. At the time of authentication, the authenticator uses the private key to generate a signature, which is sent to the server to be verified with the public key, confirming the user’s identity.

The signed data comprises from the client data and the authenticator data. The client data contains not only the domain (origin) of the displayed site, but also the server-related information like a challenge generated beforehand by the server. The server not only verifies the signature but also confirms the challenge, helping to prevent replay attacks. Various other data and are also included in the signed client data and authenticator data, and the server verifies these as well. The data flow during authentication is illustrated in the diagram below.

In the WebAuthn new credential registration process, the client asks the authenticator to generate a new key pair, and the public key and other data returned by the authenticator are registered on the server as credentials. Interestingly, the new credential registration follows a flow similar to authentication: the authenticator first signs the client data, including the challenge from the server and the authenticator data, then returns it. The server receives this via the client, verifies the signature, and, if successful, registers it as a credential record. For registration, however, the signed authenticator data also includes the newly generated public key, which is saved on the server and later used for signature verification in the authentication process.

The data flow during registration is illustrated in the diagram below.

As explained in the previous section, during authentication, the signature is created with the credential’s private key and verified with the credential’s public key. But then, what private key is used to sign the authenticator data and client data during the registration of the credential’s public key? And how does the server obtain the public key necessary for this signature verification? Typically, this private key is a unique key specific to each model of the authenticator and is embedded in the authenticator in advance. As for the public key used in verification, it can either be preconfigured on the server for trusted authenticator or obtained from a registry, such as the FIDO Metadata Service, which provides public keys for each authenticator model.

In this way, WebAuthn has a mechanism called "Attestation" that verifies that the authenticator being registered is of a specific model by signing the credential public key registration message with a model-specific private key. This data structure containing attestation information is called the "Attestation Statement". However, because the attestation statement reveals the model of the user’s authenticator, it could potentially be used for user tracking.

Therefore, in the default configuration, even if the authenticator returns an attestation statement, the client discards it and does not send it to the server. The attestation statement is only disclosed if explicitly specified as an option and with the end user’s consent.

When calling the navigator.credentials.create method, various options can be specified. One of these options is challenge. As mentioned earlier, the challenge is a parameter used to prevent replay attacks; it should be generated by the server, passed as a parameter, and also saved in a session or similar storage. According to the registration flow diagram, the backend server first generates the challenge, saves it in a session, and then sends it to the client. The WebAuthn specification does not define a specific method for passing the challenge from the backend server to the frontend. You could embed it in an HTML page or set up a REST endpoint to return the challenge. Another good idea is to create an endpoint that returns the entire PublicKeyCredentialCreationOptions, a parameter for navigator.credentials.create. The WebAuthn JavaScript API provides a method called PublicKeyCredential.parseCreationOptionsFromJSON, which can parse a serialized JSON PublicKeyCredentialCreationOptions. WebAuthn4J offers a Java class representing PublicKeyCredentialCreationOptions, which can be useful for assembling JSON on the backend server.

In any case, generate the challenge on the backend server, store it in the session, and pass it to the frontend by some means. Then, in the frontend JavaScript, call the navigator.credentials.create method with it to generate the WebAuthn credential. For more information on the other options available for the navigator.credentials.create method, please refer MDN: CredentialsContainer: create() method.

The generated WebAuthn credential must be sent to the backend server in some way. The WebAuthn specification does not define the format in which it should be sent to the server. However, the JavaScript type PublicKeyCredential, representing a WebAuthn credential, has a toJSON method. Using this method along with JSON.stringify to serialize the data is considered a best practice for transmission.

The backend server needs to verify the received WebAuthn credential and then persist the WebAuthn credential record, which includes the public key. With WebAuthn4J, you can directly verify the JSON representation of PublicKeyCredential using the WebAuthnManager#verifyRegistrationResponseJSON method. The WebAuthnManager#parseRegistrationResponseJSON method only performs deserialization of PublicKeyCredential without verification. If you want to access the parsed data when an error occurs during verification, parse it with WebAuthnManager#parseRegistrationResponseJSON to obtain an instance of RegistrationData, then pass it to the WebAuthnManager#verify method for verification.

RegistrationParameters is another argument of the WebAuthnManager#verifyRegistrationResponseJSON method, containing parameters that encapsulate the server state and verification conditions.

The server state is encapsulated in serverProperty. When calling the ServerProperty constructor, specify the following values as parameters:

If verification succeeds, create a CredentialRecord instance from the returned values and persist it in a database or similar storage for authentication. For more information on persistence methods, see CredentialRecord serialization and deserialization. If verification fails, a subclass of VerificationException will be thrown.

The primary API used during WebAuthn authentication is the browser’s navigator.credentials.get method. As illustrated in the authentication flow diagram, first the backend server needs to generate a challenge, save it in a session, and pass it to the client. This is necessary because the navigator.credentials.get method requires a challenge parameter. The WebAuthn specification does not define a specific method for transferring the challenge from the backend server to the frontend (client) for authentication. Just as with the registration process, feel free to use any preferred method to pass the challenge to the frontend. The JavaScript API for parsing PublicKeyCredentialGetOptions, a parameter of navigator.credentials.get, is PublicKeyCredential.parseCreationGetOptionsFromJSON. For additional options that can be specified for the navigator.credentials.get method, please refer MDN: CredentialsContainer: get() method.

navigator.credentials.get

The assertion generated by the navigator.credentials.get method needs to be sent to the backend server for verification. As with the registration, it can be serialized using the toJSON method.

With WebAuthn4J, you can verify the JSON representation of PublicKeyCredential using the WebAuthnManager#verifyAuthenticationResponseJSON method. If you wish to perform parsing and verification as two separate steps, use the WebAuthnManager#parseAuthenticationResponseJSON and WebAuthnManager#verify methods.

The AuthenticationParameters, which is another argument of the WebAuthnManager#verifyAuthenticationResponseJSON method, is a parameter that encapsulates the server’s state and verification conditions.

If verification succeeds, the authentication is considered successful, and the counter, uvInitialized, and backedUp values linked to the persisted CredentialRecord should be updated. The counter is used to detect cloning of the authenticator. For details on counters, see the counter section of the WebAuthn specification. Then, complete any necessary steps for successful user authentication, such as creating an authenticated session.

If verification fails, a subclass of VerificationException will be thrown.

Apple App Attest validators are contained in the dedicated webauthn4j-appattest module. If you are using maven, add the webauthn4j-appattest as a dependency in this way:

To verify an attestation on authenticator registration, call DeviceCheckManager#verify with a DCAttestationRequest instance as an argument. If you would like to access the parsed data when an validation error occurred, please use DeviceCheckManager#parse to parse the attestation request and pass the returned DCAttestationData instance to DeviceCheckManager#verify method.

The members of DCAttestationRequest are the values obtained by the Apple App Attest API in the iOS device Transmit from the iOS device to the server side in some way.

DCAttestationParameters is an another argument for DeviceCheckManager#parse method, and contains server property and validation conditions.

DCServerProperty has following members.

If validation fails, an exception inheriting VerificationException is thrown. If validation succeeds, please create an DCAppleDevice instance from the returned value and persist it to the database or something in your application manner. The instance is required at the time of authentication.

To parse and verify an assertion on authentication, call DeviceCheckManager#verify with a DCAssertionRequest instance as an argument. If you would like to access the parsed data when an validation error occurred, please use DeviceCheckManager#parse to parse the authentication request and pass the returned DCAssertionData instance to DeviceCheckManager#verify method.

The members of DCAssertionRequest are the values obtained by the App Attest API in the iOS device. Transmit from the iOS device to the server side in some way.

DCAssertionParameters is an another argument for DeviceCheckManager#parse method, and contains server property, persisted authenticator and validation conditions.

Attestation statement trustworthiness verification has two patterns: certificate path verification, and self attestation. Certificate path verification is delegated via CertPathTrustworthinessVerifier interface. WebAuthn4J provides DefaultCertPathTrustworthinessVerifier as CertPathTrustworthinessVerifier implementation. DefaultCertPathTrustworthinessVerifier verifies trustworthiness by checking the attestation certificate chains to the root certificate provided as TrustAnchor via TrustAnchorRepository interface.

TrustAnchorRepository is an interface that resolves TrustAnchor from AAGUID or attestationCertificateKeyIdentifier. webauthn4j-core module provides a KeyStoreTrustAnchorRepository as a TrustAnchorRepository. KeyStoreTrustAnchorRepository fetches TrustAnchor from a Java Key Store. Please note that KeyStoreTrustAnchorRepository does not return a different TrustAnchor depending on AAGUID or attestationCertificateKeyIdentifier. All certificates registered in the Java Key Store file are treated as trust anchors.

AttestedCredentialDataConverter converts from AttestedCredentialData to byte[] and vice versa. If you would like to persist as String, use Base64UrlUtil to convert from byte[] to base64url String.

Since AttestationStatement is an interface, there are some implementation classes like PackedAttestationStatement or AndroidKeyAttestationStatement per format. As AttestationStatement is not self-descriptive for its format, the format need to be persisted in an another field. Because of that, an envelope class which has attestationStatement field and format field is required, and the envelope class need to be serialized for persisting AttestationStatement. Since the envelope class itself is not provided by the WebAuthn4J library, please implement your own envelope class on the application side, referring to the example below.

If you would like to persist as JSON String, use ObjectConverter.

This member is long. Nothing special is required.

This member can be serialized as CBOR bytes array as it is originally CBOR data. If you would like to persist as String, use Base64UrlUtil to convert from byte[] to base64url String.

This member can be serialized as JSON as it is originally JSON data.

Provides core features for WebAuthn attestation and assertion verification.

Provides additional features regarding FIDO Metadata Service.

Provides async variant of core features for WebAuthn attestation and assertion verification. Since this module is in experimental status, the included classes don’t follow semantic versioning and the design may change even though it is public.

Provides async variant of additional features regarding FIDO Metadata Service. Since this module is in experimental status, the included classes don’t follow semantic versioning and the design may change even though it is public.

Provides core features for Apple App Attest attestation and assertion verification.

Internal library for WebAuthn4J testing. The included classes don’t follow semantic versioning and the design may be changed even though it is public.

Contains utility classes used in WebAuthn4J library.

CustomRegistrationVerifier and CustomAuthenticationVerifier implementation can be registered to WebAuthnManager via its constructor’s customRegistrationVerifiers and customAuthenticationVerifiers parameters.

Since WebAuthn4J wraps ObjectMapper with ObjectConverter, inject your customized ObjectMapper through ObjectConverter constructor and specify the ObjectConverter instance to the WebAuthnManager instance creation parameter.

Classes under com.webauthn4j.data package are designed as immutable DTO.

Classes under com.webauthn4j.data package are designed as being serializable and deserializable.

Some Classes under converter package needs custom serializer and deserializer. Jackson’s module named WebAuthnJSONModule and WebAuthnCBORModule consolidate these custom serializer and deserializer. WebAuthn4J’s validators register these modules onto Jackson’s ObjectMapper automatically.

If you want to use WebAuthn4J’s serializer and deserializer outside of WebAuthnManager, you can register these modules onto Jackson’s ObjectMapper.

TrustAnchorsResolver interface is used by TrustAnchorCertPathTrustworthinessVerifier to explore root certificates in the verification of the authenticity of the attestation statements.

TrustAnchorsProvider is an interface that TrustAnchorsResolverImpl delegates TrustAnchor load operation to. KeyStoreFileTrustAnchorsProvider is provided as an implementation for loading TrustAnchor from Java Key Store file. WebAuthn$J Spring Security also provides CertFileResourcesTrustAnchorProvider to load TrustAnchor from Spring Resource.

If some verification fails, WebAuthn4J throws an exception class inheriting VerificationException.

If you use FIDO CTAP2 security key for authentication in your own application, you need to register the security key first. Call the authenticatorMakeCredential method of the security key to retrieve the "Attestation" data, which contains public key and device configuration and save it. The obtained attestation data need to be verified to determine if the security key is acceptable for the application. WebAuthn4J can verify the attestation with CoreRegistrationVerifier class. For authentication, the application need to call the authenticatorGetAssertion method of the security key to retrieve the "assertion" data, which contains signature. By validating the retrieved assertion, the application can determine whether the security key used for authentication is the same as the one used for registration, and can determine whether the access is legitimate. WebAuthn4J can verify the assertion with CoreAuthenticationVerifier class.

Implementing the above flow will provide authentication feature, but if the entity that calls the FIDO CTAP2 security key (client) and the entity that verifies the attestation and the assertion are separated, in some cases, an application specific client data is needed to be verified at the server at registration and authentication. The client data itself can be sent together with the attestation and assertion, but in order to protect the client data from MITM attacks, it need to be signed and protected. In FIDO CTAP2 specification, there is a parameter named clientDataHash that is common to authenticatorMakeCredential method used at registration and authenticatorGetAssertion method used at authentication. Since the security key generates a signature from data that contains clientDataHash, an application can verify its specific client data by setting clientDataHash to the hash of the client data and validating the signature.