fb_graph认证全解析：Cookie解析与Signed Request的HMAC-SHA256验证原理指南-育师

fb_graph认证全解析：Cookie解析与Signed Request的HMAC-SHA256验证原理指南

【免费下载链接】fb_graphThis gem doesn't support FB Graph API v2.0+. Please use fb_graph2 gem instead.项目地址: https://gitcode.com/gh_mirrors/fb/fb_graph

🎯fb_graph是一款经典的 Ruby gem，用于封装 Facebook Graph API。它的FbGraph::Auth类内置了两大认证方式：通过Cookie 解析获取授权码并换取 Access Token，以及对Signed Request进行HMAC-SHA256签名验证。本文带你完整理解这两种 Facebook 应用认证的底层原理。

⚠️ 注意：本 gem 不支持 FB Graph API v2.0+，新版本请使用fb_graph2。

一、两种认证方式怎么选？先看这张对比表

对比项	Cookie 解析（from_cookie）	Signed Request 验证（from_signed_request）
适用场景	JavaScript SDK 登录	Canvas 应用 / 直接携带签名请求
数据来源	`fbsr_应用ID`命名空间下的 Cookie	单独的 signed_request 参数
凭证形态	解析出`code`（授权码）	解析出`oauth_token`（Access Token）
是否请求 Facebook 换 Token	✅ 需要，POST`/oauth/access_token`	❌ 不需要，本地验证即可
核心源码	Cookie 解析类	签名请求验证类
最终产物	`FbGraph::User`+ Access Token	`FbGraph::User`+ Access Token

两者最终都会产出FbGraph::User对象和Rack::OAuth2::AccessToken，统一入口在 Auth 类：

fb_auth = FbGraph::Auth.new(YOUR_APP_ID, YOUR_APPLICATION_SECRET) fb_auth.from_cookie(cookies) # 方式一：Cookie 解析 fb_auth.from_signed_request(sr) # 方式二：Signed Request 验证

二、Cookie 解析：从浏览器 Cookie 到 Access Token

第一步：定位 fbsr_ Cookie

JavaScript SDK 登录成功后，Facebook 会把凭证写入命名 Cookie，键名为fbsr_加你的应用 ID（比如fbsr_123456789）。

FbGraph::Auth::Cookie.parse的取法很灵活：你可以传入整包 cookie 哈希，让它自己按键名取出；也可以直接传单个 cookie 字符串。如果取不到，会立即抛出VerificationFailed异常，报错信息为 "Facebook cookie not found"。

第二步：复用签名验证

Cookie 的值本质上就是一个 Signed Request，所以 Cookie 解析内部直接调用了SignedRequest.verify（详见下节），验证通过后拿到data[:code]——这就是 OAuth 授权码。

第三步：用授权码换 Access Token

from_cookie调用私有方法get_access_token!，将 code 交给 OAuth2 客户端，向 Facebook 的/oauth/access_token端点发起 POST 请求，换取真正的 Access Token，并据此构建FbGraph::User对象。如果 Facebook 返回 400/401/403，会分别映射为BadRequest、Unauthorized等具体异常，方便你精准排错。

📁 相关源码：lib/fb_graph/auth/cookie.rb、lib/fb_graph/auth.rb（get_access_token!私有方法）

三、Signed Request 验证：HMAC-SHA256 的完整流程

Signed Request 是 Facebook 用你的Application Secret对一段 JSON 数据做的 HMAC 签名凭证，格式为签名.载荷（signature.payload），用一个小数点分隔。验证过程共 5 步，全部在本地完成，一次网络请求都不用发：

1️⃣ 拆分— 按.拆成 signature 和 payload 两段，缺任意一段即抛出 "No Signature" / "No Payload" 异常。

2️⃣ Base64URL 解码— Facebook 用的是 URL 安全的 Base64 变体（-代替+，_代替/）。base64_url_decode先补齐=填充位，再替换字符集后解码。

3️⃣ JSON 解析— 解码后的 payload 是 JSON，必须包含algorithm字段且值必须等于HMAC-SHA256，否则拒绝（"Unexpected Signature Algorithm"）。

4️⃣ 重新计算签名— 用 Ruby 自带的 OpenSSL 库：

def self.sign(key, payload) klass = OpenSSL::Digest::SHA256.new OpenSSL::HMAC.digest(klass, key, payload) end

即用你的 Application Secret 作为密钥，对原始 payload 字符串（非解码后的 JSON）做 HMAC-SHA256 摘要。

5️⃣ 比对签名— 将计算结果与第 1 步解出的签名逐字节比对，不一致则抛出Signature Invalid。全部通过后才返回data，里面包含user_id、oauth_token、issued_at、expires，甚至嵌套的user对象（国家、语言、年龄段等）。

🔐安全要点：因为签名验证完全依赖 Application Secret，Secret 只应留在服务端，绝不能暴露给前端。

📁 核心源码：lib/fb_graph/auth/signed_request.rb（verify与sign方法）

四、验证失败的统一异常处理

无论哪种方式，验证不通过都会抛出FbGraph::Auth::VerificationFailed（它是BadRequest的子类）。常见的触发条件包括：

Cookie 中找不到fbsr_键
Signed Request 缺少签名或载荷
algorithm不是HMAC-SHA256
payload 不是合法 JSON
签名比对不一致

💡 建议在你的 Rails/Rack 应用中统一 rescue 这个异常，把用户重定向到未登录页面，而不是让 500 冒出来。

五、从验证到拿数据：验证通过之后做什么？

两种方式成功后，fb_auth.user就是一个FbGraph::User实例：

fb_auth.authorized? # => true，表示已有 Access Token fb_auth.user # => FbGraph::User（仅基础属性） fb_auth.user.fetch # => 拉取完整用户详情

如果你想刷新短期 Token，还可以用exchange_token!向 Facebook 换取更长效的 Access Token，这在 README 的 "Extend Access Token Lifetime" 一节有说明。

六、动手看看测试用例

这个 gem 的 spec 写得非常清晰，是学习两种认证机制最好的"活文档"：

Signed Request 验证测试：内置一条完整的真实样例 signed_request，验证签名后断言user_id、oauth_token、issued_at等字段
Cookie 解析测试：覆盖"传整包 cookie"和"传单个 cookie 字符串"两种输入
Auth 集成测试：模拟 Facebook 服务器，验证换 Token 的完整 HTTP 交互与异常分支

阅读这些 spec 里的 fixture 数据，你能直观看到一条 Signed Request 解码后长什么样。