本文详解 Firebase Admin SDK 生成 custom token 与后端验证 ID token 的关键区别，指出 verifyIdToken() 不适用于 custom token，并提供从服务端签发、客户端登录、获取有效 ID token 到服务端安全校验的端到端实践方案。
本文详解 firebase admin sdk 生成 custom token 与后端验证 id token 的关键区别，指出 `verifyidtoken()` 不适用于 custom token，并提供从服务端签发、客户端登录、获取有效 id token 到服务端安全校验的端到端实践方案。
在 Firebase 身份认证体系中，“custom token” 和 “ID token” 是两类用途截然不同的 JWT：
-
Custom token：由服务端（如你的 Node.js 后端）调用
admin.auth().createCustomToken(uid, claims?)生成，仅用于客户端首次登录，本身不可被服务端直接验证； -
ID token：由客户端 Firebase SDK（如
signInWithCustomToken()成功后）自动颁发，是用户会话的有效凭证，唯一可被admin.auth().verifyIdToken()安全校验的令牌。
你当前的错误 verifyIdToken() expects an ID token, but was given a custom token 正源于混淆了二者角色——你将刚生成的 custom token 直接放入 Authorization: Bearer <custom-token></custom-token> 头部，并试图用 verifyIdToken() 校验它，这在 Firebase 架构中是非法操作。
✅ 正确流程：三步闭环验证
1️⃣ 服务端生成 custom token（你已正确实现）
// ✅ 正确：生成 custom token（仅用于客户端登录）
const customToken = await admin.auth().createCustomToken("test", { role: "third-party" });
res.json({ customToken }); // 注意：字段名应为 customToken，非 oneTimeToken2️⃣ 客户端（如 Web App）使用 custom token 登录并获取 ID token
// 前端 JS（需引入 firebase-js-sdk v9+）
import { getAuth, signInWithCustomToken, getIdToken } from "firebase/auth";
const auth = getAuth();
const customToken = "your-custom-token-from-backend"; // 从 /generate-token 接口获取
try {
await signInWithCustomToken(auth, customToken);
const idToken = await getIdToken(auth.currentUser); // ✅ 获取真正的 ID token
// 将此 idToken 发送给你的受保护 API
fetch("/api/protected", {
headers: { "Authorization": `Bearer ${idToken}` }
});
} catch (error) {
console.error("Login failed:", error);
}3️⃣ 服务端验证传入的 ID token（而非 custom token）
// ✅ 正确：验证客户端传来的 ID token
const authHeader = req.header("Authorization");
const idToken = authHeader?.split("Bearer ")[1];
if (!idToken) {
return res.status(401).json({ error: "Missing ID token" });
}
try {
const decodedToken = await admin.auth().verifyIdToken(idToken); // ✅ 现在合法
console.log("User UID:", decodedToken.uid);
console.log("Custom claims:", decodedToken.role); // 如 { role: "third-party" }
res.json({ success: true, user: decodedToken.uid });
} catch (error) {
console.error("ID token verification failed:", error);
res.status(403).json({ error: "Invalid or expired ID token" });
}⚠️ 关键注意事项
-
不要在 Postman 中直接测试 custom token：Postman 没有 Firebase 客户端上下文，无法调用
signInWithCustomToken()，因此无法获得合法 ID token。请先在真实 Web 或移动端应用中完成登录流程。 - JWT.io 验证失败是正常的：custom token 的签名密钥是 Firebase 私钥，而 JWT.io 无法访问该密钥，故显示“Invalid signature”——这不表示 token 生成错误，而是设计使然。
-
CORS 配置需匹配实际前端域名：确保
Access-Control-Allow-Origin设置为你生产环境的域名（如https://omnibill-twl.web.app），开发时可临时设为*（仅限测试）。 -
ID token 有效期为 1 小时：客户端需在过期前刷新（
getIdToken(true)强制刷新），服务端无需缓存验证结果，verifyIdToken()内部已高效处理。
遵循以上流程，即可构建安全、符合 Firebase 最佳实践的第三方服务认证链。核心牢记：custom token 是“入场券”，ID token 才是“门禁卡”——只有后者能通过后端门禁系统。
