Error handling revamp for token verification APIs (#362)

* Error handling revamp for token verification APIs

* Updated javadocs

Author: hiranya911

src/main/java/com/google/firebase/auth/AuthErrorCode.java

@@ -21,21 +21,56 @@
  */
 public enum AuthErrorCode {
 
+  /**
+   * Failed to retrieve public key certificates required to verify JWTs.
+   */
+  CERTIFICATE_FETCH_FAILED,
+
   /**
    * A user already exists with the provided email.
    */
   EMAIL_ALREADY_EXISTS,
 
+  /**
+   * The specified ID token is expired.
+   */
+  EXPIRED_ID_TOKEN,
+
+  /**
+   * The specified session cookie is expired.
+   */
+  EXPIRED_SESSION_COOKIE,
+
   /**
    * The provided dynamic link domain is not configured or authorized for the current project.
    */
   INVALID_DYNAMIC_LINK_DOMAIN,
 
+  /**
+   * The specified ID token is invalid.
+   */
+  INVALID_ID_TOKEN,
+
+  /**
+   * The specified session cookie is invalid.
+   */
+  INVALID_SESSION_COOKIE,
+
   /**
    * A user already exists with the provided phone number.
    */
   PHONE_NUMBER_ALREADY_EXISTS,
 
+  /**
+   * The specified ID token has been revoked.
+   */
+  REVOKED_ID_TOKEN,
+
+  /**
+   * The specified session cookie has been revoked.
+   */
+  REVOKED_SESSION_COOKIE,
+
   /**
    * A user already exists with the provided UID.
    */

src/main/java/com/google/firebase/auth/FirebaseAuthException.java

@@ -32,7 +32,6 @@
 public class FirebaseAuthException extends FirebaseException {
 
   private final AuthErrorCode errorCode;
-  private final String deprecatedErrorCode;
 
   FirebaseAuthException(
       @NonNull ErrorCode errorCode,
@@ -42,12 +41,6 @@ public class FirebaseAuthException extends FirebaseException {
       AuthErrorCode authErrorCode) {
     super(errorCode, message, cause, response);
     this.errorCode = authErrorCode;
-    this.deprecatedErrorCode = null;
-  }
-
-  @Deprecated
-  public FirebaseAuthException(@NonNull String errorCode, @NonNull String detailMessage) {
-    this(errorCode, detailMessage, null);
   }
 
   @Deprecated
@@ -56,17 +49,10 @@ public FirebaseAuthException(
     super(detailMessage, throwable);
     checkArgument(!Strings.isNullOrEmpty(errorCode));
     this.errorCode = null;
-    this.deprecatedErrorCode = errorCode;
   }
 
   @Nullable
   public AuthErrorCode getAuthErrorCode() {
     return errorCode;
   }
-
-  /** Returns an error code that may provide more information about the error. */
-  @Deprecated
-  public String getDeprecatedErrorCode() {
-    return deprecatedErrorCode;
-  }
 }

src/main/java/com/google/firebase/auth/FirebaseTokenUtils.java

@@ -82,6 +82,8 @@ static FirebaseTokenVerifierImpl createIdTokenVerifier(FirebaseApp app, Clock cl
         .setJsonFactory(app.getOptions().getJsonFactory())
         .setPublicKeysManager(publicKeysManager)
         .setIdTokenVerifier(idTokenVerifier)
+        .setInvalidTokenErrorCode(AuthErrorCode.INVALID_ID_TOKEN)
+        .setExpiredTokenErrorCode(AuthErrorCode.EXPIRED_ID_TOKEN)
         .build();
   }
 
@@ -100,6 +102,8 @@ static FirebaseTokenVerifierImpl createSessionCookieVerifier(FirebaseApp app, Cl
         .setShortName("session cookie")
         .setMethod("verifySessionCookie()")
         .setDocUrl("https://firebase.google.com/docs/auth/admin/manage-cookies")
+        .setInvalidTokenErrorCode(AuthErrorCode.INVALID_SESSION_COOKIE)
+        .setExpiredTokenErrorCode(AuthErrorCode.EXPIRED_SESSION_COOKIE)
         .build();
   }
 

src/main/java/com/google/firebase/auth/FirebaseTokenVerifierImpl.java

@@ -28,10 +28,12 @@
 import com.google.api.client.util.ArrayMap;
 import com.google.common.base.Joiner;
 import com.google.common.base.Strings;
+import com.google.firebase.ErrorCode;
 import java.io.IOException;
 import java.math.BigDecimal;
 import java.security.GeneralSecurityException;
 import java.security.PublicKey;
+import java.util.List;
 
 /**
  * The default implementation of the {@link FirebaseTokenVerifier} interface. Uses the Google API
@@ -43,8 +45,6 @@ final class FirebaseTokenVerifierImpl implements FirebaseTokenVerifier {
   private static final String RS256 = "RS256";
   private static final String FIREBASE_AUDIENCE =
       "https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit";
-  private static final String ERROR_INVALID_CREDENTIAL = "ERROR_INVALID_CREDENTIAL";
-  private static final String ERROR_RUNTIME_EXCEPTION = "ERROR_RUNTIME_EXCEPTION";
 
   private final JsonFactory jsonFactory;
   private final GooglePublicKeysManager publicKeysManager;
@@ -53,6 +53,8 @@ final class FirebaseTokenVerifierImpl implements FirebaseTokenVerifier {
   private final String shortName;
   private final String articledShortName;
   private final String docUrl;
+  private final AuthErrorCode invalidTokenErrorCode;
+  private final AuthErrorCode expiredTokenErrorCode;
 
   private FirebaseTokenVerifierImpl(Builder builder) {
     this.jsonFactory = checkNotNull(builder.jsonFactory);
@@ -65,6 +67,8 @@ private FirebaseTokenVerifierImpl(Builder builder) {
     this.shortName = builder.shortName;
     this.articledShortName = prefixWithIndefiniteArticle(this.shortName);
     this.docUrl = builder.docUrl;
+    this.invalidTokenErrorCode = checkNotNull(builder.invalidTokenErrorCode);
+    this.expiredTokenErrorCode = checkNotNull(builder.expiredTokenErrorCode);
   }
 
   /**
@@ -137,38 +141,28 @@ private IdToken parse(String token) throws FirebaseAuthException {
           shortName,
           docUrl,
           articledShortName);
-      throw new FirebaseAuthException(ERROR_INVALID_CREDENTIAL, detailedError, e);
-    }
-  }
-
-  private void checkContents(final IdToken token) throws FirebaseAuthException {
-    String errorMessage = getErrorIfContentInvalid(token);
-    if (errorMessage != null) {
-      String detailedError = String.format("%s %s", errorMessage, getVerifyTokenMessage());
-      throw new FirebaseAuthException(ERROR_INVALID_CREDENTIAL, detailedError);
+      throw newException(detailedError, invalidTokenErrorCode, e);
     }
   }
 
   private void checkSignature(IdToken token) throws FirebaseAuthException {
-    try {
-      if (!isSignatureValid(token)) {
-        throw new FirebaseAuthException(ERROR_INVALID_CREDENTIAL,
-            String.format(
-                "Failed to verify the signature of Firebase %s. %s",
-                shortName,
-                getVerifyTokenMessage()));
-      }
-    } catch (GeneralSecurityException | IOException e) {
-      throw new FirebaseAuthException(
-          ERROR_RUNTIME_EXCEPTION, "Error while verifying signature.", e);
+    if (!isSignatureValid(token)) {
+      String message = String.format(
+          "Failed to verify the signature of Firebase %s. %s",
+          shortName,
+          getVerifyTokenMessage());
+      throw newException(message, invalidTokenErrorCode);
     }
   }
 
-  private String getErrorIfContentInvalid(final IdToken idToken) {
+  private void checkContents(final IdToken idToken) throws FirebaseAuthException {
     final Header header = idToken.getHeader();
     final Payload payload = idToken.getPayload();
 
+    final long currentTimeMillis = idTokenVerifier.getClock().currentTimeMillis();
     String errorMessage = null;
+    AuthErrorCode errorCode = invalidTokenErrorCode;
+
     if (header.getKeyId() == null) {
       errorMessage = getErrorForTokenWithoutKid(header, payload);
     } else if (!RS256.equals(header.getAlgorithm())) {
@@ -203,14 +197,35 @@ private String getErrorIfContentInvalid(final IdToken idToken) {
       errorMessage = String.format(
           "Firebase %s has \"sub\" (subject) claim longer than 128 characters.",
           shortName);
-    } else if (!verifyTimestamps(idToken)) {
+    } else if (!idToken.verifyExpirationTime(
+        currentTimeMillis, idTokenVerifier.getAcceptableTimeSkewSeconds())) {
       errorMessage = String.format(
-          "Firebase %s has expired or is not yet valid. Get a fresh %s and try again.",
+          "Firebase %s has expired. Get a fresh %s and try again.",
           shortName,
           shortName);
+      // Also set the expired error code.
+      errorCode = expiredTokenErrorCode;
+    } else if (!idToken.verifyIssuedAtTime(
+        currentTimeMillis, idTokenVerifier.getAcceptableTimeSkewSeconds())) {
+      errorMessage = String.format(
+          "Firebase %s is not yet valid.",
+          shortName);
+    }
+
+    if (errorMessage != null) {
+      String detailedError = String.format("%s %s", errorMessage, getVerifyTokenMessage());
+      throw newException(detailedError, errorCode);
     }
+  }
+
+  private FirebaseAuthException newException(String message, AuthErrorCode errorCode) {
+    return newException(message, errorCode, null);
+  }
 
-    return errorMessage;
+  private FirebaseAuthException newException(
+      String message, AuthErrorCode errorCode, Throwable cause) {
+    return new FirebaseAuthException(
+        ErrorCode.INVALID_ARGUMENT, message, cause, null, errorCode);
   }
 
   private String getVerifyTokenMessage() {
@@ -224,15 +239,44 @@ private String getVerifyTokenMessage() {
    * Verifies the cryptographic signature on the FirebaseToken. Can block on a web request to fetch
    * the keys if they have expired.
    */
-  private boolean isSignatureValid(IdToken token) throws GeneralSecurityException, IOException {
-    for (PublicKey key : publicKeysManager.getPublicKeys()) {
-      if (token.verifySignature(key)) {
+  private boolean isSignatureValid(IdToken token) throws FirebaseAuthException {
+    for (PublicKey key : fetchPublicKeys()) {
+      if (isSignatureValid(token, key)) {
         return true;
       }
     }
+
     return false;
   }
 
+  private boolean isSignatureValid(IdToken token, PublicKey key) throws FirebaseAuthException {
+    try {
+      return token.verifySignature(key);
+    } catch (GeneralSecurityException e) {
+      // This doesn't happen under usual circumstances. Seems to only happen if the crypto
+      // setup of the runtime is incorrect in some way.
+      throw new FirebaseAuthException(
+          ErrorCode.UNKNOWN,
+          String.format("Unexpected error while verifying %s: %s", shortName, e.getMessage()),
+          e,
+          null,
+          invalidTokenErrorCode);
+    }
+  }
+
+  private List<PublicKey> fetchPublicKeys() throws FirebaseAuthException {
+    try {
+      return publicKeysManager.getPublicKeys();
+    } catch (GeneralSecurityException | IOException e) {
+      throw new FirebaseAuthException(
+          ErrorCode.UNKNOWN,
+          "Error while fetching public key certificates: " + e.getMessage(),
+          e,
+          null,
+          AuthErrorCode.CERTIFICATE_FETCH_FAILED);
+    }
+  }
+
   private String getErrorForTokenWithoutKid(IdToken.Header header, IdToken.Payload payload) {
     if (isCustomToken(payload)) {
       return String.format("%s expects %s, but was given a custom token.",
@@ -255,11 +299,6 @@ private String getProjectIdMatchMessage() {
         shortName);
   }
 
-  private boolean verifyTimestamps(IdToken token) {
-    long currentTimeMillis = idTokenVerifier.getClock().currentTimeMillis();
-    return token.verifyTime(currentTimeMillis, idTokenVerifier.getAcceptableTimeSkewSeconds());
-  }
-
   private boolean isCustomToken(IdToken.Payload payload) {
     return FIREBASE_AUDIENCE.equals(payload.getAudience());
   }
@@ -290,6 +329,8 @@ static final class Builder {
     private String shortName;
     private IdTokenVerifier idTokenVerifier;
     private String docUrl;
+    private AuthErrorCode invalidTokenErrorCode;
+    private AuthErrorCode expiredTokenErrorCode;
 
     private Builder() { }
 
@@ -323,6 +364,16 @@ Builder setDocUrl(String docUrl) {
       return this;
     }
 
+    public Builder setInvalidTokenErrorCode(AuthErrorCode invalidTokenErrorCode) {
+      this.invalidTokenErrorCode = invalidTokenErrorCode;
+      return this;
+    }
+
+    public Builder setExpiredTokenErrorCode(AuthErrorCode expiredTokenErrorCode) {
+      this.expiredTokenErrorCode = expiredTokenErrorCode;
+      return this;
+    }
+
     FirebaseTokenVerifierImpl build() {
       return new FirebaseTokenVerifierImpl(this);
     }

src/main/java/com/google/firebase/auth/RevocationCheckDecorator.java

@@ -20,30 +20,27 @@
 import static com.google.common.base.Preconditions.checkNotNull;
 
 import com.google.common.base.Strings;
+import com.google.firebase.ErrorCode;
 
 /**
  * A decorator for adding token revocation checks to an existing {@link FirebaseTokenVerifier}.
  */
 class RevocationCheckDecorator implements FirebaseTokenVerifier {
 
-  static final String ID_TOKEN_REVOKED_ERROR = "id-token-revoked";
-  static final String SESSION_COOKIE_REVOKED_ERROR = "session-cookie-revoked";
-
   private final FirebaseTokenVerifier tokenVerifier;
   private final FirebaseUserManager userManager;
-  private final String errorCode;
+  private final AuthErrorCode errorCode;
   private final String shortName;
 
   private RevocationCheckDecorator(
       FirebaseTokenVerifier tokenVerifier,
       FirebaseUserManager userManager,
-      String errorCode,
+      AuthErrorCode errorCode,
       String shortName) {
     this.tokenVerifier = checkNotNull(tokenVerifier);
     this.userManager = checkNotNull(userManager);
-    checkArgument(!Strings.isNullOrEmpty(errorCode));
+    this.errorCode = checkNotNull(errorCode);
     checkArgument(!Strings.isNullOrEmpty(shortName));
-    this.errorCode = errorCode;
     this.shortName = shortName;
   }
 
@@ -55,8 +52,14 @@ private RevocationCheckDecorator(
   public FirebaseToken verifyToken(String token) throws FirebaseAuthException {
     FirebaseToken firebaseToken = tokenVerifier.verifyToken(token);
     if (isRevoked(firebaseToken)) {
-      throw new FirebaseAuthException(errorCode, "Firebase " + shortName + " revoked");
+      throw new FirebaseAuthException(
+          ErrorCode.INVALID_ARGUMENT,
+          "Firebase " + shortName + " is revoked.",
+          null,
+          null,
+          errorCode);
     }
+
     return firebaseToken;
   }
 
@@ -69,12 +72,12 @@ private boolean isRevoked(FirebaseToken firebaseToken) throws FirebaseAuthExcept
   static RevocationCheckDecorator decorateIdTokenVerifier(
       FirebaseTokenVerifier tokenVerifier, FirebaseUserManager userManager) {
     return new RevocationCheckDecorator(
-        tokenVerifier, userManager, ID_TOKEN_REVOKED_ERROR, "id token");
+        tokenVerifier, userManager, AuthErrorCode.REVOKED_ID_TOKEN, "id token");
   }
 
   static RevocationCheckDecorator decorateSessionCookieVerifier(
       FirebaseTokenVerifier tokenVerifier, FirebaseUserManager userManager) {
     return new RevocationCheckDecorator(
-        tokenVerifier, userManager, SESSION_COOKIE_REVOKED_ERROR, "session cookie");
+        tokenVerifier, userManager, AuthErrorCode.REVOKED_SESSION_COOKIE, "session cookie");
   }
 }