【入門編】 OAuth 2.0 PKCE (Proof Key for Code Exchange)の仕組み – Web APIアーキテクチャ・データ連携実践ガイド

こんにちは、皆さん！今日もプロトコルの深淵へようこそ。ネットワークプロトコルの美しさに取り憑かれ、RFC（Request for Comments）を肴に白米が食べられるほどの情熱を持つ、当メディア主筆のプロトコルスペシャリストです。

普段はCCIE（Cisco Certified Internetwork Expert）レベルのゴリゴリなインフラの話をすることが多い私ですが、今日は少し視点を変えて、現代のWeb開発には欠かせない「Web APIのセキュリティ」についてお話ししましょう。

特に、スマートフォンアプリやSPA（Single Page Application）を開発する際に絶対に避けては通れない、「OAuth 2.0 PKCE（ピクシー）」という仕組みにスポットライトを当てます。

「OAuth？ PKCE？なんだか難しそうなアルファベットが並んでいるな……」と身構えなくても大丈夫です。一歩ずつ、現実世界の仕組みに例えながら、その「美しすぎる防御策」を紐解いていきましょう！

—

1. なぜ「PKCE」が必要なの？——横取りされる「秘密の手紙」

まず、PKCE（Proof Key for Code Exchange）がなぜ生まれたのかを知るために、従来のOAuth 2.0が抱えていた「ある弱点」についてお話しします。

OAuth 2.0でログイン（認可）を行うとき、一般的には「認可コード（Authorization Code）」という、一回限りのチケットが発行されます。例えるなら、「このチケットを持っていれば、後で本物の鍵（アクセストークン）と交換してあげるよ」という約束の手紙です。

しかし、スマートフォンアプリの場合、この手紙が届く「ポスト（URL）」は、実は他の悪意あるアプリからも覗き見ることができてしまう可能性があったのです。

悪いアプリAが、正しいアプリBのふりをして待機している。
認可サーバーから届いた「認可コード」を、悪いアプリAがサッと横取りする。
そのまま悪いアプリAがサーバーに「鍵をください！」と頼み、ユーザーのデータにアクセスしてしまう。

これを「認可コード横取り攻撃」と呼びます。これを防ぐために登場したのが、今回解説するPKCEなのです。

—

2. PKCEの仕組みを「合言葉」で理解しよう

PKCEを一言で言うなら、「最初に自分しか知らない秘密の合言葉を決め、その『ヒント』だけを先に相手に渡しておく仕組み」です。

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

1. 【準備】 あなたは自分だけが知る長い「秘密の合言葉（code_verifier）」を考えます。
2. 【ヒント作成】 その合言葉を特別な機械（ハッシュ関数）に通して、元に戻せない「合言葉の影（code_challenge）」を作ります。
3. 【発送】 郵便局（認可サーバー）に、「これから手紙を取りに行くけど、私の『合言葉の影』はこれだよ！」と先に伝えておきます。
4. 【引換券ゲット】 郵便局から「引換券（認可コード）」が届きます。もしこれが泥棒に盗まれても、泥棒は「元の合言葉」を知りません。
5. 【照合】 あなたは郵便局へ行き、「引換券」と、隠しておいた「元の合言葉」をセットで出します。
6. 【完了】 郵便局は、受け取った「元の合言葉」を機械に通し、最初に預かった「合言葉の影」と一致するか確認します。一致すれば、本物の鍵を渡してくれます。

これなら、もし途中で引換券（認可コード）が盗まれても、犯人は「元の合言葉」を持っていないため、最終的な鍵を手に入れることはできません。実にスマートな設計ですよね！

—

3. 実務で使う3つの重要パラメーター

エンジニアとして実装に向き合う際、覚えておくべきキーワードは3つだけです。

code_verifier (コード検証者)
クライアント（アプリ）側で生成する、ランダムな長い文字列です。「秘密の合言葉」そのものです。
code_challenge (コードチャレンジ)
code_verifier をハッシュ化（SHA-256など）し、URLで送れる形式にしたものです。「合言葉の影」ですね。
code_challenge_method
ハッシュ化した方法（通常は S256）をサーバーに伝えます。

—

4. 【実践】PythonでPKCEのパラメーターを作ってみる

「概念はわかったけど、コードにするとどうなるの？」という方のために、実際に code_verifier と code_challenge を生成するサンプルコードを用意しました。一歩ずつ、処理の流れを追ってみてください。

import hashlib
import secrets
import base64

def generate_pkce_params():
    # 1. code_verifier の生成
    # 43文字〜128文字のランダムな文字列を作ります。これが「秘密の合言葉」です。
    # ここでは安全な乱数生成器を使います。
    code_verifier = secrets.token_urlsafe(64)
    print(f"1. code_verifier (秘密の合言葉): {code_verifier}")

    # 2. code_challenge の作成
    # SHA-256でハッシュ化し、Base64URLエンコードを行います（パディングの = は除去）。
    # これがサーバーに先に送る「合言葉の影」になります。
    hashed = hashlib.sha256(code_verifier.encode('ascii')).digest()
    code_challenge = base64.urlsafe_b64encode(hashed).decode('ascii').replace('=', '')
    print(f"2. code_challenge (合言葉の影): {code_challenge}")

    return code_verifier, code_challenge

# 実行してみましょう！
verifier, challenge = generate_pkce_params()

# 実際のリクエストイメージ（認可リクエスト時）
# https://auth-server.example.com/authorize?
#   response_type=code&
#   client_id=YOUR_CLIENT_ID&
#   code_challenge={challenge}&
#   code_challenge_method=S256

このコードで生成された code_challenge を、最初の認可リクエスト時に GET パラメーターとして送り、最後のトークン交換時に code_verifier を POST パラメーターとして送る。これだけで、あなたのアプリのセキュリティは劇的に向上します。

—

5. 美しいAPI設計とPKCEの親和性

REST APIの原則において、エンドポイントの設計は「直感的で、かつ安全であること」が求められます。

PKCEを利用する場合でも、APIのURL自体が複雑になるわけではありません。むしろ、PKCEは 「クライアント・シークレット（パスワード）をアプリ内に持たなくて良い」 というメリットを生みます。

モバイルアプリやブラウザアプリにパスワードを埋め込むのは、泥棒に鍵を預けるようなものです。PKCEを使えば、動的にその場限りのセキュリティを構築できるため、APIアーキテクチャ全体がより堅牢で、洗練されたものになるのです。

—

おわりに：一歩ずつ、確実なセキュリティを

いかがでしたでしょうか？
「PKCE」という難しそうな言葉の裏側には、「先に影を見せておき、後で実物を照らし合わせる」という、非常に人間味のある知恵が詰まっていることが分かっていただけたかと思います。

インフラやプロトコルの世界は、一見すると無機質な数字やアルファベットの羅列に見えます。しかし、その一つひとつは「どうすれば情報を安全に届けられるか」という先人たちの熱い議論と工夫の結晶です。

もしあなたが次にAPIを設計したり、アプリの認証機能を実装したりする機会があれば、ぜひこの「秘密の合言葉」のやり取りを思い出してみてください。パケットの向こう側にある設計の意図を感じ取れるようになれば、あなたはもう立派なプロトコル・スペシャリストの卵です！

これからも、ネットワークの深淵を一緒に探求していきましょう。それでは、また次の記事でお会いしましょう！