Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/webauthn4j/webauthn4j
A portable Java library for WebAuthn and Apple App Attest server side verification
https://github.com/webauthn4j/webauthn4j
authentication fido fido-u2f fido2 java passkey u2f webauthn
Last synced: about 2 months ago
JSON representation
A portable Java library for WebAuthn and Apple App Attest server side verification
- Host: GitHub
- URL: https://github.com/webauthn4j/webauthn4j
- Owner: webauthn4j
- License: apache-2.0
- Created: 2018-05-20T12:14:36.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-04-02T13:58:48.000Z (6 months ago)
- Last Synced: 2024-04-02T14:59:48.654Z (6 months ago)
- Topics: authentication, fido, fido-u2f, fido2, java, passkey, u2f, webauthn
- Language: Java
- Homepage: https://webauthn4j.github.io/webauthn4j/en/
- Size: 20.7 MB
- Stars: 369
- Watchers: 22
- Forks: 69
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
- awesome-webauthn - WebAuthn4J Project: WebAuthn4J - A portable Java library for WebAuthn server side verification. (Server Libraries)
- awesome-fido2 - webauthn4j/webauthn4j
README
# WebAuthn4J
[](https://github.com/webauthn4j/webauthn4j/actions)
[](https://sonarcloud.io/dashboard?id=webauthn4j)
[](https://search.maven.org/#search%7Cga%7C1%7Cwebauthn4j)
[](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/)
* [Red Hat SSO](https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.4/)
* [WebAuthn4J Spring Security](https://github.com/webauthn4j/webauthn4j-spring-security)
## 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
...
0.25.0.RELEASE
...
...
com.webauthn4j
webauthn4j-core
${webauthn4j.version}
...
```
## 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.
```java
// Client properties
byte[] attestationObject = null /* set attestationObject */;
byte[] clientDataJSON = null /* set clientDataJSON */;
String clientExtensionJSON = null; /* set clientExtensionJSON */
Set transports = null /* set transports */;
// 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 pubKeyCredParams = null;
boolean userVerificationRequired = false;
boolean userPresenceRequired = true;
RegistrationRequest registrationRequest = new RegistrationRequest(attestationObject, clientDataJSON, clientExtensionJSON, transports);
RegistrationParameters registrationParameters = new RegistrationParameters(serverProperty, pubKeyCredParams, userVerificationRequired, userPresenceRequired);
RegistrationData registrationData;
try {
registrationData = webAuthnManager.parse(registrationRequest);
} catch (DataConversionException e) {
// If you would like to handle WebAuthn data structure parse error, please catch DataConversionException
throw e;
}
try {
webAuthnManager.verify(registrationData, registrationParameters);
} catch (ValidationException e) {
// If you would like to handle WebAuthn data validation error, please catch ValidationException
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
// Client properties
byte[] credentialId = null /* set credentialId */;
byte[] userHandle = null /* set userHandle */;
byte[] authenticatorData = null /* set authenticatorData */;
byte[] clientDataJSON = null /* set clientDataJSON */;
String clientExtensionJSON = null /* set clientExtensionJSON */;
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);
// expectations
List allowCredentials = null;
boolean userVerificationRequired = true;
boolean userPresenceRequired = true;
CredentialRecord credentialRecord = load(credentialId); // please load authenticator object persisted in the registration process in your manner
AuthenticationRequest authenticationRequest =
new AuthenticationRequest(
credentialId,
userHandle,
authenticatorData,
clientDataJSON,
clientExtensionJSON,
signature
);
AuthenticationParameters authenticationParameters =
new AuthenticationParameters(
serverProperty,
credentialRecord,
allowCredentials,
userVerificationRequired,
userPresenceRequired
);
AuthenticationData authenticationData;
try {
authenticationData = webAuthnManager.parse(authenticationRequest);
} catch (DataConversionException e) {
// If you would like to handle WebAuthn data structure parse error, please catch DataConversionException
throw e;
}
try {
webAuthnManager.verify(authenticationData, authenticationParameters);
} catch (ValidationException 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.