OAuthのトークンの種類とBearer認証を整理した話

GitHub OAuthのログインを実装する中で、複数の種類のトークンが登場しました。 それぞれの役割・寿命・保存場所が異なるため、整理してまとめます。

Bearer認証とは

「Bearer（ベアラー）」は英語で「持参人」を意味します。「このトークンを持っている人を信頼して処理を許可する」 という考え方の認証方式です。

HTTPヘッダーでは以下のように使います。

Authorization: Bearer ghp_xxxxxxxxxxxx

GitHubのAPIを叩くコードで言うとこの部分です。

const githubRes = await fetch('https://api.github.com/user', {
  headers: {
    Authorization: `Bearer ${accessToken}`,
  }
});

GitHubのAPIサーバーはこのヘッダーを見て「このアクセストークンを持っているなら正規のリクエストだ」と判断してユーザー情報を返します。

Bearerトークンの特徴

トークンを持っているだけで認証される

パスワード認証と違い、誰が送ってきたかを問いません。トークンさえ正しければ認証が通ります。

パスワード認証: ID + パスワードの組み合わせで認証
Bearer認証:    トークン1つで認証（IDなし）

トークンが漏れると危険

トークンを持っている人を無条件に信頼するため、第三者に漏れると不正利用されます。そのため httpOnly Cookie に保存してJavaScriptからアクセスできないようにしたり、HTTPS通信で盗聴を防ぐといった対策が必要です。

Authorizationヘッダーのスキーム

Bearer 以外にも認証スキームがあります。

WebAPIでは Bearer が最も広く使われています。

OAuthで登場する3種類のトークン

GitHub OAuthの実装では3種類のトークンが登場します。

① Authorization Code（認可コード）

GitHubがコールバックURLのクエリパラメータに付けて返してくる引換券です。

/login/github/callback?code=ABC123...&state=xxx

なぜURLに直接アクセストークンを返さないのか？

URLはブラウザの履歴・サーバーのログ・リファラーヘッダーなどに残ります。アクセストークンをURLに含めると漏洩リスクが高まるため、短命な引換券（code）をURLに載せてアクセストークンの取得はサーバー間通信で行います。

ブラウザ（URLに残る）  → code（短命・使い捨て）
サーバー間通信（安全）  → アクセストークン（本物）

② Access Token（アクセストークン）

codeをアクセストークンに交換する処理の裏側はこうなっています。

自分のサーバー → GitHubのAPIにPOSTリクエスト
  https://github.com/login/oauth/access_token
    code=ABC123...
    client_id=xxxx
    client_secret=xxxx    ← 秘密鍵（サーバーだけが知っている）

← アクセストークン（ghp_xxx）が返ってくる

今回の実装ではユーザー情報を取得したら使い捨てにしています。

const tokens = await github.validateAuthorizationCode(code);
const accessToken = tokens.accessToken();

// アクセストークンでAPIを叩く
const githubRes = await fetch('https://api.github.com/user', {
  headers: { Authorization: `Bearer ${accessToken}` }
});

// 取得できたらアクセストークンは不要（DBに保存しない）
const githubUser = await githubRes.json();

③ Refresh Token（リフレッシュトークン）

アクセストークンが期限切れになったとき、ユーザーに再ログインさせずに新しいアクセストークンを取得するためのトークンです。

アクセストークンが期限切れ
  → リフレッシュトークンを使って新しいアクセストークンを取得
  → ユーザーはログインし直さなくてよい

GitHubのOAuthアプリはデフォルトでアクセストークンが無期限のため、リフレッシュトークンは発行されません。Google・Twitterなどの他プロバイダではアクセストークンに有効期限があるため必要になります。

全体の流れと各トークンの位置づけ

① ブラウザ ←→ GitHubの認証画面
     ↓ code（引換券・短命・使い捨て）を受け取る

② 自分のサーバー ←→ GitHubのAPIサーバー
     ↓ codeをアクセストークンに交換（サーバー間通信）

③ 自分のサーバー → GitHubのAPIを叩く
     ↓ アクセストークンでユーザー情報を取得して使い捨て

④ 自分のサーバー → D1にセッションIDを保存
     ↓ CookieにセッションIDをセット（自前のセッション管理）

GitHubのアクセストークンをそのまま使わない理由

シンプルに「GitHubのアクセストークンをそのままCookieに保存する」方法もあります。しかし以下の問題があります。

そのため「GitHubのトークンはユーザー情報の取得にだけ使い、自前のセッションIDで管理する」という設計が一般的です。