Support verification of AppCheck token in Callable Functions (#885)

Callable Functions will now verify the AppCheck token included in the X-Firebase-AppCheck request header. Similar to auth, Callable Function will return 401 Unauthorized if the AppCheck token is invalid.

Author: taeold

CHANGELOG.md

@@ -1,2 +1,3 @@
 - Functions may now be deployed with 8GB RAM
 - Functions may now be deployed to europe-central2 (Warsaw)
+- Add support for validating AppCheck tokens for Callable Functions

package-lock.json

@@ -58,10 +58,11 @@
     "chai": "^4.2.0",
     "chai-as-promised": "^7.1.1",
     "child-process-promise": "^2.2.1",
-    "firebase-admin": "^8.2.0",
+    "firebase-admin": "^9.8.0",
     "js-yaml": "^3.13.1",
     "jsdom": "^16.2.1",
     "jsonwebtoken": "^8.5.1",
+    "jwk-to-pem": "^2.0.5",
     "mocha": "^6.1.4",
     "mock-require": "^3.0.3",
     "mz": "^2.7.0",

package.json

@@ -0,0 +1,14 @@
+{
+  "p": "9cTVRzGXbDfhIMQW9gXtWveDW0u_Hvwnbjx7TRPgSfawZ0MjgKfSbnyHTDXiqM1ifcN_Nk58KJ-PG9eZ7V7_mfTUnPv2puDaecn-kgHobnTJMoBR9hpzyyMpyNJuMvX4kqE7Qh8iFMBK_-p8ICiW15gK5WykswIKfIOkUZc52XM",
+  "kty": "RSA",
+  "q": "pYdUNL244sCoc4XrONKlu787AiHrjFFLHdTjoFLbvxSpszXM8iSjoiFAM_MCF-uWks2iBVDw9wlG4MB7MfNf_fD0i1wqyknSOtfMxknU7D4eU_Sp6tI99Jl8f_GAzODK__k_0MpqqXgZmJbUvYuIXMiha-5lddz8ENa4pYpbr7M",
+  "d": "MpkXqjmjvzwfmlq3o0uZAXjeeAnBlYQSNaSllBWKepgPjg4FxFIt_BlXex1NeP0npNy_oCgaM_x7NiALaaPhwPK52lhYThc-xomCic1KDkyPecODTPXi4Iw94Q_gp442SYMWz2ZktS-2DgXc3599fGHkY80u0rHNSO8ptdk8SUDUIZ82ZQ3pBhClF_uY3c1jZLuqVgCwKksInZmNPnv3ge088wmQC26t0Ph5u1HU6lISgaqZ8ol23iNWJPf4UEi8Twy1a73nphQS-y1yK9UC3c5Knk-WI2TMmjlxqC02ZjKqnRDxElTj9kpodasPRHRV_KJI8rTaStgxd7peMFODzQ",
+  "e": "AQAB",
+  "use": "sig",
+  "kid": "a12KBE",
+  "qi": "aJCrZVWeOjxYmMBTTI7aJhxcvvfS3I5Q7wwN4Oyb1rJZ4fgGYjDohlzeZz_3fNantPAgcDbzJfa3XS327sHJGaAVqvDugZUgyHeLZGzXGs-_mlL72wzcfvTa1C9_lIndLNZJle5_mg3xJAqRKV0s7kymSdYt0wL5fDaqo5SDNqQ",
+  "dp": "haBk2hWzoApt5HPZjCDC4g_rosr3enBdPAm0fL8O1whC95JAjmYw-xPIOH6f42nwYDLYSv23chr3I4tBTRe2382HgGdav3dIMqnKOTbCWrQy5LtyVN4jEVLoGCGZ-ylT4t25K4Vj8WZwIN8saAvJoCUx33YHwrCcZQDqadZQhNM",
+  "alg": "RS256",
+  "dq": "j6NdeN7hnzMbehPNyGNSmhcZd4JDymGI03w3gpokQi4GDJM1IzKUJE7CTdIkEOnIod97Jy3TzCrqrIGa5f-RXuVG79-s6hkhKxq0gaTz9YT6AFShVjnWtXizRrskz6SJw5JgxCfCYwjq_TR1q313eTxIh0Y6GQsIWPxbApuLcG0",
+  "n": "nunJGpOcPvVsP3q-NLgf3H6OycPhnXUxywMR2_H_JJP7BUIDSsYcOGBTFe7OphHYfyb1Gs14yAER243swndpNbQkuDJhj9a9kK6dJZmPGmvCySk_E5URj6MimZg1MBbwhsVAbRp2uerESZuoRrfdTdV87E3pGyg6Irl0IXRjy5w9SsFjjIi7E-Qxpf3TcNNjfVRLj9V2bSzmS7hlsPKBhDon0tWecuNKoNNMiGI46mz_MSUa2y1lPV6Cqhf1su_TRd7N7u9eP7xWArr7wqtqHiFTZ3qp1xoA_dr_xv_Ao2kBtohZiAFLV-PQShprSN5fafztRZFkSEF0m2tUkvmoaQ"
+}

spec/fixtures/credential/jwk.json

@@ -1,7 +1,9 @@
 import * as jwt from 'jsonwebtoken';
+import * as jwkToPem from 'jwk-to-pem';
 import * as _ from 'lodash';
 import * as nock from 'nock';
-import * as mocks from '../fixtures/credential/key.json';
+import * as mockKey from '../fixtures/credential/key.json';
+import * as mockJWK from '../fixtures/credential/jwk.json';
 
 // MockRequest mocks an https.Request.
 export class MockRequest {
@@ -26,6 +28,7 @@ export function mockRequest(
   context: {
     authorization?: string;
     instanceIdToken?: string;
+    appCheckToken?: string;
   } = {}
 ) {
   const body: any = {};
@@ -37,6 +40,7 @@ export function mockRequest(
     'content-type': contentType,
     authorization: context.authorization,
     'firebase-instance-id-token': context.instanceIdToken,
+    'x-firebase-appcheck': context.appCheckToken,
     origin: 'example.com',
   };
 
@@ -53,7 +57,7 @@ export const expectedResponseHeaders = {
  * verifying an id token.
  */
 export function mockFetchPublicKeys(): nock.Scope {
-  const mockedResponse = { [mocks.key_id]: mocks.public_key };
+  const mockedResponse = { [mockKey.key_id]: mockKey.public_key };
   const headers = {
     'cache-control': 'public, max-age=1, must-revalidate, no-transform',
   };
@@ -72,11 +76,48 @@ export function generateIdToken(projectId: string): string {
     audience: projectId,
     expiresIn: 60 * 60, // 1 hour in seconds
     issuer: 'https://securetoken.google.com/' + projectId,
-    subject: mocks.user_id,
+    subject: mockKey.user_id,
     algorithm: 'RS256',
     header: {
-      kid: mocks.key_id,
+      kid: mockKey.key_id,
     },
   };
-  return jwt.sign(claims, mocks.private_key, options);
+  return jwt.sign(claims, mockKey.private_key, options);
+}
+
+/**
+ * Mocks out the http request used by the firebase-admin SDK to get the jwks for
+ * verifying an AppCheck token.
+ */
+export function mockFetchAppCheckPublicJwks(): nock.Scope {
+  const { kty, use, alg, kid, n, e } = mockJWK;
+  const mockedResponse = {
+    keys: [{ kty, use, alg, kid, n, e }],
+  };
+
+  return nock('https://firebaseappcheck.googleapis.com:443')
+    .get('/v1beta/jwks')
+    .reply(200, mockedResponse);
+}
+
+/**
+ * Generates a mocked AppCheck token.
+ */
+export function generateAppCheckToken(
+  projectId: string,
+  appId: string
+): string {
+  const claims = {};
+  const options: jwt.SignOptions = {
+    audience: [`projects/${projectId}`],
+    expiresIn: 60 * 60, // 1 hour in seconds
+    issuer: `https://firebaseappcheck.googleapis.com/${projectId}`,
+    subject: appId,
+    header: {
+      alg: 'RS256',
+      typ: 'JWT',
+      kid: mockJWK.kid,
+    },
+  };
+  return jwt.sign(claims, jwkToPem(mockJWK, { private: true }), options);
 }

spec/fixtures/mockrequest.ts

@@ -30,7 +30,9 @@ import * as https from '../../src/providers/https';
 import * as mocks from '../fixtures/credential/key.json';
 import {
   expectedResponseHeaders,
+  generateAppCheckToken,
   generateIdToken,
+  mockFetchAppCheckPublicJwks,
   mockFetchPublicKeys,
   MockRequest,
   mockRequest,
@@ -414,6 +416,58 @@ describe('callable.FunctionBuilder', () => {
       });
     });
 
+    it('should handle AppCheck token', async () => {
+      const mock = mockFetchAppCheckPublicJwks();
+      const projectId = appsNamespace().admin.options.projectId;
+      const appId = '1:65211879909:web:3ae38ef1cdcb2e01fe5f0c';
+      const appCheckToken = generateAppCheckToken(projectId, appId);
+      await runTest({
+        httpRequest: mockRequest(null, 'application/json', { appCheckToken }),
+        expectedData: null,
+        callableFunction: (data, context) => {
+          expect(context.app).to.not.be.undefined;
+          expect(context.app).to.not.be.null;
+          expect(context.app.appId).to.equal(appId);
+          expect(context.app.token.app_id).to.be.equal(appId);
+          expect(context.app.token.sub).to.be.equal(appId);
+          expect(context.app.token.aud).to.be.deep.equal([
+            `projects/${projectId}`,
+          ]);
+          expect(context.auth).to.be.undefined;
+          expect(context.instanceIdToken).to.be.undefined;
+          return null;
+        },
+        expectedHttpResponse: {
+          status: 200,
+          headers: expectedResponseHeaders,
+          body: { result: null },
+        },
+      });
+      mock.done();
+    });
+
+    it('should reject bad AppCheck token', async () => {
+      await runTest({
+        httpRequest: mockRequest(null, 'application/json', {
+          appCheckToken: 'FAKE',
+        }),
+        expectedData: null,
+        callableFunction: (data, context) => {
+          return;
+        },
+        expectedHttpResponse: {
+          status: 401,
+          headers: expectedResponseHeaders,
+          body: {
+            error: {
+              status: 'UNAUTHENTICATED',
+              message: 'Unauthenticated',
+            },
+          },
+        },
+      });
+    });
+
     it('should handle instance id', async () => {
       await runTest({
         httpRequest: mockRequest(null, 'application/json', {

spec/providers/https.spec.ts

@@ -28,7 +28,7 @@ import * as _ from 'lodash';
 import { apps } from '../apps';
 import { HttpsFunction, optionsToTrigger, Runnable } from '../cloud-functions';
 import { DeploymentOptions } from '../function-configuration';
-import { warn, error } from '../logger';
+import { error, info, warn } from '../logger';
 
 /** @hidden */
 export interface Request extends express.Request {
@@ -248,6 +248,14 @@ export class HttpsError extends Error {
  * The interface for metadata for the API as passed to the handler.
  */
 export interface CallableContext {
+  /**
+   * The result of decoding and verifying a Firebase AppCheck token.
+   */
+  app?: {
+    appId: string;
+    token: firebase.appCheck.DecodedAppCheckToken;
+  };
+
   /**
    * The result of decoding and verifying a Firebase Auth ID token.
    */
@@ -411,6 +419,108 @@ export function decode(data: any): any {
   return data;
 }
 
+/**
+ * Be careful when changing token status values.
+ *
+ * Users are encouraged to setup log-based metric based on these values, and
+ * changing their values may cause their metrics to break.
+ *
+ */
+/** @hidden */
+type TokenStatus = 'MISSING' | 'VALID' | 'INVALID';
+
+/** @hidden */
+interface CallableTokenStatus {
+  app: TokenStatus;
+  auth: TokenStatus;
+}
+
+/**
+ * Check and verify tokens included in the requests. Once verified, tokens
+ * are injected into the callable context.
+ *
+ * @param {Request} req - Request sent to the Callable function.
+ * @param {CallableContext} ctx - Context to be sent to callable function handler.
+ * @return {CallableTokenStatus} Status of the token verifications.
+ */
+/** @hidden */
+async function checkTokens(
+  req: Request,
+  ctx: CallableContext
+): Promise<CallableTokenStatus> {
+  const verifications: CallableTokenStatus = {
+    app: 'MISSING',
+    auth: 'MISSING',
+  };
+
+  const appCheck = req.header('X-Firebase-AppCheck');
+  if (appCheck) {
+    verifications.app = 'INVALID';
+    try {
+      if (!apps().admin.appCheck) {
+        throw new Error(
+          'Cannot validate AppCheck token. Please uupdate Firebase Admin SDK to >= v9.8.0'
+        );
+      }
+      const appCheckToken = await apps()
+        .admin.appCheck()
+        .verifyToken(appCheck);
+      ctx.app = {
+        appId: appCheckToken.appId,
+        token: appCheckToken.token,
+      };
+      verifications.app = 'VALID';
+    } catch (err) {
+      warn('Failed to validate AppCheck token.', err);
+    }
+  }
+
+  const authorization = req.header('Authorization');
+  if (authorization) {
+    verifications.auth = 'INVALID';
+    const match = authorization.match(/^Bearer (.*)$/);
+    if (match) {
+      const idToken = match[1];
+      try {
+        const authToken = await apps()
+          .admin.auth()
+          .verifyIdToken(idToken);
+
+        verifications.auth = 'VALID';
+        ctx.auth = {
+          uid: authToken.uid,
+          token: authToken,
+        };
+      } catch (err) {
+        warn('Failed to validate auth token.', err);
+      }
+    }
+  }
+
+  const logPayload = {
+    verifications,
+    'logging.googleapis.com/labels': {
+      'firebase-log-type': 'callable-request-verification',
+    },
+  };
+
+  const errs = [];
+  if (verifications.app === 'INVALID') {
+    errs.push('AppCheck token was rejected.');
+  }
+  if (verifications.auth === 'INVALID') {
+    errs.push('Auth token was rejected.');
+  }
+
+  if (errs.length == 0) {
+    info('Callable request verification passed', logPayload);
+  } else {
+    warn(`Callable request verification failed: ${errs.join(' ')}`, logPayload);
+  }
+
+  return verifications;
+}
+
 /** @hidden */
 const corsHandler = cors({ origin: true, methods: 'POST' });
 
@@ -427,25 +537,9 @@ export function _onCallWithOptions(
       }
 
       const context: CallableContext = { rawRequest: req };
-
-      const authorization = req.header('Authorization');
-      if (authorization) {
-        const match = authorization.match(/^Bearer (.*)$/);
-        if (!match) {
-          throw new HttpsError('unauthenticated', 'Unauthenticated');
-        }
-        const idToken = match[1];
-        try {
-          const authToken = await apps()
-            .admin.auth()
-            .verifyIdToken(idToken);
-          context.auth = {
-            uid: authToken.uid,
-            token: authToken,
-          };
-        } catch (err) {
-          throw new HttpsError('unauthenticated', 'Unauthenticated');
-        }
+      const tokenStatus = await checkTokens(req, context);
+      if (tokenStatus.app === 'INVALID' || tokenStatus.auth === 'INVALID') {
+        throw new HttpsError('unauthenticated', 'Unauthenticated');
       }
 
       const instanceId = req.header('Firebase-Instance-ID-Token');

src/providers/https.ts

@@ -1,13 +1,13 @@
 {
   "compilerOptions": {
     "declaration": true,
-    "lib": ["es2017"],
+    "lib": ["es2018"],
     "module": "commonjs",
     "noImplicitAny": false,
     "noUnusedLocals": true,
     "outDir": "lib",
     "stripInternal": true,
-    "target": "es2017",
+    "target": "es2018",
     "typeRoots": ["./node_modules/@types"]
   },
   "files": ["./src/index.ts", "./src/logger.ts", "./src/logger/compat.ts"]