Extracting the Token Verification Logic into a New Type (#222)

* Refactoring token verification logic

* Improved tests and test coverage

* Fixing token verification tests

* Cleaned up docs, tests and code order

* Added some spaing for clarity

* Addressing some style issues

Author: hiranya911

auth/auth.go

@@ -12,7 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package auth contains functions for minting custom authentication tokens, and verifying Firebase ID tokens.
+// Package auth contains functions for minting custom authentication tokens, verifying Firebase ID tokens,
+// and managing users in a Firebase project.
 package auth
 
 import (
@@ -23,49 +24,29 @@ import (
 
 	"firebase.google.com/go/internal"
 	"google.golang.org/api/identitytoolkit/v3"
-	"google.golang.org/api/option"
 	"google.golang.org/api/transport"
 )
 
 const (
 	firebaseAudience = "https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit"
-	idTokenCertURL   = "https://www.googleapis.com/robot/v1/metadata/x509/securetoken@system.gserviceaccount.com"
-	issuerPrefix     = "https://securetoken.google.com/"
-	tokenExpSeconds  = 3600
-	clockSkewSeconds = 300
+	oneHourInSeconds = 3600
 )
 
 var reservedClaims = []string{
 	"acr", "amr", "at_hash", "aud", "auth_time", "azp", "cnf", "c_hash",
 	"exp", "firebase", "iat", "iss", "jti", "nbf", "nonce", "sub",
 }
 
-// Token represents a decoded Firebase ID token.
-//
-// Token provides typed accessors to the common JWT fields such as Audience (aud) and Expiry (exp).
-// Additionally it provides a UID field, which indicates the user ID of the account to which this token
-// belongs. Any additional JWT claims can be accessed via the Claims map of Token.
-type Token struct {
-	Issuer   string                 `json:"iss"`
-	Audience string                 `json:"aud"`
-	Expires  int64                  `json:"exp"`
-	IssuedAt int64                  `json:"iat"`
-	Subject  string                 `json:"sub,omitempty"`
-	UID      string                 `json:"uid,omitempty"`
-	Claims   map[string]interface{} `json:"-"`
-}
-
 // Client is the interface for the Firebase auth service.
 //
 // Client facilitates generating custom JWT tokens for Firebase clients, and verifying ID tokens issued
 // by Firebase backend services.
 type Client struct {
-	is        *identitytoolkit.Service
-	keySource keySource
-	projectID string
-	signer    cryptoSigner
-	version   string
-	clock     internal.Clock
+	is              *identitytoolkit.Service
+	idTokenVerifier *tokenVerifier
+	signer          cryptoSigner
+	version         string
+	clock           internal.Clock
 }
 
 // NewClient creates a new instance of the Firebase Auth Client.
@@ -113,17 +94,16 @@ func NewClient(ctx context.Context, conf *internal.AuthConfig) (*Client, error)
 		return nil, err
 	}
 
-	noAuthHTTPClient, _, err := transport.NewHTTPClient(ctx, option.WithoutAuthentication())
+	idTokenVerifier, err := newIDTokenVerifier(ctx, conf.ProjectID)
 	if err != nil {
 		return nil, err
 	}
 	return &Client{
-		is:        is,
-		keySource: newHTTPKeySource(idTokenCertURL, noAuthHTTPClient),
-		projectID: conf.ProjectID,
-		signer:    signer,
-		version:   "Go/Admin/" + conf.Version,
-		clock:     internal.SystemClock,
+		is:              is,
+		idTokenVerifier: idTokenVerifier,
+		signer:          signer,
+		version:         "Go/Admin/" + conf.Version,
+		clock:           internal.SystemClock,
 	}, nil
 }
 
@@ -183,101 +163,53 @@ func (c *Client) CustomTokenWithClaims(ctx context.Context, uid string, devClaim
 			Aud:    firebaseAudience,
 			UID:    uid,
 			Iat:    now,
-			Exp:    now + tokenExpSeconds,
+			Exp:    now + oneHourInSeconds,
 			Claims: devClaims,
 		},
 	}
 	return info.Token(ctx, c.signer)
 }
 
+// Token represents a decoded Firebase ID token.
+//
+// Token provides typed accessors to the common JWT fields such as Audience (aud) and Expiry (exp).
+// Additionally it provides a UID field, which indicates the user ID of the account to which this token
+// belongs. Any additional JWT claims can be accessed via the Claims map of Token.
+type Token struct {
+	Issuer   string                 `json:"iss"`
+	Audience string                 `json:"aud"`
+	Expires  int64                  `json:"exp"`
+	IssuedAt int64                  `json:"iat"`
+	Subject  string                 `json:"sub,omitempty"`
+	UID      string                 `json:"uid,omitempty"`
+	Claims   map[string]interface{} `json:"-"`
+}
+
 // VerifyIDToken verifies the signature	and payload of the provided ID token.
 //
 // VerifyIDToken accepts a signed JWT token string, and verifies that it is current, issued for the
 // correct Firebase project, and signed by the Google Firebase services in the cloud. It returns
 // a Token containing the decoded claims in the input JWT. See
 // https://firebase.google.com/docs/auth/admin/verify-id-tokens#retrieve_id_tokens_on_clients for
 // more details on how to obtain an ID token in a client app.
-// This does not check whether or not the token has been revoked. See `VerifyIDTokenAndCheckRevoked` below.
+//
+// This function does not make any RPC calls most of the time. The only time it makes an RPC call
+// is when Google public keys need to be refreshed. These keys get cached up to 24 hours, and
+// therefore the RPC overhead gets amortized over many invocations of this function.
+//
+// This does not check whether or not the token has been revoked. Use `VerifyIDTokenAndCheckRevoked()`
+// when a revocation check is needed.
 func (c *Client) VerifyIDToken(ctx context.Context, idToken string) (*Token, error) {
-	if c.projectID == "" {
-		return nil, errors.New("project id not available")
-	}
-	if idToken == "" {
-		return nil, fmt.Errorf("id token must be a non-empty string")
-	}
-
-	segments := strings.Split(idToken, ".")
-
-	var (
-		header  jwtHeader
-		payload Token
-		claims  map[string]interface{}
-	)
-	if err := decode(segments[0], &header); err != nil {
-		return nil, err
-	}
-	if err := decode(segments[1], &payload); err != nil {
-		return nil, err
-	}
-	if err := decode(segments[1], &claims); err != nil {
-		return nil, err
-	}
-	// Delete standard claims from the custom claims maps.
-	for _, r := range []string{"iss", "aud", "exp", "iat", "sub", "uid"} {
-		delete(claims, r)
-	}
-	payload.Claims = claims
-
-	projectIDMsg := "make sure the ID token comes from the same Firebase project as the credential used to" +
-		" authenticate this SDK"
-	verifyTokenMsg := "see https://firebase.google.com/docs/auth/admin/verify-id-tokens for details on how to " +
-		"retrieve a valid ID token"
-	issuer := issuerPrefix + c.projectID
-
-	var err error
-	if header.KeyID == "" {
-		if payload.Audience == firebaseAudience {
-			err = fmt.Errorf("expected an ID token but got a custom token")
-		} else {
-			err = fmt.Errorf("ID token has no 'kid' header")
-		}
-	} else if header.Algorithm != "RS256" {
-		err = fmt.Errorf("ID token has invalid algorithm; expected 'RS256' but got %q; %s",
-			header.Algorithm, verifyTokenMsg)
-	} else if payload.Audience != c.projectID {
-		err = fmt.Errorf("ID token has invalid 'aud' (audience) claim; expected %q but got %q; %s; %s",
-			c.projectID, payload.Audience, projectIDMsg, verifyTokenMsg)
-	} else if payload.Issuer != issuer {
-		err = fmt.Errorf("ID token has invalid 'iss' (issuer) claim; expected %q but got %q; %s; %s",
-			issuer, payload.Issuer, projectIDMsg, verifyTokenMsg)
-	} else if (payload.IssuedAt - clockSkewSeconds) > c.clock.Now().Unix() {
-		err = fmt.Errorf("ID token issued at future timestamp: %d", payload.IssuedAt)
-	} else if (payload.Expires + clockSkewSeconds) < c.clock.Now().Unix() {
-		err = fmt.Errorf("ID token has expired at: %d", payload.Expires)
-	} else if payload.Subject == "" {
-		err = fmt.Errorf("ID token has empty 'sub' (subject) claim; %s", verifyTokenMsg)
-	} else if len(payload.Subject) > 128 {
-		err = fmt.Errorf("ID token has a 'sub' (subject) claim longer than 128 characters; %s", verifyTokenMsg)
-	}
-
-	if err != nil {
-		return nil, err
-	}
-	payload.UID = payload.Subject
-
-	// Verifying the signature requires syncronized access to a key store and
-	// potentially issues a http request. Validating the fields of the token is
-	// cheaper and invalid tokens will fail faster.
-	if err := verifyToken(ctx, idToken, c.keySource); err != nil {
-		return nil, err
-	}
-	return &payload, nil
+	return c.idTokenVerifier.VerifyToken(ctx, idToken)
 }
 
-// VerifyIDTokenAndCheckRevoked verifies the provided ID token and checks it has not been revoked.
+// VerifyIDTokenAndCheckRevoked verifies the provided ID token, and additionally checks that the
+// token has not been revoked.
 //
-// VerifyIDTokenAndCheckRevoked verifies the signature and payload of the provided ID token and
-// checks that it wasn't revoked. Uses VerifyIDToken() internally to verify the ID token JWT.
+// This function uses `VerifyIDToken()` internally to verify the ID token JWT. However, unlike
+// `VerifyIDToken()` this function must make an RPC call to perform the revocation check.
+// Developers are advised to take this additional overhead into consideration when including this
+// function in an authorization flow that gets executed often.
 func (c *Client) VerifyIDTokenAndCheckRevoked(ctx context.Context, idToken string) (*Token, error) {
 	p, err := c.VerifyIDToken(ctx, idToken)
 	if err != nil {