feat(appcheck): Add App Check token verification support with replay protection by yvonnep165 · Pull Request #1233 · firebase/firebase-admin-java

yvonnep165 · 2026-08-24T19:42:50Z

This PR adds support for App Check standard token verification and one-time token verification for replay protection. This enables backend servers to verify standard App Check JWTs locally and optionally verify/consume limited-use (replay-protected) tokens via backend RPC.

Adds the FirebaseAppCheck service entry point with synchronous and asynchronous verifyToken methods.
Creates the data models and options (DecodedAppCheckToken, VerifyAppCheckTokenResponse, VerifyAppCheckTokenOptions, FirebaseAppCheckException) for token verification results and options.
Verifies tokens locally using App Check public keys and calls the backend to consume one-time tokens.
Adds full unit test suites

…eckTokenOptions classes

…n and one time token verification

…e formatting

gemini-code-assist

Code Review

This pull request introduces the Firebase App Check service, including token verification capabilities, option and response models, custom exceptions, and comprehensive unit tests. The review feedback highlights two critical issues in AppCheckTokenVerifier.java: a potential NullPointerException when checking the audience claim if it is missing from the JWT, and a resource leak due to the HttpResponse not being closed after executing the backend verification request.

…quest execute in a try-finally block

weixifan

Thank you for this PR! Some minor comments.

weixifan · 2026-08-24T21:36:08Z

+  private final JsonFactory jsonFactory;
+  private volatile DefaultJWTProcessor<SecurityContext> jwtProcessor;
+
+  public AppCheckTokenVerifier(FirebaseApp app) {


In the Admin SDK, do we use Guice or Dagger to manage the dependency injection of parameters? If so, a singleton-scoped JWK parameter can be injected and managed by Guice or Dagger instead.

We don't use Guice or Dagger. Instead we use manual dependency injection via package-private @VisibleForTesting constructors and the services are singletons scoped to the FirebaseApp lifecycle.

weixifan · 2026-08-24T21:42:36Z

+  }
+
+  protected JWKSource<SecurityContext> createKeySource() throws MalformedURLException {
+    return JWKSourceBuilder.create(URI.create(JWKS_URL).toURL()).retrying(true).build();


Can we please cache this for 6 hours, using .cache(...)? The refresh timeout can be left at default (15 seconds).

https://www.javadoc.io/doc/com.nimbusds/nimbus-jose-jwt/latest/com/nimbusds/jose/jwk/source/JWKSourceBuilder.html#cache(long,long)

Sure! added.

weixifan · 2026-08-24T21:48:52Z

+
+  private DefaultJWTProcessor<SecurityContext> getJwtProcessor() {
+    DefaultJWTProcessor<SecurityContext> processor = this.jwtProcessor;
+    if (processor == null) {


Is there a reason this initialization logic can't be put into the constructor? Doing so avoids the subtle and error-prone synchronization logic. For example, the necessity of the double null-check is not immediately obvious.

Just tried to mirror the pattern from FirebasePhoneNumberVerificationTokenVerifier, which used double-checked locking for its jwtProcessor. But that's a good point! I updated jwtProcessor to be initialized directly in the constructor as a final field and removed the double checking.

weixifan · 2026-08-24T21:57:34Z

+          ErrorCode.INVALID_ARGUMENT, "App Check token has no 'iss' (issuer) claim.");
+    }
+
+    if (!issuer.startsWith(APP_CHECK_ISSUER)) {


I think in Admin SDK, we don't have access to the developer's project number. This is actually a deficiency, as https://google.aip.dev/cloud/2510 states that the project number is the canonical identifier, and there are issues in working with project IDs in general.

In the future, if we ever address this issue and we finally get access to the project number, it's actually better to check for strict equality to https://firebaseappcheck.googleapis.com/<project_number> here -- for example, https://firebaseappcheck.googleapis.com/12345678.

Perhaps a comment explaining this would be appropriate here.

Comment added.

weixifan · 2026-08-24T22:13:46Z

+    } catch (BadJOSEException e) {
+      throw new FirebaseAppCheckException(
+          ErrorCode.INVALID_ARGUMENT,
+          "Check your project: " + projectId + ". Firebase App Check token is invalid: "


I think this exception type is the one corresponding to an invalid signature, while the JOSEException is thrown when an internal error happens.

https://www.javadoc.io/doc/com.nimbusds/nimbus-jose-jwt/latest/com/nimbusds/jwt/proc/DefaultJWTProcessor.html#process(com.nimbusds.jwt.SignedJWT,C)

Thanks for catching that!

weixifan · 2026-08-24T22:29:22Z

+   */
+  public DecodedAppCheckToken(Map<String, Object> claims) {
+    checkNotNull(claims, "Claims map must not be null");
+    checkArgument(claims.containsKey("sub"), "Claims map must contain sub");


We should probably also check the other required claims iss, aud, exp, and iat.

This followed the convention from FirebaseToken (auth) and FirebasePhoneNumberVerificationToken, where only sub is strictly required in the constructor and the full claims validation (iss, aud, exp, iat) is handled by AppCheckTokenVerifier before the object is instantiated. Try to keep DecodedAppCheckToken as a flexible claims wrapper allows the getters to provide fallbacks (e.g. getAudience() returning []) and make creating mock tokens in tests much simpler. But let me know if you'd still prefer enforcing all of them here though!

I don't feel too strongly about this topic. Note that for these required claim names, the App Check backend is quite disciplined and will never return empty or null for them. For testing, it's reasonable to have an additional test-only constructor where these checks are not performed.

weixifan · 2026-08-24T22:30:39Z

+  /**
+   * Returns the expiration time in seconds since the Unix epoch.
+   */
+  public long getExpirationTime() {


I think java.time.Instant is a better candidate to hold instants in time, since we have access to Java 8.

weixifan · 2026-08-24T22:31:03Z

+  /**
+   * Returns the issued-at time in seconds since the Unix epoch.
+   */
+  public long getIssuedAt() {


weixifan · 2026-08-24T22:32:42Z

+/**
+ * Represents a verified Firebase App Check token.
+ */
+public class DecodedAppCheckToken {


If this class is part of the public API, please also consider exposing provider and the optional claim jti.

Added getJti() and getProvider().

weixifan · 2026-08-24T22:36:46Z

+     * @return This builder.
+     */
+    public Builder setConsume(Optional<Boolean> consume) {
+      this.consume = consume != null ? consume : Optional.<Boolean>empty();


In my opinion, allowing nulls into an optional parameter re-exposes the exact same problem that Optional<> was intended to solve. I think it's better for us to check for nullness and throw in this case.

…rocessor

weixifan

Approved with only minor comments!

weixifan · 2026-08-26T02:54:10Z

+   */
+  public DecodedAppCheckToken(Map<String, Object> claims) {
+    checkNotNull(claims, "Claims map must not be null");
+    checkArgument(claims.containsKey("sub"), "Claims map must contain sub");


I don't feel too strongly about this topic. Note that for these required claim names, the App Check backend is quite disciplined and will never return empty or null for them. For testing, it's reasonable to have an additional test-only constructor where these checks are not performed.

weixifan · 2026-08-26T02:56:31Z


+  /**
+   * Returns the App ID for which this token was issued.
+   * This is an alias for {@link #getSubject()}.


Actually, I would prefer not promising that the sub claim is equal to the app ID, even though it is the case today.

weixifan · 2026-08-26T02:59:53Z


  /**
-   * Returns the expiration time in seconds since the Unix epoch.
+   * Returns the expiration time as an {@link Instant}, or {@code null} if not present.


You can actually promise that this is never null, if we perform the check for it. Similarly for getIssuedAt below.

weixifan · 2026-08-26T03:06:36Z

  private Date expirationTime;

  @Before
  public void setUp() throws Exception {


Is it possible to write a couple of real token tests? Creating JWTs with a simulated public/private RSA key pair shouldn't be too difficult with nimbusds. You can create JWT with a private key, and you can mock the JWKS URL to return a JWKS containing your public key.

This isn't too urgent, and can definitely be added in a follow-up PR, but the test will be a lot stronger for having real token tests.

yvonnep165 added 9 commits August 20, 2026 14:52

Add exception handling covered by standard platform ErrorCode

4e8c8aa

Add DecodedAppCheckToken, VerifyAppCheckTokenResponse and VerifyAppCh…

7f56cb3

…eckTokenOptions classes

Add internal appchecktokenverifier class to support token verificatio…

4341926

…n and one time token verification

create the entry point for the Firebase App Check service and fix som…

7e4dd47

…e formatting

Add unit tests for internal appcheck processing

8b672ad

add unit tests for decoded app check token

b015d15

add unit tests for firebaseappcheck class

c2818a9

add unit tests for appchecktokenoptions

2cdabc5

add unit tests for appchecktokenresponse

03e1be1

yvonnep165 self-assigned this Aug 24, 2026

yvonnep165 added release-note release:stage Stage a release candidate labels Aug 24, 2026

gemini-code-assist Bot reviewed Aug 24, 2026

View reviewed changes

Comment thread src/main/java/com/google/firebase/appcheck/internal/AppCheckTokenVerifier.java Outdated

Comment thread src/main/java/com/google/firebase/appcheck/internal/AppCheckTokenVerifier.java

add defensively check for null for audience claim and wrap the httpre…

e5269d6

…quest execute in a try-finally block

yvonnep165 requested review from jonathanedey and weixifan August 24, 2026 21:29

weixifan reviewed Aug 24, 2026

View reviewed changes

yvonnep165 added 7 commits August 25, 2026 15:04

add 6-hour caching and default refresh timeout to createKeySource

3ebfa55

initialize the jwtProcessor inside the constructor and remove getJwtP…

208dbe8

…rocessor

add comment for future issuer check upgrade

eebd884

reverse error messages for badjoseexception and joseexception

a737d2b

use java.time.Instant for get issued at time and expiration time

2c05450

add appid, provider and jti properties exposure

c30d590

add check for null for setConsume

8ee2a99

weixifan approved these changes Aug 26, 2026

View reviewed changes

Uh oh!

Conversation

yvonnep165 commented Aug 24, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

weixifan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yvonnep165 Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weixifan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

yvonnep165 Aug 25, 2026 •

edited

Loading