WebAuthn4J

A portable Java library for WebAuthn(Passkeys) server side verification

Conformance

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

Supported Attestation statement format

All attestation statement formats are supported.

• Packed attestation
• FIDO U2F attestation
• Android Key attestation
• Android SafetyNet attestation
• TPM attestation
• Apple Anonymous attestation
• None attestation
• Apple App Attest attestation

Kotlin friendly

Although WebAuthn4J is written in Java, public members are marked by NotNull or Nullable annotation to declare nullability explicitly.

Projects using WebAuthn4J

• Keycloak and Red Hat build of Keycloak
• Quarkus Security
• Spring Security
  • spring-security-web module provides passkeys support
  • maintained by Spring Security project
• WebAuthn4J Spring Security
  • extension for spring security to add webauthn(passkey) support
  • maintained by WebAuthn4J project
• Eclipse Vert.x Auth
• OpenAM
• OpenUnison

Documentation

You can find out more details from the reference.

Getting from Maven Central

If you are using Maven, just add the webauthn4j as a dependency:

<properties>
  ...
  <!-- Use the latest version whenever possible. -->
  <webauthn4j.version>0.31.10.RELEASE</webauthn4j.version>
  ...
</properties>

<dependencies>
  ...
  <dependency>
    <groupId>com.webauthn4j</groupId>
    <artifactId>webauthn4j-core</artifactId>
    <version>${webauthn4j.version}</version>
  </dependency>
  ...
</dependencies>

Build from source

WebAuthn4J uses a Gradle based build system. In the instructions below, gradlew is invoked from the root of the source tree and serves as a cross-platform, self-contained bootstrap mechanism for the build.

Prerequisites

Java17 or later is required to use WebAuthn4J.

Checkout sources

git clone https://github.com/webauthn4j/webauthn4j

Build all jars

./gradlew build

Reproducible builds

WebAuthn4J is committed to software supply chain security. All release artifacts support reproducible builds — you can rebuild from source and verify that the result is bit-for-bit identical to the artifacts published on Maven Central.

The exact JDK version used for each release is listed in the release notes.

git clone https://github.com/webauthn4j/webauthn4j.git
cd webauthn4j
git checkout <VERSION>.RELEASE
./gradlew jar -PtoolchainJdkVersion=<JDK_VERSION>

Then compare the locally built JARs against Maven Central:

VERSION=<VERSION>.RELEASE
find . -path "*/build/libs/webauthn4j-*-${VERSION}.jar" | while read jar; do
  module=$(basename "$jar" "-${VERSION}.jar")
  local=$(sha256sum "$jar" | cut -d' ' -f1)
  central=$(curl -sL "https://repo1.maven.org/maven2/com/webauthn4j/${module}/${VERSION}/${module}-${VERSION}.jar" \
    | sha256sum | cut -d' ' -f1)
  echo "$module: $([ "$local" = "$central" ] && echo MATCH || echo MISMATCH)"
done

All modules should show MATCH.

How to use

Parse and Validation on WebAuthn registration

If your would like to verify Apple App Attest, please see the reference.

String registrationResponseJSON = "<registrationResponseJSON>"; /* set registrationResponseJSON received from frontend */
RegistrationData registrationData;
try {
    registrationData = webAuthnManager.parseRegistrationResponseJSON(registrationResponseJSON);
} catch (DataConversionException e) {
    // If you would like to handle WebAuthn data structure parse error, please catch DataConversionException
    throw e;
}

// Server properties
Origin origin = null /* set origin */;
String rpId = null /* set rpId */;
Challenge challenge = null /* set challenge */;
byte[] tokenBindingId = null /* set tokenBindingId */;
ServerProperty serverProperty = new ServerProperty(origin, rpId, challenge, tokenBindingId);

// expectations
List<PublicKeyCredentialParameters> pubKeyCredParams = null;
boolean userVerificationRequired = false;
boolean userPresenceRequired = true;

RegistrationParameters registrationParameters = new RegistrationParameters(serverProperty, pubKeyCredParams, userVerificationRequired, userPresenceRequired);
try {
    webAuthnManager.verify(registrationData, registrationParameters);
} catch (VerificationException e) {
    // If you would like to handle WebAuthn data verification error, please catch VerificationException
    throw e;
}

// please persist CredentialRecord object, which will be used in the authentication process.
CredentialRecord credentialRecord =
        new CredentialRecordImpl( // You may create your own CredentialRecord implementation to save friendly authenticator name
                registrationData.getAttestationObject(),
                registrationData.getCollectedClientData(),
                registrationData.getClientExtensions(),
                registrationData.getTransports()
        );
save(credentialRecord); // please persist credentialRecord in your manner

Parse and Validation on authentication

String authenticationResponseJSON = "<authenticationResponseJSON>"; /* set authenticationResponseJSON received from frontend */

AuthenticationData authenticationData;
try {
    authenticationData = webAuthnManager.parseAuthenticationResponseJSON(authenticationResponseJSON);
} catch (DataConversionException e) {
    // If you would like to handle WebAuthn data structure parse error, please catch DataConversionException
    throw e;
}

// Server properties
Origin origin = null /* set origin */;
String rpId = null /* set rpId */;
Challenge challenge = null /* set challenge */;
byte[] tokenBindingId = null /* set tokenBindingId */;
ServerProperty serverProperty = new ServerProperty(origin, rpId, challenge, tokenBindingId);

// expectations
List<byte[]> allowCredentials = null;
boolean userVerificationRequired = true;
boolean userPresenceRequired = true;

CredentialRecord credentialRecord = load(authenticationData.getCredentialId()); // please load authenticator object persisted in the registration process in your manner
AuthenticationParameters authenticationParameters =
        new AuthenticationParameters(
                serverProperty,
                credentialRecord,
                allowCredentials,
                userVerificationRequired,
                userPresenceRequired
        );

try {
    webAuthnManager.verify(authenticationData, authenticationParameters);
} catch (VerificationException e) {
    // If you would like to handle WebAuthn data validation error, please catch ValidationException
    throw e;
}
// please update the counter of the authenticator record
updateCounter(authenticationData.getCredentialId(), authenticationData.getAuthenticatorData().getSignCount());

Sample application

WebAuthn4J Spring Security is built on the top of WebAuthn4J, and its sample application demonstrates WebAuthn4J feature well. Please see WebAuthn4J Spring Security sample application.

License

WebAuthn4J is Open Source software released under the Apache 2.0 license.

Contributing

Interested in helping out with WebAuthn4J? Great! Your participation in the community is much appreciated! Please feel free to open issues and send pull-requests.