Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 2,718 Commits
.devcontainer		.devcontainer
.github		.github
buildSrc		buildSrc
docs		docs
gradle		gradle
webauthn4j-appattest		webauthn4j-appattest
webauthn4j-core-async		webauthn4j-core-async
webauthn4j-core		webauthn4j-core
webauthn4j-metadata-async		webauthn4j-metadata-async
webauthn4j-metadata		webauthn4j-metadata
webauthn4j-test		webauthn4j-test
webauthn4j-util		webauthn4j-util
.gitignore		.gitignore
LICENSE.txt		LICENSE.txt
README.md		README.md
build.gradle.kts		build.gradle.kts
github-release-notes-generator.yml		github-release-notes-generator.yml
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
jitpack.yml		jitpack.yml
settings.gradle.kts		settings.gradle.kts

Repository files navigation

WebAuthn4J

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

Conformance

All mandatory test cases and optional Android Key attestation test cases ofFIDO2 Test Tools provided by FIDO Allianceare 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 byNotNull orNullable annotationto declare nullability explicitly.

Projects using WebAuthn4J

Keycloak andRed Hat build of Keycloak
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 thereference.

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.30.1.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 build WebAuthn4J.To use WebAuthn4J library, JDK11 is OK if you don't need EdDSA support.

Checkout sources

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

Build all jars

./gradlew build

How to use

Parse and Validation on WebAuthn registration

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

StringregistrationResponseJSON ="<registrationResponseJSON>";/* set registrationResponseJSON received from frontend */RegistrationDataregistrationData;try {registrationData =webAuthnManager.parseRegistrationResponseJSON(registrationResponseJSON);}catch (DataConversionExceptione) {// If you would like to handle WebAuthn data structure parse error, please catch DataConversionExceptionthrowe;}// Server propertiesOriginorigin =null/* set origin */;StringrpId =null/* set rpId */;Challengechallenge =null/* set challenge */;byte[]tokenBindingId =null/* set tokenBindingId */;ServerPropertyserverProperty =newServerProperty(origin,rpId,challenge,tokenBindingId);// expectationsList<PublicKeyCredentialParameters>pubKeyCredParams =null;booleanuserVerificationRequired =false;booleanuserPresenceRequired =true;RegistrationParametersregistrationParameters =newRegistrationParameters(serverProperty,pubKeyCredParams,userVerificationRequired,userPresenceRequired);try {webAuthnManager.verify(registrationData,registrationParameters);}catch (VerificationExceptione) {// If you would like to handle WebAuthn data verification error, please catch VerificationExceptionthrowe;}// please persist CredentialRecord object, which will be used in the authentication process.CredentialRecordcredentialRecord =newCredentialRecordImpl(// You may create your own CredentialRecord implementation to save friendly authenticator nameregistrationData.getAttestationObject(),registrationData.getCollectedClientData(),registrationData.getClientExtensions(),registrationData.getTransports()        );save(credentialRecord);// please persist credentialRecord in your manner

Parse and Validation on authentication

StringauthenticationResponseJSON ="<authenticationResponseJSON>";/* set authenticationResponseJSON received from frontend */AuthenticationDataauthenticationData;try {authenticationData =webAuthnManager.parseAuthenticationResponseJSON(authenticationResponseJSON);}catch (DataConversionExceptione) {// If you would like to handle WebAuthn data structure parse error, please catch DataConversionExceptionthrowe;}// Server propertiesOriginorigin =null/* set origin */;StringrpId =null/* set rpId */;Challengechallenge =null/* set challenge */;byte[]tokenBindingId =null/* set tokenBindingId */;ServerPropertyserverProperty =newServerProperty(origin,rpId,challenge,tokenBindingId);// expectationsList<byte[]>allowCredentials =null;booleanuserVerificationRequired =true;booleanuserPresenceRequired =true;CredentialRecordcredentialRecord =load(authenticationData.getCredentialId());// please load authenticator object persisted in the registration process in your mannerAuthenticationParametersauthenticationParameters =newAuthenticationParameters(serverProperty,credentialRecord,allowCredentials,userVerificationRequired,userPresenceRequired        );try {webAuthnManager.verify(authenticationData,authenticationParameters);}catch (VerificationExceptione) {// If you would like to handle WebAuthn data validation error, please catch ValidationExceptionthrowe;}// please update the counter of the authenticator recordupdateCounter(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 seeWebAuthn4J Spring Security sample application.

License

WebAuthn4J is Open Source software released under theApache 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.