用戶認(rèn)證)
前言用 JWTJSON Web Token做接口認(rèn)證的項目出問題的姿勢高度雷同本地一切正常上線后要么是「令牌永遠(yuǎn)不過期」要么是「用戶改了密碼舊令牌照樣能用」最糟糕的一種是安全掃描直接報出「簽名可繞過」。根因通常不在 JWT 本身而在于把它當(dāng)成了一個「加密過的 cookie」。JWT 的前兩段header 與 payload只是 Base64URL 編碼任何人拿到令牌就能解開、看到里面的全部內(nèi)容安全邊界完全落在第三段的簽名上。一旦簽名校驗寫錯——用比較、不限定算法、拿到false不看——JWT 就退化成一個可以任意偽造的明文 JSON。還需要先澄清一點JWT 不是 PHP 的語言特性PHP 8.1 并沒有為它引入任何東西。它是一套令牌格式規(guī)范你既可以用hash_hmac()手寫也可以用firebase/php-jwt之類的庫。8.1 能幫上忙的只是語法層面枚舉enumPHP 8.1、readonly提升屬性PHP 8.1、never返回類型PHP 8.1這些能讓簽發(fā)與校驗的代碼少踩幾個字面量拼錯的坑。本文先講清 JWT 的簽名原理再給出一個不依賴任何第三方庫、純hash_hmac()實現(xiàn)的完整可運行示例含篡改檢測與過期檢測最后說明接入firebase/php-jwt與框架集成時的注意事項。一、JWT 的三段結(jié)構(gòu)與簽名原理一個 JWT 長這樣用兩個點分成三段eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MiIsImV4cCI6MTc2MDAwMDAwMH0.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk段名稱內(nèi)容是否保密第 1 段header{alg:HS256,typ:JWT}的 Base64URL否可解碼第 2 段payload聲明claimssub、exp、iat、role等否可解碼第 3 段signature對前兩段的簽名是但不可逆只能驗不能解簽名的計算方式是signature HMAC-SHA256( base64url(header) . . . base64url(payload) , secret )三個關(guān)鍵推論也是后面所有坑點的來源payload 不是加密的。把密碼、手機(jī)號、身份證號放進(jìn) payload等于把它們貼在瀏覽器地址欄上。Base64 不是加密。簽名只保證「沒被改過」不保證「沒被別人看過」。需要保密就上 JWEJSON Web Encryption或者干脆別把敏感數(shù)據(jù)放進(jìn)去。驗證必須用「先重算再定長比較」的方式而且重算時用的算法必須是服務(wù)端白名單里的算法絕不能聽 header 里alg字段的。Base64URL 是 Base64 的變體換成-、/換成_并去掉末尾的填充以便安全地放進(jìn) URL、cookie 與 HTTP 頭。很多「令牌一放進(jìn) URL 就失效」的問題就是忘了這一步轉(zhuǎn)換。二、PHP 8.1 下用 hash_hmac 手寫簽發(fā)與校驗不依賴庫的版本只有一百來行而且把每個校驗點都擺在明面上?php declare(strict_types1); // 最低 PHP 8.1用到了 enum、readonly 屬性提升、never 返回類型、array_is_list final class JwtError extends RuntimeException {} /** 用戶角色枚舉讓「字符串寫錯」在靜態(tài)分析階段就暴露 */ enum Role: string { case User user; case Admin admin; } /** * 解碼后的令牌載荷。 * 用 readonly 提升屬性PHP 8.1 特性注意不是 readonly 類——那是 PHP 8.2 才有的 * 保證拿到手后不會被意外改寫。 */ final class Claims { public function __construct( public readonly int $sub, public readonly Role $role, public readonly int $exp, public readonly int $iat, ) {} } /** * 支持的算法白名單alg 名字 hash_hmac 的算法名 * 只允許 HS 系列杜絕 RS256/HS256 混淆與 algnone */ const JWT_ALGS [ HS256 sha256, HS384 sha384, HS512 sha512, ]; function base64UrlEncode(string $raw): string { return rtrim(strtr(base64_encode($raw), /, -_), ); } function base64UrlDecode(string $seg): string { $pad strlen($seg) % 4; if ($pad ! 0) { $seg . str_repeat(, 4 - $pad); // 解碼前必須補(bǔ)回填充 } $raw base64_decode(strtr($seg, -_, /), true); if ($raw false) { throw new JwtError(base64url 段解碼失敗); } return $raw; } function jwtSign(string $signingInput, string $secret, string $alg): string { if (!isset(JWT_ALGS[$alg])) { throw new JwtError(不支持的算法$alg); } return hash_hmac(JWT_ALGS[$alg], $signingInput, $secret, true); } /** * 簽發(fā)令牌。$ttl 是有效期秒數(shù)。 */ function jwtIssue(int $userId, Role $role, string $secret, int $ttl 900, string $alg HS256): string { $now time(); $header [alg $alg, typ JWT]; $payload [ sub $userId, role $role-value, iat $now, nbf $now, exp $now $ttl, ]; $h base64UrlEncode(json_encode($header, JSON_THROW_ON_ERROR)); $p base64UrlEncode(json_encode($payload, JSON_THROW_ON_ERROR)); $signingInput $h . . . $p; return $signingInput . . . base64UrlEncode(jwtSign($signingInput, $secret, $alg)); } /** * 校驗令牌。失敗一律拋 JwtError絕不返回 false 讓調(diào)用方自己猜。 */ function jwtVerify(string $jwt, string $secret, string $issuer my-app): Claims { $parts explode(., $jwt); if (count($parts) ! 3) { throw new JwtError(令牌格式不是三段); } [$h, $p, $s] $parts; $header json_decode(base64UrlDecode($h), true, 8, JSON_THROW_ON_ERROR); if (!is_array($header)) { throw new JwtError(header 不是對象); } // 關(guān)鍵算法只認(rèn)服務(wù)端白名單絕不信 header 里寫了什么 $alg $header[alg] ?? ; if (!is_string($alg) || !isset(JWT_ALGS[$alg])) { throw new JwtError(算法不在白名單內(nèi)); } $expected base64UrlEncode(jwtSign($h . . . $p, $secret, $alg)); // 關(guān)鍵定長比較不能用 或 if (!hash_equals($expected, $s)) { throw new JwtError(簽名不匹配); } $payload json_decode(base64UrlDecode($p), true, 16, JSON_THROW_ON_ERROR); if (!is_array($payload)) { throw new JwtError(payload 不是對象); } $now time(); foreach ([exp 已過期, nbf 尚未生效] as $key $msg) { if (!isset($payload[$key]) || !is_int($payload[$key])) { throw new JwtError(缺少 $key 聲明); } if ($key exp $payload[$key] $now) { throw new JwtError($msg); } if ($key nbf $payload[$key] $now) { throw new JwtError($msg); } } if (($payload[iss] ?? $issuer) ! $issuer) { throw new JwtError(簽發(fā)方不匹配); } $role Role::tryFrom((string) ($payload[role] ?? )); if ($role null) { throw new JwtError(未知角色); } return new Claims( sub: (int) $payload[sub], role: $role, exp: $payload[exp], iat: (int) $payload[iat], ); }這里有幾個刻意的設(shè)計都是踩過坑之后才加的Role用枚舉而不是字符串。校驗$claims-role Role::Admin時拼錯角色名會直接報錯而不是靜默地永遠(yuǎn)不成立。Claims用readonly類。令牌一旦驗證通過中間件把它注入后續(xù)流程后任何一層都改不動它避免「越權(quán)」來自內(nèi)部而不是外部。校驗失敗一律拋異常。返回false的接口最容易被調(diào)用方寫成if (!$ok) { /* 忘了 return */ }那才是真正的漏洞。hash_equals()。它按位比較且耗時與內(nèi)容無關(guān)。用比較簽名會被時序攻擊timing attack逐字節(jié)爆破。三、接入 firebase/php-jwt 與框架中間件生產(chǎn)項目一般直接用庫省得自己維護(hù)加密細(xì)節(jié)。下面是 6.x 的 API 形態(tài)?php declare(strict_types1); require __DIR__ . /vendor/autoload.php; use Firebase\JWT\JWT; use Firebase\JWT\Key; use Firebase\JWT\ExpiredException; use Firebase\JWT\SignatureInvalidException; $secret $_ENV[JWT_SECRET] ?? ; // 密鑰只從環(huán)境變量來絕不寫進(jìn)代碼庫 // 簽發(fā) $token JWT::encode( [sub 42, role admin, iat time(), exp time() 900], $secret, HS256 ); // 校驗 try { $decoded JWT::decode($token, new Key($secret, HS256)); echo 通過sub . $decoded-sub . PHP_EOL; } catch (ExpiredException $e) { echo 令牌過期 . PHP_EOL; } catch (SignatureInvalidException $e) { echo 簽名無效 . PHP_EOL; } catch (Throwable $e) { echo 其他失敗 . $e-getMessage() . PHP_EOL; }注意6.x 里算法由Key對象帶進(jìn)來第三個參數(shù)$allowed_algs已廢棄5.x 的decode()簽名不同請以vendor/firebase/php-jwt/src/JWT.php里的實際簽名為準(zhǔn)不要照抄博客?？蚣芾锿ǔ懗梢粋€中間件。核心邏輯只有三句從Authorization: Bearer xxx里取出令牌、校驗、把Claims掛到請求屬性上。?php declare(strict_types1); /** * 認(rèn)證失敗直接終止請求。 * never 返回類型是 PHP 8.1 新增的它告訴靜態(tài)分析器「這個函數(shù)不會正常返回」 * 因而后面不會出現(xiàn)「忘記 return 導(dǎo)致繼續(xù)往下走」的漏網(wǎng)之魚。 */ function abortUnauthorized(string $reason): never { http_response_code(401); header(Content-Type: application/json; charsetutf-8); echo json_encode([error $reason], JSON_UNESCAPED_UNICODE); exit; } function authenticate(string $authorizationHeader, string $secret): Claims { if (!str_starts_with($authorizationHeader, Bearer )) { abortUnauthorized(缺少 Bearer 令牌); } try { return jwtVerify(substr($authorizationHeader, 7), $secret); } catch (JwtError $e) { abortUnauthorized($e-getMessage()); } }其中的str_starts_with()是 PHP 8.0 引入的。校驗項必須做不做的后果簽名hash_equals()或庫的 verify令牌可任意偽造算法服務(wù)端白名單algnone、HS/RS 混淆攻擊exp與服務(wù)器時間比較令牌永久有效nbf/iat檢查是否提前生效時鐘漂移被利用iss/aud多系統(tǒng)共用密鑰時必查別家系統(tǒng)的令牌能登你的系統(tǒng)角色枚舉校驗空角色被當(dāng)成普通用戶放行四、完整可運行示例把下面這段存成jwt_demo.php直接運行它會把「正常簽發(fā)、被篡改、已過期」三種情況都跑一遍?php declare(strict_types1); // 需要 PHP 8.1。上面第二節(jié)的類與函數(shù)請一并放進(jìn)這個文件。 $secret dev-only-secret-do-not-use-in-production; // ---------- 1. 正常簽發(fā)與校驗 ---------- $token jwtIssue(1001, Role::Admin, $secret, ttl: 900); echo 令牌$token\n; $claims jwtVerify($token, $secret); printf( 校驗通過sub%d, role%s, 剩余 %d 秒\n, $claims-sub, $claims-role-value, $claims-exp - time() ); // ---------- 2. 篡改 payload把 role 改成 admin 或把 sub 改掉---------- $parts explode(., $token); $fake json_decode(base64UrlDecode($parts[1]), true, 16, JSON_THROW_ON_ERROR); $fake[sub] 1; $parts[1] base64UrlEncode(json_encode($fake, JSON_THROW_ON_ERROR)); $tampered implode(., $parts); try { jwtVerify($tampered, $secret); echo 嚴(yán)重問題篡改后的令牌居然通過了\n; } catch (JwtError $e) { echo 篡改被攔下{$e-getMessage()}\n; } // ---------- 3. 過期令牌 ---------- $expired jwtIssue(1001, Role::User, $secret, ttl: -10); try { jwtVerify($expired, $secret); echo 嚴(yán)重問題過期令牌居然通過了\n; } catch (JwtError $e) { echo 過期被攔下{$e-getMessage()}\n; } // ---------- 4. 換個密鑰再驗?zāi)M密鑰輪換后的舊令牌是否還能用---------- try { jwtVerify($token, another-secret); echo 嚴(yán)重問題錯誤密鑰居然通過了\n; } catch (JwtError $e) { echo 錯誤密鑰被攔下{$e-getMessage()}\n; }預(yù)期輸出令牌eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... 校驗通過sub1001, roleadmin, 剩余 900 秒 篡改被攔下簽名不匹配 過期被攔下已過期 錯誤密鑰被攔下簽名不匹配常見坑點1. 用或比較簽名?if ($expected $signature) { ... }—— 字符串比較會在第一個不同字節(jié)處提前返回攻擊者可以按位試探簽名這是典型的時序攻擊。 ?if (hash_equals($expected, $signature)) { ... }定長比較耗時與內(nèi)容無關(guān)。2. 直接相信 header 里的alg?$alg $header[alg]; $sig hash_hmac($alg, ...);—— 攻擊者把a(bǔ)lg改成none或者把 RS256 改成 HS256 讓你用公鑰當(dāng) HMAC 密鑰去驗簽。 ? 只認(rèn)服務(wù)端硬編碼的白名單數(shù)組isset(JWT_ALGS[$alg])不通過就直接拒。3. 用普通 base64 而不是 base64url?base64_encode($payload)—— 輸出里的/放進(jìn) URL 或 cookie 會被轉(zhuǎn)義、截斷令牌時靈時不靈。 ? 編碼時strtr($s, /, -_)再去掉解碼時先把-_換回來并補(bǔ)上填充。4. 把敏感信息放進(jìn) payload? 把密碼哈希、手機(jī)號、訂單金額寫進(jìn) claims —— 只做了一次 base64任何抓包的人都能讀到。 ? payload 只放標(biāo)識和授權(quán)所需的最小信息用戶 ID、角色、過期時間敏感數(shù)據(jù)按需查庫。5. 只驗簽名不驗exp?JWT::decode()之后直接取出sub就用。庫的校驗再全也擋不住你自己簽出exp缺失的歷史令牌。 ? 顯式檢查exp、nbf、iss、aud把exp當(dāng)作必填字段缺失即拒。6. HMAC 密鑰是短口令?$secret myapp2024;—— 這種密鑰可以被離線爆破一旦爆破成功攻擊者就能自己簽發(fā)管理員令牌。 ? 用bin2hex(random_bytes(32))生成密鑰存進(jìn)環(huán)境變量或密鑰管理服務(wù)并支持輪換同時接受新舊兩把密鑰一段時間。7. 以為「無狀態(tài)」就等于「不能登出」? 用戶點了退出前端刪掉令牌就完事服務(wù)端手里的舊令牌還能一直用到過期。 ? access token 設(shè)短幾分鐘到十幾分鐘配一個可撤銷的 refresh token需要即時失效就維護(hù)jti黑名單RedisTTL 設(shè)為令牌剩余壽命。8. 令牌放 localStorage 又忘了 cookie 的安全屬性? 前端把令牌存 localStorage任何一次 XSS 都能直接偷走或者放 cookie 但不設(shè)HttpOnlySecureSameSite。 ? 放 cookie 時設(shè)HttpOnly、Secure、SameSiteLax配合 CSRF 防護(hù)堅持用 localStorage 就必須嚴(yán)格控制 XSS?？偨Y(jié)環(huán)節(jié)做法要點令牌格式header.payload.signature 三段 Base64URLpayload 不保密簽名HMAC-SHA256 hash_hmac()密鑰隨機(jī)且長比較hash_equals()防時序攻擊算法服務(wù)端白名單防algnone與算法混淆聲明exp/nbf/iss/aud全查缺一即拒有效期access 短 refresh 可撤銷兼顧安全與體驗傳輸cookie 加HttpOnly/Secure/SameSite防 XSS 與 CSRFJWT 本身并不復(fù)雜坑幾乎全在「校驗環(huán)節(jié)偷懶」上。把簽名比較換成hash_equals()、把算法固化成白名單、把exp當(dāng)成必填項、把密鑰挪進(jìn)環(huán)境變量——這四件事做完P(guān)HP 8.1 下的 JWT 認(rèn)證就比大多數(shù)出過事的項目更穩(wěn)。如果你的服務(wù)沒有跨端、跨域、無狀態(tài)橫向擴(kuò)展的需求傳統(tǒng)的服務(wù)端 Session 往往更簡單也更安全。 PHP8.1怎么使用JWT實現(xiàn)用戶認(rèn)證
前言用 JWTJSON Web Token做接口認(rèn)證的項目出問題的姿勢高度雷同本地一切正常上線后要么是「令牌永遠(yuǎn)不過期」要么是「用戶改了密碼舊令牌照樣能用」最糟糕的一種是安全掃描直接報出「簽名可繞過」。根因通常不在 JWT 本身而在于把它當(dāng)成了一個「加密過的 cookie」。JWT 的前兩段header 與 payload只是 Base64URL 編碼任何人拿到令牌就能解開、看到里面的全部內(nèi)容安全邊界完全落在第三段的簽名上。一旦簽名校驗寫錯——用比較、不限定算法、拿到false不看——JWT 就退化成一個可以任意偽造的明文 JSON。還需要先澄清一點JWT 不是 PHP 的語言特性PHP 8.1 并沒有為它引入任何東西。它是一套令牌格式規(guī)范你既可以用hash_hmac()手寫也可以用firebase/php-jwt之類的庫。8.1 能幫上忙的只是語法層面枚舉enumPHP 8.1、readonly提升屬性PHP 8.1、never返回類型PHP 8.1這些能讓簽發(fā)與校驗的代碼少踩幾個字面量拼錯的坑。本文先講清 JWT 的簽名原理再給出一個不依賴任何第三方庫、純hash_hmac()實現(xiàn)的完整可運行示例含篡改檢測與過期檢測最后說明接入firebase/php-jwt與框架集成時的注意事項。一、JWT 的三段結(jié)構(gòu)與簽名原理一個 JWT 長這樣用兩個點分成三段eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MiIsImV4cCI6MTc2MDAwMDAwMH0.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk段名稱內(nèi)容是否保密第 1 段header{alg:HS256,typ:JWT}的 Base64URL否可解碼第 2 段payload聲明claimssub、exp、iat、role等否可解碼第 3 段signature對前兩段的簽名是但不可逆只能驗不能解簽名的計算方式是signature HMAC-SHA256( base64url(header) . . . base64url(payload) , secret )三個關(guān)鍵推論也是后面所有坑點的來源payload 不是加密的。把密碼、手機(jī)號、身份證號放進(jìn) payload等于把它們貼在瀏覽器地址欄上。Base64 不是加密。簽名只保證「沒被改過」不保證「沒被別人看過」。需要保密就上 JWEJSON Web Encryption或者干脆別把敏感數(shù)據(jù)放進(jìn)去。驗證必須用「先重算再定長比較」的方式而且重算時用的算法必須是服務(wù)端白名單里的算法絕不能聽 header 里alg字段的。Base64URL 是 Base64 的變體換成-、/換成_并去掉末尾的填充以便安全地放進(jìn) URL、cookie 與 HTTP 頭。很多「令牌一放進(jìn) URL 就失效」的問題就是忘了這一步轉(zhuǎn)換。二、PHP 8.1 下用 hash_hmac 手寫簽發(fā)與校驗不依賴庫的版本只有一百來行而且把每個校驗點都擺在明面上?php declare(strict_types1); // 最低 PHP 8.1用到了 enum、readonly 屬性提升、never 返回類型、array_is_list final class JwtError extends RuntimeException {} /** 用戶角色枚舉讓「字符串寫錯」在靜態(tài)分析階段就暴露 */ enum Role: string { case User user; case Admin admin; } /** * 解碼后的令牌載荷。 * 用 readonly 提升屬性PHP 8.1 特性注意不是 readonly 類——那是 PHP 8.2 才有的 * 保證拿到手后不會被意外改寫。 */ final class Claims { public function __construct( public readonly int $sub, public readonly Role $role, public readonly int $exp, public readonly int $iat, ) {} } /** * 支持的算法白名單alg 名字 hash_hmac 的算法名 * 只允許 HS 系列杜絕 RS256/HS256 混淆與 algnone */ const JWT_ALGS [ HS256 sha256, HS384 sha384, HS512 sha512, ]; function base64UrlEncode(string $raw): string { return rtrim(strtr(base64_encode($raw), /, -_), ); } function base64UrlDecode(string $seg): string { $pad strlen($seg) % 4; if ($pad ! 0) { $seg . str_repeat(, 4 - $pad); // 解碼前必須補(bǔ)回填充 } $raw base64_decode(strtr($seg, -_, /), true); if ($raw false) { throw new JwtError(base64url 段解碼失敗); } return $raw; } function jwtSign(string $signingInput, string $secret, string $alg): string { if (!isset(JWT_ALGS[$alg])) { throw new JwtError(不支持的算法$alg); } return hash_hmac(JWT_ALGS[$alg], $signingInput, $secret, true); } /** * 簽發(fā)令牌。$ttl 是有效期秒數(shù)。 */ function jwtIssue(int $userId, Role $role, string $secret, int $ttl 900, string $alg HS256): string { $now time(); $header [alg $alg, typ JWT]; $payload [ sub $userId, role $role-value, iat $now, nbf $now, exp $now $ttl, ]; $h base64UrlEncode(json_encode($header, JSON_THROW_ON_ERROR)); $p base64UrlEncode(json_encode($payload, JSON_THROW_ON_ERROR)); $signingInput $h . . . $p; return $signingInput . . . base64UrlEncode(jwtSign($signingInput, $secret, $alg)); } /** * 校驗令牌。失敗一律拋 JwtError絕不返回 false 讓調(diào)用方自己猜。 */ function jwtVerify(string $jwt, string $secret, string $issuer my-app): Claims { $parts explode(., $jwt); if (count($parts) ! 3) { throw new JwtError(令牌格式不是三段); } [$h, $p, $s] $parts; $header json_decode(base64UrlDecode($h), true, 8, JSON_THROW_ON_ERROR); if (!is_array($header)) { throw new JwtError(header 不是對象); } // 關(guān)鍵算法只認(rèn)服務(wù)端白名單絕不信 header 里寫了什么 $alg $header[alg] ?? ; if (!is_string($alg) || !isset(JWT_ALGS[$alg])) { throw new JwtError(算法不在白名單內(nèi)); } $expected base64UrlEncode(jwtSign($h . . . $p, $secret, $alg)); // 關(guān)鍵定長比較不能用 或 if (!hash_equals($expected, $s)) { throw new JwtError(簽名不匹配); } $payload json_decode(base64UrlDecode($p), true, 16, JSON_THROW_ON_ERROR); if (!is_array($payload)) { throw new JwtError(payload 不是對象); } $now time(); foreach ([exp 已過期, nbf 尚未生效] as $key $msg) { if (!isset($payload[$key]) || !is_int($payload[$key])) { throw new JwtError(缺少 $key 聲明); } if ($key exp $payload[$key] $now) { throw new JwtError($msg); } if ($key nbf $payload[$key] $now) { throw new JwtError($msg); } } if (($payload[iss] ?? $issuer) ! $issuer) { throw new JwtError(簽發(fā)方不匹配); } $role Role::tryFrom((string) ($payload[role] ?? )); if ($role null) { throw new JwtError(未知角色); } return new Claims( sub: (int) $payload[sub], role: $role, exp: $payload[exp], iat: (int) $payload[iat], ); }這里有幾個刻意的設(shè)計都是踩過坑之后才加的Role用枚舉而不是字符串。校驗$claims-role Role::Admin時拼錯角色名會直接報錯而不是靜默地永遠(yuǎn)不成立。Claims用readonly類。令牌一旦驗證通過中間件把它注入后續(xù)流程后任何一層都改不動它避免「越權(quán)」來自內(nèi)部而不是外部。校驗失敗一律拋異常。返回false的接口最容易被調(diào)用方寫成if (!$ok) { /* 忘了 return */ }那才是真正的漏洞。hash_equals()。它按位比較且耗時與內(nèi)容無關(guān)。用比較簽名會被時序攻擊timing attack逐字節(jié)爆破。三、接入 firebase/php-jwt 與框架中間件生產(chǎn)項目一般直接用庫省得自己維護(hù)加密細(xì)節(jié)。下面是 6.x 的 API 形態(tài)?php declare(strict_types1); require __DIR__ . /vendor/autoload.php; use Firebase\JWT\JWT; use Firebase\JWT\Key; use Firebase\JWT\ExpiredException; use Firebase\JWT\SignatureInvalidException; $secret $_ENV[JWT_SECRET] ?? ; // 密鑰只從環(huán)境變量來絕不寫進(jìn)代碼庫 // 簽發(fā) $token JWT::encode( [sub 42, role admin, iat time(), exp time() 900], $secret, HS256 ); // 校驗 try { $decoded JWT::decode($token, new Key($secret, HS256)); echo 通過sub . $decoded-sub . PHP_EOL; } catch (ExpiredException $e) { echo 令牌過期 . PHP_EOL; } catch (SignatureInvalidException $e) { echo 簽名無效 . PHP_EOL; } catch (Throwable $e) { echo 其他失敗 . $e-getMessage() . PHP_EOL; }注意6.x 里算法由Key對象帶進(jìn)來第三個參數(shù)$allowed_algs已廢棄5.x 的decode()簽名不同請以vendor/firebase/php-jwt/src/JWT.php里的實際簽名為準(zhǔn)不要照抄博客?？蚣芾锿ǔ懗梢粋€中間件。核心邏輯只有三句從Authorization: Bearer xxx里取出令牌、校驗、把Claims掛到請求屬性上。?php declare(strict_types1); /** * 認(rèn)證失敗直接終止請求。 * never 返回類型是 PHP 8.1 新增的它告訴靜態(tài)分析器「這個函數(shù)不會正常返回」 * 因而后面不會出現(xiàn)「忘記 return 導(dǎo)致繼續(xù)往下走」的漏網(wǎng)之魚。 */ function abortUnauthorized(string $reason): never { http_response_code(401); header(Content-Type: application/json; charsetutf-8); echo json_encode([error $reason], JSON_UNESCAPED_UNICODE); exit; } function authenticate(string $authorizationHeader, string $secret): Claims { if (!str_starts_with($authorizationHeader, Bearer )) { abortUnauthorized(缺少 Bearer 令牌); } try { return jwtVerify(substr($authorizationHeader, 7), $secret); } catch (JwtError $e) { abortUnauthorized($e-getMessage()); } }其中的str_starts_with()是 PHP 8.0 引入的。校驗項必須做不做的后果簽名hash_equals()或庫的 verify令牌可任意偽造算法服務(wù)端白名單algnone、HS/RS 混淆攻擊exp與服務(wù)器時間比較令牌永久有效nbf/iat檢查是否提前生效時鐘漂移被利用iss/aud多系統(tǒng)共用密鑰時必查別家系統(tǒng)的令牌能登你的系統(tǒng)角色枚舉校驗空角色被當(dāng)成普通用戶放行四、完整可運行示例把下面這段存成jwt_demo.php直接運行它會把「正常簽發(fā)、被篡改、已過期」三種情況都跑一遍?php declare(strict_types1); // 需要 PHP 8.1。上面第二節(jié)的類與函數(shù)請一并放進(jìn)這個文件。 $secret dev-only-secret-do-not-use-in-production; // ---------- 1. 正常簽發(fā)與校驗 ---------- $token jwtIssue(1001, Role::Admin, $secret, ttl: 900); echo 令牌$token\n; $claims jwtVerify($token, $secret); printf( 校驗通過sub%d, role%s, 剩余 %d 秒\n, $claims-sub, $claims-role-value, $claims-exp - time() ); // ---------- 2. 篡改 payload把 role 改成 admin 或把 sub 改掉---------- $parts explode(., $token); $fake json_decode(base64UrlDecode($parts[1]), true, 16, JSON_THROW_ON_ERROR); $fake[sub] 1; $parts[1] base64UrlEncode(json_encode($fake, JSON_THROW_ON_ERROR)); $tampered implode(., $parts); try { jwtVerify($tampered, $secret); echo 嚴(yán)重問題篡改后的令牌居然通過了\n; } catch (JwtError $e) { echo 篡改被攔下{$e-getMessage()}\n; } // ---------- 3. 過期令牌 ---------- $expired jwtIssue(1001, Role::User, $secret, ttl: -10); try { jwtVerify($expired, $secret); echo 嚴(yán)重問題過期令牌居然通過了\n; } catch (JwtError $e) { echo 過期被攔下{$e-getMessage()}\n; } // ---------- 4. 換個密鑰再驗?zāi)M密鑰輪換后的舊令牌是否還能用---------- try { jwtVerify($token, another-secret); echo 嚴(yán)重問題錯誤密鑰居然通過了\n; } catch (JwtError $e) { echo 錯誤密鑰被攔下{$e-getMessage()}\n; }預(yù)期輸出令牌eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... 校驗通過sub1001, roleadmin, 剩余 900 秒 篡改被攔下簽名不匹配 過期被攔下已過期 錯誤密鑰被攔下簽名不匹配常見坑點1. 用或比較簽名?if ($expected $signature) { ... }—— 字符串比較會在第一個不同字節(jié)處提前返回攻擊者可以按位試探簽名這是典型的時序攻擊。 ?if (hash_equals($expected, $signature)) { ... }定長比較耗時與內(nèi)容無關(guān)。2. 直接相信 header 里的alg?$alg $header[alg]; $sig hash_hmac($alg, ...);—— 攻擊者把a(bǔ)lg改成none或者把 RS256 改成 HS256 讓你用公鑰當(dāng) HMAC 密鑰去驗簽。 ? 只認(rèn)服務(wù)端硬編碼的白名單數(shù)組isset(JWT_ALGS[$alg])不通過就直接拒。3. 用普通 base64 而不是 base64url?base64_encode($payload)—— 輸出里的/放進(jìn) URL 或 cookie 會被轉(zhuǎn)義、截斷令牌時靈時不靈。 ? 編碼時strtr($s, /, -_)再去掉解碼時先把-_換回來并補(bǔ)上填充。4. 把敏感信息放進(jìn) payload? 把密碼哈希、手機(jī)號、訂單金額寫進(jìn) claims —— 只做了一次 base64任何抓包的人都能讀到。 ? payload 只放標(biāo)識和授權(quán)所需的最小信息用戶 ID、角色、過期時間敏感數(shù)據(jù)按需查庫。5. 只驗簽名不驗exp?JWT::decode()之后直接取出sub就用。庫的校驗再全也擋不住你自己簽出exp缺失的歷史令牌。 ? 顯式檢查exp、nbf、iss、aud把exp當(dāng)作必填字段缺失即拒。6. HMAC 密鑰是短口令?$secret myapp2024;—— 這種密鑰可以被離線爆破一旦爆破成功攻擊者就能自己簽發(fā)管理員令牌。 ? 用bin2hex(random_bytes(32))生成密鑰存進(jìn)環(huán)境變量或密鑰管理服務(wù)并支持輪換同時接受新舊兩把密鑰一段時間。7. 以為「無狀態(tài)」就等于「不能登出」? 用戶點了退出前端刪掉令牌就完事服務(wù)端手里的舊令牌還能一直用到過期。 ? access token 設(shè)短幾分鐘到十幾分鐘配一個可撤銷的 refresh token需要即時失效就維護(hù)jti黑名單RedisTTL 設(shè)為令牌剩余壽命。8. 令牌放 localStorage 又忘了 cookie 的安全屬性? 前端把令牌存 localStorage任何一次 XSS 都能直接偷走或者放 cookie 但不設(shè)HttpOnlySecureSameSite。 ? 放 cookie 時設(shè)HttpOnly、Secure、SameSiteLax配合 CSRF 防護(hù)堅持用 localStorage 就必須嚴(yán)格控制 XSS?？偨Y(jié)環(huán)節(jié)做法要點令牌格式header.payload.signature 三段 Base64URLpayload 不保密簽名HMAC-SHA256 hash_hmac()密鑰隨機(jī)且長比較hash_equals()防時序攻擊算法服務(wù)端白名單防algnone與算法混淆聲明exp/nbf/iss/aud全查缺一即拒有效期access 短 refresh 可撤銷兼顧安全與體驗傳輸cookie 加HttpOnly/Secure/SameSite防 XSS 與 CSRFJWT 本身并不復(fù)雜坑幾乎全在「校驗環(huán)節(jié)偷懶」上。把簽名比較換成hash_equals()、把算法固化成白名單、把exp當(dāng)成必填項、把密鑰挪進(jìn)環(huán)境變量——這四件事做完P(guān)HP 8.1 下的 JWT 認(rèn)證就比大多數(shù)出過事的項目更穩(wěn)。如果你的服務(wù)沒有跨端、跨域、無狀態(tài)橫向擴(kuò)展的需求傳統(tǒng)的服務(wù)端 Session 往往更簡單也更安全。