java-webauthn-server

:toc:
:toc-placement: macro
:toc-title:

image:https://travis-ci.org/Yubico/java-webauthn-server.svg?branch=master["Build Status", link="https://travis-ci.org/Yubico/java-webauthn-server"]
image:https://github.com/Yubico/java-webauthn-server/workflows/build/badge.svg["Build Status", link="https://github.com/Yubico/java-webauthn-server/actions"]
image:https://coveralls.io/repos/github/Yubico/java-webauthn-server/badge.svg["Coverage Status", link="https://coveralls.io/github/Yubico/java-webauthn-server"]

Server-side https://www.w3.org/TR/webauthn/[Web Authentication] library for
Java. Provides implementations of the
https://www.w3.org/TR/webauthn/#rp-operations[Relying Party operations] required
for a server to support Web Authentication. This includes registering
authenticators and authenticating registered authenticators.

toc::[]

== Dependency configuration

Maven:

Gradle:

compile 'com.yubico:webauthn-server-core:1.5.0'

== Features

Generates request objects suitable as parameters to
navigator.credentials.create() and .get()
Performs all necessary
https://www.w3.org/TR/webauthn/#rp-operations[validation logic] on the
response from the client
No mutable state or side effects - everything (except builders) is thread safe
Optionally integrates with a "metadata service" to verify
https://www.w3.org/TR/webauthn/#sctn-attestation[authenticator attestations]
and annotate responses with additional authenticator metadata

=== Non-features

This library has no concept of accounts, sessions, permissions or identity
federation, and it's not an authentication framework; it only deals with
executing the WebAuthn authentication mechanism. Sessions, account management
and other higher level concepts can make use of this authentication mechanism,
but the authentication mechanism alone does not make a security system.

== Known issues

In the link:webauthn-server-demo[example app], authentication does not work in
Chrome as of version 70. This is due to a
link:https://bugs.chromium.org/p/chromium/issues/detail?id=847878[bug in
Chrome] which will not be worked around here. To work around this in
application code, you can omit the
link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core/latest/com/yubico/webauthn/data/AuthenticatorAssertionResponse.AuthenticatorAssertionResponseBuilder.html#userHandle-java.util.Optional[userHandle]
when constructing an
link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core/latest/com/yubico/webauthn/data/AuthenticatorAssertionResponse.html[AuthenticatorAssertionResponse]
value if the userHandle is empty. See
https://github.com/Yubico/java-webauthn-server/issues/12 .

== Documentation

See the
link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core/latest/com/yubico/webauthn/package-summary.html[Javadoc]
for in-depth API documentation.

== Quick start

Implement the
link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core/latest/com/yubico/webauthn/CredentialRepository.html[CredentialRepository]
interface with your database access logic. See
link:https://github.com/Yubico/java-webauthn-server/blob/master/webauthn-server-demo/src/main/java/demo/webauthn/InMemoryRegistrationStorage.java[InMemoryRegistrationStorage]
for an example.

Instantiate the
link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core/latest/com/yubico/webauthn/RelyingParty.html[RelyingParty]
class:

[source,java]

RelyingPartyIdentity rpIdentity = RelyingPartyIdentity.builder()
.id("example.com")
.name("Example Application")
.build();

RelyingParty rp = RelyingParty.builder()
.identity(rpIdentity)
.credentialRepository(new MyCredentialRepository())
.build();

=== Registration

Initiate a registration ceremony:

[source,java]

byte[] userHandle = new byte[64];
random.nextBytes(userHandle);

PublicKeyCredentialCreationOptions request = rp.startRegistration(StartRegistrationOptions.builder()
.user(UserIdentity.builder()
.name("alice")
.displayName("Alice Hypothetical")
.id(new ByteArray(userHandle))
.build())
.build());

Serialize request to JSON and send it to the client:

[source,java]

import com.fasterxml.jackson.databind.ObjectMapper;

ObjectMapper jsonMapper = new ObjectMapper()
.configure(SerializationFeature.FAIL_ON_EMPTY_BEANS, false)
.setSerializationInclusion(Include.NON_ABSENT)
.registerModule(new Jdk8Module());

String json = jsonMapper.writeValueAsString(request);
return json;

Get the response from the client:

[source,java]

String responseJson = /* ... */;
PublicKeyCredential<AuthenticatorAttestationResponse, ClientRegistrationExtensionOutputs> pkc =
PublicKeyCredential.parseRegistrationResponseJson(responseJson);

Validate the response:

[source,java]

try {
RegistrationResult result = rp.finishRegistration(FinishRegistrationOptions.builder()
.request(request)
.response(pkc)
.build());
} catch (RegistrationFailedException e) { /* ... */ }

Update your database:

[source,java]

storeCredential("alice", result.getKeyId(), result.getPublicKeyCose());

=== Authentication

Initiate an authentication ceremony:

[source,java]

AssertionRequest request = rp.startAssertion(StartAssertionOptions.builder()
.username(Optional.of("alice"))
.build());
String json = jsonMapper.writeValueAsString(request);
return json;

Validate the response:

[source,java]

String responseJson = /* ... */;

PublicKeyCredential<AuthenticatorAssertionResponse, ClientAssertionExtensionOutputs> pkc =
PublicKeyCredential.parseAssertionResponseJson(responseJson);

try {
AssertionResult result = rp.finishAssertion(FinishAssertionOptions.builder()
.request(request)
.response(pkc)
.build());

if (result.isSuccess()) {
    return result.getUsername();
}

} catch (AssertionFailedException e) { /* ... */ }
throw new RuntimeException("Authentication failed");

For more detailed example usage, see
link:webauthn-server-demo[webauthn-server-demo] for a complete demo server.

== Architecture

The library tries to place as few requirements on the overall application
architecture as possible. For this reason it is stateless and free from side
effects, and does not directly interact with any database. This means it is
database agnostic and thread safe. The following diagram illustrates an example
architecture for an application using the library.

image::https://raw.githubusercontent.com/Yubico/java-webauthn-server/master/docs/img/demo-architecture.svg?sanitize=true["Example application architecture",align="center"]

The application manages all state and database access, and communicates with the
library via POJO representations of requests and responses. The following
diagram illustrates the data flow during a WebAuthn registration or
authentication ceremony.

image::https://raw.githubusercontent.com/Yubico/java-webauthn-server/master/docs/img/demo-sequence-diagram.svg?sanitize=true["WebAuthn ceremony sequence diagram",align="center"]

In this diagram, the Client is the user's browser and the application's
client-side scripts. The Server is the application and its business logic, the
Library is this library, and the Users database stores registered WebAuthn
credentials.

. The client requests to start the ceremony, for example by submitting a form.
The username may or may not be known at this point. For example, the user
might be requesting to create a new account, or we might be using
username-less authentication.

. If the user does not already have a
https://www.w3.org/TR/webauthn/#user-handle[user handle], the application
creates one in some application-specific way.

. The application may choose to authenticate the user with a password or the
like before proceeding.

. The application calls one of the library's "start" methods to generate a
parameter object to be passed to navigator.credentials.create() or .get()
on the client.

. The library generates a random challenge and an assortment of other arguments
depending on configuration set by the application.

. If the username is known, the library uses a read-only database adapter
provided by the application to look up the user's credentials.

. The returned list of https://www.w3.org/TR/webauthn/#credential-id[credential
IDs] is used to populate the
https://www.w3.org/TR/webauthn/#dom-publickeycredentialcreationoptions-excludecredentials[`excludeCredentials`]
or
https://www.w3.org/TR/webauthn/#dom-publickeycredentialrequestoptions-allowcredentials[`allowCredentials`]
parameter.

. The library returns a request object which can be serialized to JSON and
passed as the publicKey argument to navigator.credentials.create() or
.get(). For registration ceremonies this will be a
https://www.w3.org/TR/webauthn/#dictdef-publickeycredentialcreationoptions[`PublicKeyCredentialCreationOptions`],
and for authentication ceremonies it will be a
https://www.w3.org/TR/webauthn/#dictdef-publickeycredentialrequestoptions[`PublicKeyCredentialRequestOptions`].
The application stores the request in temporary storage.

. The application's client-side script runs navigator.credentials.create() or
.get() with request as the publicKey argument.

. The user confirms the operation and the client returns a
https://www.w3.org/TR/webauthn/#public-key-credential[`PublicKeyCredential`]
object response to the application.

. The application retrieves the request from temporary storage and passes
request and response to one of the library's "finish" methods to run the
response validation logic.

. The library verifies that the response contents - challenge, origin, etc. -
are valid.

. If this is an authentication ceremony, the library uses the database adapter
to look up the public key for the credential named in response.id.

. The database adapter returns the public key.

. The library verifies the authentication signature.

. The library returns a POJO representation of the result of the ceremony. For
registration ceremonies, this will include the credential ID and public key of
the new credential. The application may opt in to also getting
information about the authenticator model and whether the authenticator
attestation is trusted. For authentication ceremonies, this will include the
username and user handle, the credential ID of the credential used, and the
new https://www.w3.org/TR/webauthn/#signature-counter[signature counter] value
for the credential.

. The application inspects the result object and takes any appropriate actions
as defined by its business logic.

. If the result is not satisfactory, the application reports failure to the
client.

. If the result is satisfactory, the application proceeds with storing the new
credential if this is a registration ceremony.

. If this is an authentication ceremony, the application updates the signature
counter stored in the database for the credential.

. Finally, the application reports success and resumes its business logic.

== Building

Use the included
https://docs.gradle.org/current/userguide/gradle_wrapper.html[Gradle wrapper] to
build the .jar artifact:

$ ./gradlew :webauthn-server-core:jar

The output is built in the webauthn-server-core/build/libs/ directory, and the
version is derived from the most recent Git tag. Builds done on a tagged commit
will have a plain x.y.z version number, while a build on any other commit will
result in a version number containing the abbreviated commit hash.

Starting in version 1.4.0-RC2, artifacts are built reproducibly. Fresh builds from
tagged commits should therefore be verifiable by signatures from Maven Central:

$ git checkout 1.4.0-RC2
$ ./gradlew :webauthn-server-core:jar
$ wget https://repo1.maven.org/maven2/com/yubico/webauthn-server-core/1.4.0-RC2/webauthn-server-core-1.4.0-RC2.jar.asc
$ gpg --verify webauthn-server-core-1.4.0-RC2.jar.asc webauthn-server-core/build/libs/webauthn-server-core-1.4.0-RC2.jar

Note that building with a different JDK may produce a different artifact. To
ensure binary reproducibility, please build with the same JDK as specified in
the release notes.

Official Yubico software signing keys are listed on the
https://developers.yubico.com/Software_Projects/Software_Signing.html[Yubico
Developers site].

To run the tests:

$ ./gradlew check

To run the http://pitest.org/[PIT mutation tests] (this may take upwards of 30
minutes):

名称与所有者	Yubico/java-webauthn-server
主编程语言	Scala
编程语言	Groovy (语言数: 6)
平台
许可证	Other

创建于	2018-05-08 13:01:39
推送于	2025-06-10 11:37:22
最后一次提交
发布数	124
最新版本名称	2.7.0 (发布于 2025-05-15 11:35:38)
第一版名称	0.14.0 (发布于 2015-02-03 12:19:43)

星数	505
关注者数	44
派生数	155
提交数	3.1k
已启用问题?
问题数	157
打开的问题数	17
拉请求数	175
打开的拉请求数	1
关闭的拉请求数	52

已启用Wiki?
已存档?
是复刻?
已锁定?
是镜像?
是私有?

java-webauthn-server

Github星跟踪图

java-webauthn-server

compile 'com.yubico:webauthn-server-core:1.5.0'

[source,java]

RelyingParty rp = RelyingParty.builder()
.identity(rpIdentity)
.credentialRepository(new MyCredentialRepository())
.build();

[source,java]

PublicKeyCredentialCreationOptions request = rp.startRegistration(StartRegistrationOptions.builder()
.user(UserIdentity.builder()
.name("alice")
.displayName("Alice Hypothetical")
.id(new ByteArray(userHandle))
.build())
.build());

[source,java]

String json = jsonMapper.writeValueAsString(request);
return json;

[source,java]

String responseJson = /* ... */;
PublicKeyCredential<AuthenticatorAttestationResponse, ClientRegistrationExtensionOutputs> pkc =
PublicKeyCredential.parseRegistrationResponseJson(responseJson);

[source,java]

try {
RegistrationResult result = rp.finishRegistration(FinishRegistrationOptions.builder()
.request(request)
.response(pkc)
.build());
} catch (RegistrationFailedException e) { /* ... */ }

[source,java]

storeCredential("alice", result.getKeyId(), result.getPublicKeyCose());

[source,java]

AssertionRequest request = rp.startAssertion(StartAssertionOptions.builder()
.username(Optional.of("alice"))
.build());
String json = jsonMapper.writeValueAsString(request);
return json;

[source,java]

} catch (AssertionFailedException e) { /* ... */ }
throw new RuntimeException("Authentication failed");

$ ./gradlew :webauthn-server-core:jar

$ ./gradlew check

$ ./gradlew pitest

主要指标

java-webauthn-server

Github星跟踪图

java-webauthn-server

compile 'com.yubico:webauthn-server-core:1.5.0'

[source,java]

RelyingParty rp = RelyingParty.builder() .identity(rpIdentity) .credentialRepository(new MyCredentialRepository()) .build();

[source,java]

PublicKeyCredentialCreationOptions request = rp.startRegistration(StartRegistrationOptions.builder() .user(UserIdentity.builder() .name("alice") .displayName("Alice Hypothetical") .id(new ByteArray(userHandle)) .build()) .build());

[source,java]

String json = jsonMapper.writeValueAsString(request); return json;

[source,java]

String responseJson = /* ... */; PublicKeyCredential<AuthenticatorAttestationResponse, ClientRegistrationExtensionOutputs> pkc = PublicKeyCredential.parseRegistrationResponseJson(responseJson);

[source,java]

try { RegistrationResult result = rp.finishRegistration(FinishRegistrationOptions.builder() .request(request) .response(pkc) .build()); } catch (RegistrationFailedException e) { /* ... */ }

[source,java]

storeCredential("alice", result.getKeyId(), result.getPublicKeyCose());

[source,java]

AssertionRequest request = rp.startAssertion(StartAssertionOptions.builder() .username(Optional.of("alice")) .build()); String json = jsonMapper.writeValueAsString(request); return json;

[source,java]

} catch (AssertionFailedException e) { /* ... */ } throw new RuntimeException("Authentication failed");

$ ./gradlew :webauthn-server-core:jar

$ ./gradlew check

$ ./gradlew pitest

主要指标

RelyingParty rp = RelyingParty.builder()
.identity(rpIdentity)
.credentialRepository(new MyCredentialRepository())
.build();

PublicKeyCredentialCreationOptions request = rp.startRegistration(StartRegistrationOptions.builder()
.user(UserIdentity.builder()
.name("alice")
.displayName("Alice Hypothetical")
.id(new ByteArray(userHandle))
.build())
.build());

String json = jsonMapper.writeValueAsString(request);
return json;

String responseJson = /* ... */;
PublicKeyCredential<AuthenticatorAttestationResponse, ClientRegistrationExtensionOutputs> pkc =
PublicKeyCredential.parseRegistrationResponseJson(responseJson);

try {
RegistrationResult result = rp.finishRegistration(FinishRegistrationOptions.builder()
.request(request)
.response(pkc)
.build());
} catch (RegistrationFailedException e) { /* ... */ }

AssertionRequest request = rp.startAssertion(StartAssertionOptions.builder()
.username(Optional.of("alice"))
.build());
String json = jsonMapper.writeValueAsString(request);
return json;

} catch (AssertionFailedException e) { /* ... */ }
throw new RuntimeException("Authentication failed");