使用 Firebase AppCheck 和 reCAPTCHA 验证 Places API 请求

1. 准备工作

为确保与您的 Web 应用互动的用户是合法用户，您将实现 Firebase App Check，利用 reCAPTCHA JWT 令牌来验证用户会话。通过此设置，您可以安全地处理从客户端应用到 Places API（新版） 的请求。

b40cfddb731786fa.png

实时链接

您将构建的内容。

为了演示这一点，您将创建一个 Web 应用，该应用会在加载时显示地图。它还会使用 Firebase SDK 谨慎地生成 reCAPTCHA 令牌。然后，此令牌会发送到您的 Node.js 服务器，Firebase 会先验证该令牌，然后再满足对 Places API 的任何请求。

如果令牌有效，Firebase App Check 会存储该令牌，直到其过期，从而无需为每个客户端请求创建新令牌。如果令牌无效，系统会提示用户再次完成 reCAPTCHA 验证以获取新令牌。

2. 前提条件

您必须熟悉以下各项内容，才能完成此 Codelab。 daea823b6bc38b67.png

必需的 Google Cloud 产品

  • Google Cloud Firebase App Check：用于令牌管理的数据库
  • Google reCAPTCHA：令牌创建和验证。它是一种用于区分网站上的真人与机器人的工具。它的工作原理是分析用户行为、浏览器属性和网络信息，以生成一个分数，该分数表示用户是漫游器的可能性。如果分数足够高，则用户被视为真人，无需采取进一步操作。如果分数较低，系统可能会显示 CAPTCHA 谜题来确认用户的身份。与传统的 CAPTCHA 方法相比，这种方法侵入性较小，可让用户体验更加顺畅。
  • （可选）Google Cloud App Engine：部署环境。

必需的 Google Maps Platform 产品

在此 Codelab 中，您将使用以下 Google Maps Platform 产品：

完成此 Codelab 的其他要求

若要完成此 Codelab，您需要以下账号、服务和工具：

  • 已启用结算功能的 Google Cloud Platform 账号
  • 已启用 Maps JavaScript API 和 Places 的 Google Maps Platform API 密钥
  • 具备 JavaScript、HTML 和 CSS 方面的基础知识
  • 具备 Node.js 方面的基础知识
  • 您自己喜欢用的文本编辑器或 IDE

3. 进行设置

设置 Google Maps Platform

如果您还没有 Google Cloud Platform 账号，也没有启用了结算功能的项目，请先参阅 Google Maps Platform 使用入门指南创建一个结算账号和一个项目。

  1. 在 Cloud Console 中，点击项目下拉菜单，选择要用于此 Codelab 的项目。

e7ffad81d93745cd.png

  1. 在 Google Cloud Marketplace 中，启用此 Codelab 所需的 Google Maps Platform API 和 SDK。为此，请按照此视频或此文档中的步骤操作。
  2. 在 Cloud Console 的凭据页面中，生成 API 密钥。您可以按照此视频或此文档中的步骤操作。向 Google Maps Platform 发出的所有请求都需要 API 密钥。

应用默认凭证

您将使用 Firebase Admin SDK 与 Firebase 项目互动，并向 Places API 发出请求，因此需要提供有效的凭据才能正常运行。

我们将使用 ADC 身份验证 （自动默认凭据）对您的服务器进行身份验证以发出请求。或者（不建议）您可以创建服务账号并在代码中存储凭据。

定义：应用默认凭据 (ADC) 是 Google Cloud 提供的一种机制，用于自动对应用进行身份验证，而无需显式管理凭据。它会在各种位置（例如环境变量、服务账号文件或 Google Cloud 元数据服务器）中查找凭据，并使用找到的第一个凭据。

  • 在终端中，使用以下命令，让您的应用代表当前登录的用户安全地访问 Google Cloud 资源：
gcloud auth application-default login
  • 您将在根目录下创建一个 .env 文件，用于指定 Google Cloud 项目变量：
GOOGLE_CLOUD_PROJECT="your-project-id"

创建服务账号

凭据

  • 点击创建的服务账号
  • 前往“密钥”标签页，依次点击“创建密钥”>“JSON”>“保存下载的 JSON 凭据”。将自动下载的 xxx.json 文件移动到根文件夹中
  • （下一章）将其正确命名为 nodejs 文件 server.js (​​firebase-credentials.json)

4. Firebase AppCheck 集成

您将获取 Firebase 配置详细信息和 reCAPTCHA 密钥。

您将它们粘贴到演示应用中并启动服务器。

在 Firebase 中创建应用

选择已创建的 Google Cloud 项目（您可能需要指定：“选择父级资源”）

a6d171c6d7e98087.png a16010ba102cc90b.png

  • 从左上角的“菜单”（齿轮）中添加应用

18e5a7993ad9ea53.png 4632158304652118.png

Firebase 初始化代码

  • 保存 Firebase 初始化代码 ，以便在客户端的 script.js（下一章）中粘贴

f10dcf6f5027e9f0.png

  • 注册您的应用，以允许 Firebase 使用 reCAPTCHA v3 令牌

https://console.firebase.google.com/u/0/project/YOUR_PROJECT/appcheck/apps

da7efe203ce4142c.png

  • 选择 reCAPTCHA → 在 reCAPTCHA 网站中创建密钥（配置了正确的网域：localhost 用于应用开发）

b47eab131617467.png e6bddef9d5cf5460.png

  • 在 Firebase AppCheck 中粘贴 reCAPTCHA 密钥

a63bbd533a1b5437.png

  • 应用状态应变为绿色

4f7962b527b78ee5.png

5. 演示应用

  • 客户端 Web 应用： HTML、JavaScript、CSS 文件
  • 服务器： Node.js 文件
  • .env： API 密钥
  • 配置 (app.yaml)： Google App Engine 部署设置

Node.js 设置：

  • 导航：打开终端并导航到克隆项目的根目录。
  • 安装 Node.js（如果需要）：版本 18 或更高版本。
node -v  # Check installed version
  • 初始化项目： 运行以下命令以初始化新的 Node.js 项目，保留所有默认设置：
npm init
  • 安装依赖项： 使用以下命令安装所需的项目依赖项：
npm install @googlemaps/places firebase-admin express axios dotenv

配置：Google Cloud 项目的环境变量

  • 创建环境文件： 在项目的根目录下，创建一个名为 .env 的文件。此文件将存储敏感配置数据，不应提交到版本控制。
  • 填充环境变量： 打开 .env 文件并添加以下变量，将占位符替换为 Google Cloud 项目中的实际值：
# Google Cloud Project ID
GOOGLE_CLOUD_PROJECT="your-cloud-project-id"

# reCAPTCHA Keys (obtained in previous steps) 
RECAPTCHA_SITE_KEY="your-recaptcha-site-key"
RECAPTCHA_SECRET_KEY="your-recaptcha-secret-key"

# Maps Platform API Keys (obtained in previous steps)
PLACES_API_KEY="your-places-api-key"
MAPS_API_KEY="your-maps-api-key"

6. 代码概览

index.html

  • 加载 Firebase 库以在应用中创建令牌
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Places API with AppCheck</title>
  <style></style>  </head>
<body>
  <div id="map"></div>

    <!-- Firebase services -->
  <script src="https://www.gstatic.com/firebasejs/9.15.0/firebase-app-compat.js"></script>
  <script src="https://www.gstatic.com/firebasejs/9.15.0/firebase-app-check-compat.js"></script>
  
  <script type="module" src="./script.js"></script> 
  <link rel="stylesheet" href="./style.css">
</body>
</html>

script.js

  • 提取 API 密钥： 从后端服务器检索 Google 地图和 Firebase App Check 的 API 密钥。
  • 初始化 Firebase： 设置 Firebase 以进行身份验证和安全保护。（替换配置 → 请参阅第 4 章）。

Firebase App Check 令牌的有效期（30 分钟到 7 天）在 Firebase 控制台中配置，无法通过尝试强制刷新令牌来更改。

  • 激活 App Check： 启用 Firebase App Check 以验证传入请求的真实性。
  • 加载 Google 地图 API： 动态加载 Google Maps JavaScript 库以显示地图。
  • 初始化地图： 创建以默认位置为中心的 Google 地图。
  • 处理地图点击： 监听地图上的点击并相应地更新中心点。
  • 查询 Places API： 向后端 API (/api/data) 发送请求，以提取有关点击位置附近的地点（餐厅、公园、酒吧）的信息，并使用 Firebase App Check 进行授权。
  • 显示标记： 在地图上以标记的形式绘制提取的数据，显示其名称和图标。
let mapsApiKey, recaptchaKey; // API keys
let currentAppCheckToken = null; // AppCheck token

async function init() {
  try {
    await fetchConfig(); // Load API keys from .env variable

    /////////// REPLACE with your Firebase configuration details
    const firebaseConfig = {
      apiKey: "AIza.......",
      authDomain: "places.......",
      projectId: "places.......",
      storageBucket: "places.......",
      messagingSenderId: "17.......",
      appId: "1:175.......",
      measurementId: "G-CPQ.......",
    };
    /////////// REPLACE 

    // Initialize Firebase and App Check
    await firebase.initializeApp(firebaseConfig);
    await firebase.appCheck().activate(recaptchaKey);

    // Get the initial App Check token
    currentAppCheckToken = await firebase.appCheck().getToken();

    // Load the Maps JavaScript API dynamically
    const scriptMaps = document.createElement("script");
    scriptMaps.src = `https://maps.googleapis.com/maps/api/js?key=${mapsApiKey}&libraries=marker,places&v=beta`;
    scriptMaps.async = true;
    scriptMaps.defer = true;
    scriptMaps.onload = initMap; // Create the map after the script loads
    document.head.appendChild(scriptMaps);
  } catch (error) {
    console.error("Firebase initialization error:", error);
    // Handle the error appropriately (e.g., display an error message)
  }
}
window.onload = init()

// Fetch configuration data from the backend API
async function fetchConfig() {
  const url = "/api/config";

  try {
    const response = await fetch(url);
    const config = await response.json();
    mapsApiKey = config.mapsApiKey;
    recaptchaKey = config.recaptchaKey;
  } catch (error) {
    console.error("Error fetching configuration:", error);
    // Handle the error (e.g., show a user-friendly message)
  }
}

// Initialize the map when the Maps API script loads
let map; // Dynamic Map
let center = { lat: 48.85557501, lng: 2.34565006 };
function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: center,
    zoom: 13,
    mapId: "b93f5cef6674c1ff",
    zoomControlOptions: {
      position: google.maps.ControlPosition.RIGHT_TOP,
    },
    streetViewControl: false,
    mapTypeControl: false,
    clickableIcons: false,
    fullscreenControlOptions: {
      position: google.maps.ControlPosition.LEFT_TOP,
    },
  });

  // Initialize the info window for markers
  infoWindow = new google.maps.InfoWindow({});

  // Add a click listener to the map
  map.addListener("click", async (event) => {
    try {
      // Get a fresh App Check token on each click
      const appCheckToken = await firebase.appCheck().getToken();
      currentAppCheckToken = appCheckToken;

      // Update the center for the Places API query
      center.lat = event.latLng.lat();
      center.lng = event.latLng.lng();

      // Query for places with the new token and center
      queryPlaces();
    } catch (error) {
      console.error("Error getting App Check token:", error);
    }
  });
}

function queryPlaces() {
  const url = '/api/data'; // "http://localhost:3000/api/data"

  const body = {
    request: {
      includedTypes: ['restaurant', 'park', 'bar'],
      excludedTypes: [],
      maxResultCount: 20,
      locationRestriction: {
        circle: {
          center: {
            latitude: center.lat,
            longitude: center.lng,
          },
          radius: 4000,
        },
      },
    },
  };

  // Provides token to the backend using header: X-Firebase-AppCheck

  fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Firebase-AppCheck': currentAppCheckToken.token,
    },
    body: JSON.stringify(body),
  })
    .then((response) => response.json())
    .then((data) => {
      // display if response successful
      displayMarkers(data.places);
    })
    .catch((error) => {
      alert('No places');
      // eslint-disable-next-line no-console
      console.error('Error:', error);
    });
}


//// display places markers on map
...

server.js

  • 从 .env 文件加载环境变量 （API 密钥、Google 项目 ID）。
  • 启动服务器， 监听 http://localhost:3000 上的请求。
  • 使用应用默认凭证 (ADC) 初始化 Firebase Admin SDK 。
  • 从 script.js 接收 reCAPTCHA 令牌 。
  • 验证收到的令牌的有效性 。
  • 如果令牌有效，向 Google Places API 发出 POST 请求 ，其中包含搜索参数。
  • 处理 Places API 的响应并将其返回 给客户端。
const express = require('express');
const axios = require('axios');

const admin = require('firebase-admin');

// .env variables
require('dotenv').config();

// Store sensitive API keys in environment variables
const recaptchaSite = process.env.RECAPTCHA_SITE_KEY;
const recaptchaSecret = process.env.RECAPTCHA_SECRET_KEY;
const placesApiKey = process.env.PLACES_API_KEY;
const mapsApiKey = process.env.MAPS_API_KEY;

// Verify environment variables loaded (only during development)
console.log('recaptchaSite:', recaptchaSite, '\n');
console.log('recaptchaSecret:', recaptchaSecret, '\n');

const app = express();
app.use(express.json());

// Firebase Admin SDK setup with Application Default Credentials (ADC)
const { GoogleAuth } = require('google-auth-library');
admin.initializeApp({
  // credential: admin.credential.applicationDefault(), // optional: explicit ADC
});

// Main API Endpoint 
app.post('/api/data', async (req, res) => {
  const appCheckToken = req.headers['x-firebase-appcheck'];

  console.log("\n", "Token", "\n", "\n", appCheckToken, "\n")

  try {
    // Verify Firebase App Check token for security
    const appCheckResult = await admin.appCheck().verifyToken(appCheckToken);

    if (appCheckResult.appId) {
      console.log('App Check verification successful!');
      placesQuery(req, res);
    } else {
      console.error('App Check verification failed.');
      res.status(403).json({ error: 'App Check verification failed.' });
    }
  } catch (error) {
    console.error('Error verifying App Check token:', error);
    res.status(500).json({ error: 'Error verifying App Check token.' });
  }
});

// Function to query Google Places API
async function placesQuery(req, res) {
  console.log('#################################');
  console.log('\n', 'placesApiKey:', placesApiKey, '\n');

  const queryObject = req.body.request;
  console.log('\n','Request','\n','\n', queryObject, '\n')

  const headers = {
    'Content-Type': 'application/json',
    'X-Goog-FieldMask': '*',
    'X-Goog-Api-Key': placesApiKey,
    'Referer': 'http://localhost:3000',  // Update for production(ie.: req.hostname)
  };

  const myUrl = 'https://places.googleapis.com/v1/places:searchNearby';

  try {
    // Authenticate with ADC
    const auth = new GoogleAuth();
    const { credential } = await auth.getApplicationDefault();

    const response = await axios.post(myUrl, queryObject, { headers, auth: credential });
    
    console.log('############### SUCCESS','\n','\n','Response','\n','\n', );
    const myBody = response.data;
    myBody.places.forEach(place => {
      console.log(place.displayName); 
    });
    res.json(myBody); // Use res.json for JSON data
  } catch (error) {
    console.log('############### ERROR');
    // console.error(error); // Log the detailed error for debugging
    res.status(error.response.status).json(error.response.data); // Use res.json for errors too
  }
}

// Configuration endpoint (send safe config data to the client)
app.get('/api/config', (req, res) => {
  res.json({
    mapsApiKey: process.env.MAPS_API_KEY, 
    recaptchaKey: process.env.RECAPTCHA_SITE_KEY, 
  });
});

// Serve static files
app.use(express.static('static'));

// Start the server
const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`Server listening on port ${port}`, '\n');
});

7. 运行应用

从您选择的环境中，在终端中运行服务器，然后前往 http://localhost:3000

npm start

令牌将创建为全局变量，对用户的浏览器窗口隐藏，并传输到服务器进行处理。您可以在服务器日志中找到令牌的详细信息。

您可以在服务器日志中找到有关服务器函数以及对 Places API 附近搜索请求的响应的详细信息。

问题排查：

确保 Google 项目 ID 在设置中保持一致：

  • 在 .env 文件中（GOOGLE_CLOUD_PROJECT 变量）
  • 在终端 gcloud 配置中：
gcloud config set project your-project-id
  • 在 reCaptcha 设置中

e6bddef9d5cf5460.png

  • 在 Firebase 设置中

7e17bfbcb8007763.png

其他

  • 创建一个调试令牌，该令牌可在 script.js 中代替 reCAPTCHA 网站密钥使用，以进行测试和问题排查。

9c0beb760d13faef.png

try {
 // Initialize Firebase first
 await firebase.initializeApp(firebaseConfig);
  // Set the debug token
  if (window.location.hostname === 'localhost') { // Only in development
    await firebase.appCheck().activate(
      'YOUR_DEBUG_FIREBASE_TOKEN', // Replace with the token from the console
      true // Set to true to indicate it's a debug token
      );
  } else {
      // Activate App Check
      await firebase.appCheck().activate(recaptchaKey);
}
  • 尝试进行过多不成功的身份验证（例如使用错误的 reCAPTCHA 网站密钥）可能会触发临时限制。
FirebaseError: AppCheck: Requests throttled due to 403 error. Attempts allowed again after 01d:00m:00s (appCheck/throttled).

ADC 凭据

  • 确保您使用的是正确的 gcloud 账号
gcloud auth login
  • 确保已安装必要的库
npm install @googlemaps/places firebase-admin
  • 确保在 server.js 中加载了 Firebase 库
const {GoogleAuth} = require('google-auth-library');

gcloud auth application-default login
  • 模拟：已保存 ADC 凭据
gcloud auth application-default login --impersonate-service-account your_project@appspot.gserviceaccount.com
  • 最终在本地测试 ADC，将以下脚本另存为 test.js，然后在终端中运行：node test.js
const {GoogleAuth} = require('google-auth-library');

async function requestTestADC() {
 try {
   // Authenticate using Application Default Credentials (ADC)
   const auth = new GoogleAuth();
   const {credential} = await auth.getApplicationDefault();

   // Check if the credential is successfully obtained
   if (credential) {
     console.log('Application Default Credentials (ADC) loaded successfully!');
     console.log('Credential:', credential); // Log the credential object
   } else {
     console.error('Error: Could not load Application Default Credentials (ADC).');
   }

   // ... rest of your code ...

 } catch (error) {
   console.error('Error:', error);
 }
}

requestTestADC();

8. 好了，干得好！

后续步骤

部署到 App Engine：

  • 准备将项目部署到 Google App Engine，并进行任何必要的配置更改。
  • 使用 gcloud 命令行工具或 App Engine 控制台部署应用。

增强 Firebase Authentication：

  • 默认令牌与自定义令牌： 实现 Firebase 自定义令牌，以便更深入地使用 Firebase 服务。
  • 令牌有效期： 设置适当的令牌有效期，对于敏感操作，令牌有效期较短（自定义 Firebase 令牌最长为一小时），对于一般会话，令牌有效期较长（reCAPTCHA 令牌：30 分钟到 7 小时）。
  • 探索 reCAPTCHA 的替代方案： 调查 DeviceCheck (iOS)、SafetyNet (Android) 或 App Attest 是否适合您的安全需求。

集成 Firebase 产品：

  • Realtime Database 或 Firestore： 如果您的应用需要实时数据同步或离线功能，请与 Realtime Database 或 Firestore 集成。
  • Cloud Storage： 使用 Cloud Storage 存储和提供用户生成的内容（例如图片或视频）。
  • 身份验证： 利用 Firebase Authentication 创建用户账号、管理登录会话和处理重设密码。

扩展到移动设备：

  • Android 和 iOS： 如果您计划拥有移动应用，请为 Android 和 iOS 平台创建版本。
  • Firebase SDK： 使用适用于 Android 和 iOS 的 Firebase SDK 将 Firebase 功能无缝集成到移动应用中。