Skip to content
A portable Java library for WebAuthn server side verification
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Update issue templates Feb 15, 2019
docs/src/reference/asciidoc
gradle/wrapper
owasp Adjust dependency check alerts suppressions Mar 21, 2019
webauthn4j-core
webauthn4j-metadata
webauthn4j-test
webauthn4j-util
.gitignore
.travis.yml Configure OWASP dependency-check Mar 20, 2019
LICENSE.txt
README.md Release 0.8.2.RELEASE Feb 27, 2019
build.gradle Adjust asciidoctorJ and dependency check Mar 21, 2019
gradle.properties Address asciidoc syntax errors Mar 21, 2019
gradlew Polish gradle wrapper Dec 1, 2018
gradlew.bat Initial commit Mar 10, 2018
helper.gradle
settings.gradle Remove webauthn4j-extras module Feb 16, 2019

README.md

WebAuthn4J

Build Status Coverage Build Status license

A portable Java library for WebAuthn server side verification

This library hasn't reached version 1. Design may change.

Supported Attestation statement format

All attestation statement formats are supported.

  • Packed attestation
  • FIDO U2F attestation
  • Android Key attestation
  • Android SafetyNet attestation
  • TPM attestation
  • None attestation

Conformance

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

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

  • Java8 or later

Checkout sources

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

Build all jars

./gradlew build

How to use

Verification on registration

// Client properties
byte[] clientDataJSON = null /* set clientDataJSON */;
byte[] attestationObject = null /* set attestationObject */;

// 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);
boolean userVerificationRequired = false;

WebAuthnRegistrationContext registrationContext = new WebAuthnRegistrationContext(clientDataJSON, attestationObject, serverProperty, userVerificationRequired);

// WebAuthnRegistrationContextValidator.createNonStrictRegistrationContextValidator() returns a WebAuthnRegistrationContextValidator instance
// which doesn't validate an attestation statement. It is recommended configuration for most web application.
// If you are building enterprise web application and need to validate the attestation statement, use the constructor of
// WebAuthnRegistrationContextValidator and provide validators you like
WebAuthnRegistrationContextValidator webAuthnRegistrationContextValidator =
        WebAuthnRegistrationContextValidator.createNonStrictRegistrationContextValidator();


WebAuthnRegistrationContextValidationResponse response = webAuthnRegistrationContextValidator.validate(registrationContext);

// please persist Authenticator object, which will be used in the authentication process.
Authenticator authenticator =
        new AuthenticatorImpl( // You may create your own Authenticator implementation to save friendly authenticator name
                response.getAttestationObject().getAuthenticatorData().getAttestedCredentialData(),
                response.getAttestationObject().getAttestationStatement(),
                response.getAttestationObject().getAuthenticatorData().getSignCount()
        );
save(authenticator); // please persist authenticator in your manner

Verification on authentication

// Client properties
byte[] credentialId = null /* set credentialId */;
byte[] clientDataJSON = null /* set clientDataJSON */;
byte[] authenticatorData = null /* set authenticatorData */;
byte[] signature = null /* set signature */;

// 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);
boolean userVerificationRequired = true;

WebAuthnAuthenticationContext authenticationContext =
        new WebAuthnAuthenticationContext(
                credentialId,
                clientDataJSON,
                authenticatorData,
                signature,
                serverProperty,
                userVerificationRequired
        );
Authenticator authenticator = load(credentialId); // please load authenticator object persisted in the registration process in your manner

WebAuthnAuthenticationContextValidator webAuthnAuthenticationContextValidator =
        new WebAuthnAuthenticationContextValidator();

WebAuthnAuthenticationContextValidationResponse response = webAuthnAuthenticationContextValidator.validate(authenticationContext, authenticator);

// please update the counter of the authenticator record
updateCounter(
        response.getAuthenticatorData().getAttestedCredentialData().getCredentialId(),
        response.getAuthenticatorData().getSignCount()
);

Sample application

Spring Security WebAuthn is built on the top of WebAuthn4J, and its sample application demonstrates WebAuthn4J feature well. Please see Spring Security WebAuthn 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.

You can’t perform that action at this time.