webauthn4j - GitLite

KO | EN

gitlite — search

#react #ai #go #android #deep-learning #linux #nodejs #windows #awesome #cli #kubernetes #security #openai #open-source

webauthn4j

(★ 588)

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

File Explorer

Download Latest Version (.zip)

- - bug_report.md
  - feature_request.md
- - bump-version.yml
  - ci.yml
  - codeql-analysis.yml
  - dependabot-labeler.yml
  - doc.yml
  - pr-gate-ci.yml
  - release.yml
  - snapshot-release.yml
  - stale.yml
- dependabot.yml
- release.yml
- build.gradle.kts
- settings.gradle.kts
- - logo.png
- - release-procedure.md
- - gradle-wrapper.jar
  - gradle-wrapper.properties
- libs.versions.toml
- verification-keyring.keys
- verification-metadata.xml
- - build.gradle.kts
  - README.md
- - build.gradle.kts
- - build.gradle.kts
- - build.gradle.kts
- - build.gradle.kts
- ARCHITECTURE.md
- build.gradle.kts
- README.md
- settings.gradle.kts
- build.gradle.kts
- README.md
- settings.gradle.kts
- build.gradle.kts
- README.md
- settings.gradle.kts
- build.gradle.kts
- README.md
- settings.gradle.kts
- build.gradle.kts
- build.gradle.kts
- build.gradle.kts
- build.gradle.kts
- build.gradle.kts
- build.gradle.kts
- build.gradle.kts
.gitattributes
.gitignore
build.gradle.kts
gradle.properties
gradlew
gradlew.bat
jitpack.yml
LICENSE.txt
README.md
settings.gradle.kts

# Installation Guide

1. Get the code

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

Downloads the entire project code from GitHub to your computer.

cd webauthn4j

Moves into the project folder you just downloaded.

2. Gradle (Java/Kotlin)

Medium Recommended

Prerequisites

Git Needed to download the project code from GitHub.
JDK (Java) Required to build and run Java/Kotlin projects.
Gradle If the repo includes gradlew (Gradle Wrapper), you don't need to install Gradle separately.

./gradlew build

Builds the project using Gradle.

./gradlew jar -PtoolchainJdkVersion=<JDK_VERSION>

Builds the project using Gradle.

✅ A BUILD SUCCESSFUL message means it worked. The output is created under build/.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# WebAuthn4J

![WebAuthn4J](https://raw.githubusercontent.com/webauthn4j/webauthn4j/master/docs/image/logo.png)

[![Actions Status](https://github.com/webauthn4j/webauthn4j/workflows/CI/badge.svg)](https://github.com/webauthn4j/webauthn4j/actions)
[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=webauthn4j&metric=coverage)](https://sonarcloud.io/dashboard?id=webauthn4j)
[![Build Status](https://img.shields.io/maven-central/v/com.webauthn4j/webauthn4j-core.svg)](https://search.maven.org/#search%7Cga%7C1%7Cwebauthn4j)
[![Reproducible Builds](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/jvm-repo-rebuild/reproducible-central/master/content/com/webauthn4j/badge.json)](https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/com/webauthn4j/README.md)
[![license](https://img.shields.io/github/license/webauthn4j/webauthn4j.svg)](https://github.com/webauthn4j/webauthn4j/blob/master/LICENSE.txt)

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](https://fidoalliance.org/certification/functional-certification/conformance/)
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](https://www.keycloak.org/) and [Red Hat build of Keycloak](https://access.redhat.com/products/red-hat-build-of-keycloak) 
* [Quarkus Security](https://quarkus.io/guides/security-webauthn)
* [Spring Security](https://docs.spring.io/spring-security/reference/servlet/authentication/passkeys.html)
  * `spring-security-web` module provides passkeys support
  * maintained by Spring Security project
* [WebAuthn4J Spring Security](https://github.com/webauthn4j/webauthn4j-spring-security)
  * extension for spring security to add webauthn(passkey) support
  * maintained by WebAuthn4J project
* [Eclipse Vert.x Auth](https://github.com/eclipse-vertx/vertx-auth)
* [OpenAM](https://github.com/OpenIdentityPlatform/OpenAM)
* [OpenUnison](https://openunison.github.io)

## Documentation

You can find out more details from the [reference](https://webauthn4j.github.io/webauthn4j/en/).

## Getting from Maven Central

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

```xml
<properties>
  ...
  
  <webauthn4j.version>0.31.9.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](https://github.com/webauthn4j/webauthn4j/releases).

```sh
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:

```sh
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.

```java 
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
```java 
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](https://github.com/webauthn4j/webauthn4j-spring-security).

## License

WebAuthn4J is Open Source software released under the
[Apache 2.0 license](http://www.apache.org/licenses/LICENSE-2.0.html).

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