【入門編】リフレッシュトークンのローテーション(Refresh Token Rotation)の設計 – Web APIアーキテクチャ・データ連携実践ガイド

こんにちは！今日もパケットの海を泳いでいますか？プロトコルの深淵を愛してやまない、インフラアーキテクトの執筆担当です。

普段は「BGPの収束が〜」とか「TCPの再送制御が〜」なんていう泥臭い話ばかりしている私ですが、今日は少し視点を変えて、Web APIの世界における「鍵の受け渡し」の作法、なかでも「リフレッシュトークンのローテーション（Refresh Token Rotation）」という、とってもスマートで安全な仕組みについてお話ししましょう。

「APIのセキュリティ？難しそうだな……」と身構えなくても大丈夫です。今回は、私たちの生活に欠かせない「郵便配達」や「ホテルのルームキー」の仕組みに例えて、一歩ずつ丁寧に紐解いていきますね。

—

そもそも、なぜ「2種類のトークン」が必要なの？

Web APIの世界では、ログインした後に「私は本人ですよ！」と証明するために「トークン」というデジタルな引換券を使います。これには大きく分けて2つの役割があります。

1. アクセストークン (Access Token)

役割： 部屋に入るための「一時的なカードキー」。
特徴： 有効期限がとっても短い（例：15分〜1時間）。万が一盗まれても、すぐに使えなくなるので被害を抑えられます。

2. リフレッシュトークン (Refresh Token)

役割： カードキーが切れた時に、新しいカードキーをもらうための「引換券（スペアキー）」。
特徴： 有効期限が長い（例：数日間〜数週間）。これがあれば、ユーザーは何度もログインし直さなくて済みます。

ここで一つ、恐ろしい想像をしてみてください。もし、有効期限の長い「リフレッシュトークン」が悪い人に盗まれてしまったら……？

泥棒は、あなたの代わりに新しいカードキーを何度も発行し、いつまでもあなたの部屋（データ）にアクセスできてしまいます。これを防ぐための最強の盾が、今回ご紹介する「リフレッシュトークンのローテーション」なんです。

—

リフレッシュトークンのローテーションとは？

一言で言うと、「リフレッシュトークンを1回使ったら、そのトークンは捨てて、新しいリフレッシュトークンに取り替える」という仕組みです。

郵便配達に例えてみましょう。

1. あなたは郵便局に「新しい荷物を受け取るためのチケット」を持っています。
2. そのチケットを使って荷物（アクセストークン）を受け取る際、郵便局員さんはこう言います。

「はい、新しい荷物です。それと、次回の引換に使う新しいチケットも渡しておきますね。古いチケットはもう無効にしておきます！」

3. 手元には常に「未使用の最新チケット」が1枚だけある状態になります。

これが「ローテーション（回転）」と呼ばれる所以です。

—

なぜこれが「盗難」に強いのか？（検知の仕組み）

「でも、盗まれたチケットを先に泥棒に使われたら終わりじゃない？」と思うかもしれません。ここからがこの設計の最高にクールなところです。

もし、泥棒がリフレッシュトークンを盗んで、あなたより先に「新しいトークン」に交換してしまったとします。その後に本物のあなたが古いトークンを使うと、サーバー側で「おや？このトークンはもう交換済みのはずだぞ。誰かが不正に使い回したな！」と気づくことができるんです。

この異常を検知した瞬間、サーバーはそのユーザーに関わる全てのトークンを即座に無効化します。これにより、泥棒もそれ以上アクセスできなくなり、被害を最小限に食い止められるわけです。

—

実際の設計を見てみよう（Python風の擬似コード）

では、エンジニアの皆さんがイメージしやすいように、サーバー側でどのような判定を行っているのか、簡単なロジックを書いてみますね。

# リフレッシュトークン交換の処理イメージ

def refresh_access_token(received_refresh_token):
    # 1. データベースからトークンの情報を探す
    token_info = db.find_token(received_refresh_token)

    # 2. もしトークンが見つからない、または既に「使用済み」フラグが立っていたら...
    if token_info.is_used:
        # 【重要】ここがローテーションのキモ！
        # 既に使われた形跡がある＝盗難の可能性大
        revoke_all_tokens_for_user(token_info.user_id)
        raise SecurityException("不正な利用を検知しました。全てのセッションを強制終了します。")

    # 3. トークンの有効期限をチェック
    if is_expired(token_info):
        raise TokenExpiredException("期限切れです。もう一度ログインしてください。")

    # 4. 【ローテーションの発動】
    # 今使ったトークンを「使用済み」にする
    mark_as_used(received_refresh_token)

    # 新しいアクセストークンと「新しい」リフレッシュトークンを発行
    new_access_token = generate_token()
    new_refresh_token = generate_token()

    # 新しいリフレッシュトークンをDBに保存（未使用状態で）
    db.save_token(new_refresh_token, user_id=token_info.user_id, is_used=False)

    # 5. 両方の新しいトークンをクライアントに返す
    return {
        "access_token": new_access_token,
        "refresh_token": new_refresh_token, # 次回はこれを使う！
        "expires_in": 3600
    }

クライアント側（アプリ側）の注意点

この仕組みを導入する場合、アプリ側の実装も少し優しく作る必要があります。

新しいトークンを必ず保存する： APIから新しい refresh_token が返ってきたら、古いものは捨てて、必ず新しいものに書き換えてください。
通信エラーへの配慮： サーバーが新しいトークンを発行した直後にネットワークが切れると、アプリの手元には「使用済みトークン」だけが残り、次にアクセスした時に不正検知されてしまうことがあります。そのため、少しだけ「猶予時間」を設ける設計にすることもありますが、まずは「使い捨てが基本」と覚えましょう！

—

まとめ：一歩ずつ、安全なネットワークを作ろう

「リフレッシュトークンのローテーション」は、一見すると処理が増えて複雑に見えるかもしれません。しかし、万が一の盗難時に「自動的に異常を検知して鍵を全部取り替える」という自浄作用を持たせられる、非常に美しい設計です。

現代のWeb API設計において、セキュリティは「後付けのオプション」ではなく「基盤となる心臓部」です。

1. アクセストークンは短命に！
2. リフレッシュトークンは使い捨て（ローテーション）に！
3. 再利用を検知したら、潔く全てを無効化する！

この3原則を意識するだけで、あなたの作るシステムはぐっと堅牢でプロフェッショナルなものになります。

「難しいな」と感じたら、いつでもこの郵便配達の例を思い出してください。パケットの一つひとつ、トークンの一行一行が、ユーザーの安全を守る大切な手紙なのです。

これからも、美しいプロトコルと安全なアーキテクチャの世界を一緒に楽しんでいきましょう！応援しています！