JWT認証の仕組み
実装に入る前に、そもそもなぜ認証が必要かを押さえたうえで、JWTがどのように「サーバがセッションを持たずに認証を成立させるか」を確認します。JWTの構造、アクセストークンとリフレッシュトークンの役割分担、そしてサーバ側で持つべき責務の範囲を整理します。
1. 認証の必要性
Webアプリケーションでは、リクエストの送信元が「誰なのか」を判定できないと、以下のような問題が発生します。
1.1 なりすましの防止
リクエストにユーザ本人であることを示す情報が付いていなければ、他人のIDを騙って自由にリクエストを送れる状態になります。攻撃者は他人のIDでAPIを呼び出すだけで、その人のデータを閲覧したり、勝手に変更・削除したりできてしまいます。SNSであれば他人になりすまして投稿する、ECサイトであれば他人のアカウントで注文するといった被害に直結するため、リクエスト元が本人であることを検証する認証の仕組みが必要になります。
1.2 責任追跡性の担保
誰がいつどの操作を行ったかを特定できない状態だと、不正な操作が発生しても追跡や責任の切り分けができません。監査ログ自体は残っていても、「その操作をしたのが本当に本人か」を保証する仕組みが無ければ、ログの信頼性が下がります。認証の仕組みを通してリクエスト元を特定できて初めて、操作ログが証跡として機能します。
1.3 機密情報の保護
個人情報・課金情報・非公開ドラフトなど、本来は本人だけが見られるべき情報を扱うAPIに認証が無いと、URLを推測されるだけで他人の情報を取得されてしまいます。公開情報しか扱わないサービスでも、ユーザごとの設定・履歴・下書きといった非公開情報を持つ場面はほぼ必ずあるため、認証を前提として本人以外からのアクセスを弾く設計が欠かせません。
こうした問題を防ぐために、Webアプリケーションでは「そのリクエストが誰から送られたものか」を検証する認証の仕組みが必要になります。認証が成立して初めて、ユーザごとに「何をしてよいか」を判定する認可の判断に進めます。
2. JWT認証とは
認証を成立させる方式には複数の選択肢があります。従来はサーバ側にセッション情報を保持し、Cookieでセッションキーを受け渡すステートフルな方式が使われてきました。この方式では、以下のようなリスクがありました。
- ロードバランサー越しに複数のAPIサーバを並べる構成の場合、リクエストごとに違うサーバに振り分けられるため、認証情報を全台で共有する仕組みが別途必要になる
- オートスケーリングでサーバが増減したり、サーバが再起動したりすると、そのサーバが持っていた認証情報が失われ、ユーザがログアウトされてしまう
- Cookieを前提とした仕組みのため、Cookieを扱いにくい環境からは同じ方式で認証しにくい
JWTは、必要な情報をトークン自身に埋め込み、サーバの署名で改竄されていないことを検証できる形にしたステートレスな方式です。JWTを採用することで、上記のリスクは以下のように解消できます。
- サーバ側で認証状態を保持しないため、ロードバランサーがどのサーバに振り分けても認証情報の共有が不要になる
- 認証情報がトークン自体に含まれるため、オートスケーリングでのサーバの増減や再起動があっても認証状態が失われない
- HTTPヘッダに載せてやり取りする方式なので、Cookieが扱いにくい環境からも同じ方式で認証できる
一方で、「サーバ側にセッションが無い=サーバから任意のトークンを即時に無効化できない」という性質もあります。これを補うために、後述のリフレッシュトークンと失効管理の仕組みを組み合わせて運用します。
3. JWTの構造
JWTは、以下の3つのパートを.で連結した文字列です。
ヘッダ.ペイロード.署名
実際に発行されたJWTは、以下のようにそれぞれのパートがBase64URLエンコードされた文字列で並びます。
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjEsImV4cCI6MTcyNDMzMTIwMCwiaWF0IjoxNzI0MzMwMzAwfQ.dQw4w9WgXcQ_1a2B3c4D5e6F7g8H9i0J
各パートを順に見ていきます。
3.1 ヘッダ
ヘッダは、署名アルゴリズムやトークンの種別を示すJSONを、Base64URLでエンコードしたものです。実際の値の例は以下のとおりです。
{
"alg": "HS256",
"typ": "JWT"
}
これをBase64URLエンコードすると、以下のようになります。
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
algは署名アルゴリズム(ここではHMAC-SHA256)、typはトークンの種別(JWT)を示します。
3.2 ペイロード
ペイロードは、発行者・有効期限・ユーザIDなどのクレーム(Claims)を表すJSONを、Base64URLでエンコードしたものです。
クレーム(Claims)は、ペイロードに含まれる個々の情報要素です。「このトークンについて主張(claim)したい事実」をJSONのキーと値のペアで表現するもので、たとえば「このトークンはユーザID=1のもの」「有効期限はUNIX時刻1724331200まで」といった一つひとつの主張がクレームにあたります。JWTの仕様で名前が予約されているものを標準クレーム、アプリケーション独自に定義したものをプライベートクレームと呼びます。
ペイロードには、以下のような標準クレームがあります。
| クレーム | 意味 |
|---|---|
sub |
認証対象の識別子(ユーザIDなど) |
exp |
トークンの有効期限(UNIX時刻) |
iat |
発行時刻(UNIX時刻) |
iss |
発行者 |
実際のペイロードの例は以下のとおりです。
{
"sub": 1,
"exp": 1724331200,
"iat": 1724330300
}
これをBase64URLエンコードすると、以下のようになります。
eyJzdWIiOjEsImV4cCI6MTcyNDMzMTIwMCwiaWF0IjoxNzI0MzMwMzAwfQ
ペイロードは暗号化されず、Base64URLでエンコードされているだけなので、誰でも中身を復号して見られます。パスワードなどの秘匿情報を入れてはいけません。改竄検知は署名で担保され、秘密鍵を知らない第三者が中身を書き換えると、署名の検証に失敗してサーバが弾きます。
3.3 署名
署名は、Base64URLエンコード済みのヘッダとペイロードを.で連結した文字列に対して、ヘッダで指定したアルゴリズム(例: HMAC-SHA256)とサーバの秘密鍵でハッシュ署名し、その結果をBase64URLエンコードしたものです。実際の値の例は以下のとおりです。
dQw4w9WgXcQ_1a2B3c4D5e6F7g8H9i0J
同じ秘密鍵を持っているサーバのみ、この署名を再計算して一致するかを検証できるため、トークンが改竄されていないことをステートレスに確認できます。
| 📝 JWTの仕様 |
|---|
JWTの標準仕様は、RFC 7519 - JSON Web Token (JWT)(IETF公式)に定義されています。標準クレーム(iss・sub・exp・iatなど)や、対応する署名アルゴリズム(JWS)についてもここが一次情報になります。 |
4. アクセストークン
JWT自体はトークンの形式であり、運用の設計は別途決める必要があります。本章では、以下の2種類のトークンを組み合わせる構成を採用します。
| 種別 | 有効期限 | 用途 | 失効の即時性 |
|---|---|---|---|
| アクセストークン | 短い(例: 15分) | APIリクエストの認証に使う | 有効期限までは失効させない前提 |
| リフレッシュトークン | 長い(例: 30日) | アクセストークンの再発行に使う | サーバ側で失効管理できる |
アクセストークンは、APIリクエストの認証に使う短命なトークンです。JWT形式で発行し、以降のAPIリクエストごとにAuthorization: Bearer <アクセストークン>ヘッダに載せてサーバへ送ります。サーバは署名の検証と有効期限のチェックだけでリクエスト元を判定できるため、DBへの問い合わせなしにステートレスに扱えます。
アクセストークンを短命にすることで、盗まれた場合の影響時間を狭められます。ただし短命にすると再ログインの頻度が増えてユーザ体験が悪くなるため、後述のリフレッシュトークンを合わせて発行し、期限が切れる前にアクセストークンだけを再発行する構成にします。
5. リフレッシュトークン
リフレッシュトークンは、アクセストークンの再発行に使う長命なトークンです。JWT形式にはせず、secretsモジュールで生成した乱数文字列をサーバ側のDBに保管し、以下の管理を行います。
- ログアウト時に該当のリフレッシュトークンを失効させる
- リフレッシュのたびに古いリフレッシュトークンを失効させ、新しいものを発行する(ローテーション)
この構成にすると、アクセストークンはステートレスに検証しつつ、リフレッシュトークンによって「特定のユーザ・端末のセッションを即時に切る」ことが可能になります。
6. 認証の全体フロー
ここまで説明した仕組みを踏まえ、実際にクライアントとサーバがやり取りする流れを追います。
6.1 1. ユーザ登録
ユーザ登録を表すエンドポイント(例: POST /signup)を用意し、クライアントからメールアドレスとパスワードを受け取ってユーザレコードを作成します。この段階ではトークンは発行されません。
リクエスト (POST /signup):
{"email": "test@example.com", "password": "password12345"}
処理内容:
- パスワードをハッシュ化して users テーブルにユーザレコードを作成
レスポンス:
{"id": 1, "email": "test@example.com", "created_at": "2026-08-24T10:00:00Z"}
6.2 2. ログイン
ログインを表すエンドポイント(例: POST /login)を用意し、受け取ったパスワードを検証したうえで、2種類のトークンを返します。アクセストークンはJWT形式の文字列、リフレッシュトークンは乱数由来の16進文字列で、サーバはリフレッシュトークンの値を同じ内容でDBにも保管しておきます。
リクエスト (POST /login):
{"email": "test@example.com", "password": "password12345"}
処理内容:
- メールアドレスでユーザを検索
- 受け取ったパスワードと DB のハッシュを照合
- アクセストークン(JWT)を生成
- リフレッシュトークン(乱数)を生成して DB に保存
レスポンス:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"refresh_token": "3f4c8d2a6b..."
}
6.3 3. 保護されたAPI呼び出し
認証済みユーザだけが呼び出せるAPI(例: GET /notes)にアクセスする際は、アクセストークンをリクエストに添えて送ります。クライアントは受け取ったアクセストークンをAuthorizationヘッダにBearerスキームで載せて送り、サーバはFastAPIのDependsで作成した認証依存で署名と有効期限を検証したうえで、正当ならハンドラに処理を渡します。
リクエスト (GET /notes):
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
処理内容:
- Authorization ヘッダからアクセストークンを取り出す
- 署名と有効期限を検証
- 検証に成功したらハンドラに処理を渡し、対応するデータを返す
レスポンス:
[{"id": 1, "title": "買い物"}, {"id": 2, "title": "打ち合わせ資料"}]
6.4 4. アクセストークンの再発行
アクセストークンは短命なので、期限が切れそう/切れたら再発行が必要になります。再発行を表すエンドポイント(例: POST /refresh)を用意し、受け取ったリフレッシュトークンがDB上で失効していないことを確認したうえで、古いリフレッシュトークンを失効させて新しいアクセストークンとリフレッシュトークンを返します。以降クライアントは、新しく受け取ったトークンだけを使う運用になります。
リクエスト (POST /refresh):
{"refresh_token": "3f4c8d2a6b..."}
処理内容:
- DB からリフレッシュトークンを検索
- 失効・期限切れになっていないことを確認
- 古いリフレッシュトークンを失効させる(ローテーション)
- 新しいアクセストークンとリフレッシュトークンを発行
レスポンス:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...新しい...",
"refresh_token": "a91b7e3d..."
}
6.5 5. ログアウト
ログアウトを表すエンドポイント(例: POST /logout)を用意し、受け取ったアクセストークンとリフレッシュトークンの両方を無効化します。アクセストークンはJWT側で即時無効化ができない(ステートレスなので)ため、DBのブラックリスト(revoked_access_tokensテーブル)に登録し、認証依存で照合することで即時拒否させます。リフレッシュトークンはrefresh_tokensテーブルのrevoked_atを更新して、以降の/refreshを拒否します。
リクエスト (POST /logout):
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
{"refresh_token": "a91b7e3d..."}
処理内容:
- アクセストークンを revoked_access_tokens に登録して即時無効化
- 対応するリフレッシュトークンを無効化
レスポンス:
204 No Content
この流れを本章の後半で1エンドポイントずつ実装します。
| 💡 ポイント |
|---|
認証で扱うパスワードは、DBに平文で保存せず、必ずハッシュ化して管理するのが基本です。ハッシュ化しておくと、万が一DBが漏洩してもパスワード自体は復元しにくいため、被害を最小限に抑えられます。本章のハンズオンでも、Pythonでよく使われるbcryptパッケージを使ってハッシュ化します。 |