紀錄工作經驗、相關知識,解決技術相關問題。

Javascript, 新手 Jamp Holes, 網站相關

Access Token 是什麼?存取權杖的用途,與 Bearer Token、Refresh Token 的差異

Access Token 是什麼?存取權杖的用途,與 Bearer Token、Refresh Token 的差異 特色圖片

Access Token 是什麼? Access Token(存取權杖)是用戶端向伺服器要資料時出示的憑證:伺服器看到有效的 Token,就知道這個請求已經被授權,不必每次都重新輸入帳號密碼。第一次接觸通常是在串接 API 時,文件說「請在標頭帶上 Authorization: Bearer <token>」。本文說明 Access Token 與 Bearer Token 的關係、標頭怎麼帶、伺服器怎麼回 401、Refresh Token 負責什麼,以及它和 Session Cookie 的差別,最後整理使用時的注意事項。

Access Token 是什麼:存取受保護資源的憑證

Access Token 是 OAuth 2.0 規範(RFC 6749)定義的名詞。RFC 6749 §1.4 的說明是:Access Token 是用來存取受保護資源(protected resources)的憑證,是一個代表授權的字串,對用戶端來說通常是不透明的(opaque),也就是用戶端不需要、也不該去解讀它的內容。

整個流程裡有幾個角色:

角色白話說明
用戶端(client)要存取資料的程式,例如前端網頁、手機 App
授權伺服器(authorization server)確認使用者身分後,簽發 Access Token 的一方
資源伺服器(resource server)存放受保護資料的 API,收到 Token 才放行

用戶端先從授權伺服器取得 Access Token,之後每次呼叫資源伺服器都出示它。RFC 6749 §1.4 也提到,Token 代表特定的存取範圍(scope)與期間,由資源伺服器和授權伺服器負責執行。

Token 的內容形式沒有固定。RFC 6749 §1.4 說明,它可以是一個用來查詢授權資訊的識別碼,也可以把授權資訊連同簽章一起放在字串裡(self-contained)。第二種做法最常見的格式是 JWT;JWT 的結構與驗證流程,詳細可前往〈JWT 是什麼?JSON Web Token 結構(Header、Payload、Signature)與驗證流程〉。RFC 9068 就是專門定義「用 JWT 格式簽發 OAuth 2.0 Access Token」的規範,所以 JWT 只是 Access Token 的其中一種格式,不是 Access Token 的定義本身。

Bearer Token 是什麼:誰持有,誰就能用

Bearer Token 是 Access Token 的「使用方式」。RFC 6750(OAuth 2.0 Bearer Token Usage)的摘要寫得很直接:任何持有 Bearer Token 的一方(a "bearer"),不必證明自己持有任何密鑰,就能用它取得對應的資源。

所以 Bearer Token 的特性可以濃縮成一句:Token 本身就是通行證,伺服器只看 Token,不看是誰拿來的。這跟銀行提款卡不同,提款卡還要搭配密碼;Bearer Token 比較像一張無記名的入場券,撿到的人也能入場。也因此 RFC 6750 明確要求,Bearer Token 在儲存與傳輸時都要避免外洩。

兩個名詞的關係整理如下:

名詞說的是什麼
Access Token這個 Token 的「用途」:拿來存取受保護資源
Bearer Token這個 Token 的「使用方式」:持有即可使用,用 Bearer scheme 放進 Authorization 標頭

實務上你看到的 Access Token 大多是 Bearer Token,所以兩個詞常被混用。RFC 6750 也提到,這個規範定義的是一種通用的 HTTP 授權方式,可以搭配任何來源的 Bearer Token 使用,不限於 OAuth 流程。

Authorization: Bearer 標頭怎麼帶

RFC 6750 §2.1 規定的格式是:標頭名稱 Authorization,值為 Bearer、一個以上的空白、再接 Token。規範給的範例如下:

GET /resource HTTP/1.1
Host: server.example.com
Authorization: Bearer mF_9.B5f-4.1JqM

同一節也寫明:用戶端應該(SHOULD)用這個標頭傳送 Bearer Token,資源伺服器必須(MUST)支援這個方式。MDN 的 Authorization 標頭說明頁則指出,這個標頭用來提供讓用戶端向伺服器驗證身分的憑證,Bearer 是它可搭配的驗證方式之一。

用 JavaScript 的 fetch 呼叫時,寫法是:

const res = await fetch('https://api.example.com/profile', {
  headers: { Authorization: `Bearer ${accessToken}` },
});

另外,MDN 說明這個標頭在跨來源重新導向(cross-origin redirect)時會被移除,所以請求被導向到別的網站時,Token 不會跟著送過去。

伺服器怎麼回應:401 與 WWW-Authenticate

接著看資源伺服器那一端。RFC 6750 §3 規定:請求沒帶憑證,或帶的 Token 無法存取資源時,伺服器必須回傳 WWW-Authenticate 回應標頭,驗證方式要寫 Bearer。規範給的範例是 HTTP 401 搭配 WWW-Authenticate: Bearer realm="example"。

Token 帶了但有問題時,RFC 6750 §3.1 定義了錯誤碼:

錯誤碼意思建議狀態碼
invalid_request請求缺少參數或格式不對400
invalid_tokenToken 過期、被撤銷、格式錯誤或其他原因無效401
insufficient_scopeToken 的權限不夠這個請求403

invalid_token 這一項還有一句:用戶端可以申請新的 Access Token 後重試。這也是下一節 Refresh Token 派上用場的時機。

下面用 Node.js 內建的 http 模組,做一個只檢查 Authorization: Bearer 的小伺服器,再用 fetch 分別以「沒帶標頭」「Token 錯誤」「Token 正確」三種情況呼叫。Token 是示範用的字串,不需要安裝任何套件:

import http from 'node:http';

const DEMO_TOKEN = 'demo-access-token-123'; // 示範用字串,不是真的 Token

const server = http.createServer((req, res) => {
  const auth = req.headers['authorization'];

  // 沒帶 Authorization:回 401 並用 WWW-Authenticate 告知要用 Bearer
  if (!auth) {
    res.writeHead(401, { 'WWW-Authenticate': 'Bearer realm="demo"' });
    return res.end('missing token');
  }

  // 格式必須是「Bearer」加空白再加 Token
  const match = /^Bearer +(\S+)$/i.exec(auth);
  if (!match || match[1] !== DEMO_TOKEN) {
    res.writeHead(401, {
      'WWW-Authenticate': 'Bearer realm="demo", error="invalid_token"',
    });
    return res.end('invalid token');
  }

  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ message: '拿到受保護的資料了' }));
});

server.listen(0, '127.0.0.1', async () => {
  const url = `http://127.0.0.1:${server.address().port}/profile`;

  const cases = [
    ['沒帶 Authorization', {}],
    ['Token 錯誤', { Authorization: 'Bearer wrong-token' }],
    ['Token 正確', { Authorization: `Bearer ${DEMO_TOKEN}` }],
  ];

  for (const [label, headers] of cases) {
    const r = await fetch(url, { headers });
    const body = await r.text();
    console.log(`[${label}] ${r.status} ${r.statusText}`);
    console.log(`  WWW-Authenticate: ${r.headers.get('www-authenticate')}`);
    console.log(`  body: ${body}`);
  }
  server.close();
});

存成 bearer-demo.mjs 後用 node bearer-demo.mjs 執行,輸出如下:

[沒帶 Authorization] 401 Unauthorized
  WWW-Authenticate: Bearer realm="demo"
  body: missing token
[Token 錯誤] 401 Unauthorized
  WWW-Authenticate: Bearer realm="demo", error="invalid_token"
  body: invalid token
[Token 正確] 200 OK
  WWW-Authenticate: null
  body: {"message":"拿到受保護的資料了"}
Node.js v22.20.0、Windows 11 執行 Bearer Token 範例的輸出畫面(圖中為腳本輸出內容)

三種情況的差別一目瞭然:沒帶標頭和 Token 錯誤都是 401,而且都附上 WWW-Authenticate: Bearer;只有 Token 正確才回 200。範例只示範標頭的檢查流程,真正的伺服器還要驗證 Token 的簽章或查詢授權伺服器,這部分看 Token 的格式而定。

Access Token 與 Refresh Token 的分工

Access Token 通常設計成短效期,過期後就不能用了。那使用者是不是每隔一段時間就得重新登入?不用,這就是 Refresh Token 的工作。

RFC 6749 §1.5 的說明是:Refresh Token 是用來取得 Access Token 的憑證,在目前的 Access Token 失效或過期時,用它換一個新的;也可以換出範圍相同或更小的 Access Token。簽發 Refresh Token 是選擇性的,由授權伺服器決定。

項目Access TokenRefresh Token
用途呼叫資源伺服器(API)向授權伺服器換新的 Access Token
送往哪裡資源伺服器授權伺服器
效期短較長
外洩的影響在過期前可被拿去呼叫 API攻擊者能持續換出新的 Access Token

RFC 9700(OAuth 2.0 安全最佳實務)§4.14 也說明了這個設計的用意:有了 Refresh Token,授權伺服器就能發出短效期、小範圍的 Access Token,降低 Access Token 外洩時的影響;反過來,攻擊者如果偷到並重送 Refresh Token,就能持續換出 Access Token,所以 Refresh Token 本身要更小心保護。

Refresh Token 每次使用後要不要換新、被偷時怎麼偵測與登出時怎麼撤銷,詳細可前往〈JWT Refresh Token Rotation 怎麼做?雙權杖輪替、重複使用偵測與登出撤銷〉。

Access Token 和 Session Cookie 差在哪

另一種常見的登入機制是 Session Cookie。MDN 的 Cookie 說明描述了流程:使用者登入成功後,伺服器回傳一個含 session ID 的 cookie,記錄這個瀏覽器的登入狀態;之後使用者在同一個網站瀏覽其他頁面,瀏覽器會把這個 cookie 隨請求一併送出,伺服器檢查 session ID 是否仍然有效。

兩者的差異整理如下:

項目Session CookieBearer Access Token
憑證放在哪Cookie 請求標頭Authorization 請求標頭
誰負責帶上憑證瀏覽器依 cookie 規則附上用戶端程式碼把 Token 放進標頭
伺服器端通常要保存 session 狀態來比對 session ID看 Token 的形式:識別碼要查詢,自含式(如 JWT)可驗證簽章
主要使用情境同一個網站的網頁提供給不同用戶端使用的 API,如前後端分離、手機 App

這張表談的是機制上的差別,不代表誰比較安全。Cookie 的 HttpOnly、Secure、SameSite 屬性,以及 Token 該存在哪裡,各自有不同的風險取捨,可以參考這幾篇:

使用 Access Token 的注意事項

設定有效期限,過期就換新的

RFC 6749 §4.1.4 的 Token 回應裡有 expires_in 欄位(規範標示為 RECOMMENDED),單位是秒,例如 3600 代表從回應產生起算一小時後過期。用戶端收到 401 與 invalid_token 時,可以用 Refresh Token 換新的 Access Token 再重試,而不是要使用者重新登入。有效期限要多長,規範沒有一個固定數字,依你的系統風險決定。

不要把 Token 放在網址

RFC 6750 §2.3 允許用網址的 access_token query 參數傳 Token,但同時寫明,因為這種方式的安全弱點(包括含 Token 的網址很可能被記錄在日誌),除非完全無法使用標頭或請求本文,否則不應該使用。RFC 9700 §4.3.2 更進一步:用戶端不得(MUST NOT)以這種方式傳遞 Access Token,因為 Token 可能留在瀏覽器歷史紀錄裡。

全程使用 HTTPS

RFC 6750 規定 Bearer Token 要搭配 TLS 使用。Bearer Token 被攔截就等於通行證被拿走,所以只能走加密連線。

限制 Token 的範圍與對象

RFC 6750 §5.2 建議 Token 內要含預期接收者(audience),通常是單一資源伺服器,並建議限制 Token 的 scope。RFC 9700 §4.9.3 要求資源伺服器把 Access Token 當成其他敏感機密處理,不得以明文儲存或傳送。實務上的意思是:Token 不要印進日誌、不要貼進聊天或截圖。

權限不足是 403,不是 401

Token 有效但權限不夠,RFC 6750 §3.1 的 insufficient_scope 建議回 403;Token 本身過期或無效才是 401。前端依狀態碼決定要換新 Token 還是提示使用者沒有權限,邏輯才不會混在一起。

參考資料與延伸閱讀

發佈留言