EN

OAuthのPKCEを図で整理する

目次

はじめに

前回の記事では、写真プリントサービスがInstagramの写真を取り込む例で、OAuthの認可コードフローを整理しました。そこで前提にしていたのは、クライアントシークレットを安全に保管できるWebアプリ(コンフィデンシャルクライアント)です。

ところが、同じ写真プリントサービスがスマホアプリを出すと、話が変わります。スマホアプリはシークレットを安全に持てないので、前回のフローのままでは、認可コードを横取りされたときに防げません。

そこで使われるのがPKCE(Proof Key for Code Exchange、「ピクシー」と読みます)です。今回は、スマホアプリで何が困るのか、PKCEがそれをどう防ぐのかを、前回と同じ例とシーケンス図で整理します。あわせて、前回のstateとの違いや、Webアプリでも使われる理由にも触れます。

スマホアプリで困ること

シークレットを隠せない

前回のフローでは、認可コードをアクセストークンと交換するときに、クライアントシークレットを送って「正規のクライアントからのリクエストである」ことを証明していました。Webアプリなら、シークレットをクライアント(写真プリントサービス)自身のサーバーに置けます。認可サーバー(Instagram)に預けるのではなく、クライアントの事業者が管理するサーバーなので、利用者からは見えません。

スマホアプリは事情が違います。アプリ本体は利用者のスマホにダウンロードされて動くため、シークレットを埋め込んでも、アプリを解析すれば取り出せてしまいます。前回の分類でいう、パブリッククライアントです。

シークレットの置き場所の図。Webアプリではシークレットをクライアント(写真プリントサービス)自身のサーバーに置くので利用者からは見えない。スマホアプリではアプリ本体が利用者のスマホに配られるので、埋め込んだシークレットは解析すれば取り出せる。 Webアプリ スマホアプリ ブラウザ利用者の手元 クライアントのサーバー写真プリントサービスの手元 client_secret 利用者からは見えない アプリ本体利用者のスマホの中 client_secret 解析すれば 取り出せる

シークレットが使えないと、認可サーバーには、トークンを求めてきた相手が本当に正規のアプリなのかを確かめる手段がありません。認可コードさえ持っていれば、誰でもトークンと交換できてしまいます。

認可コードの横取り

スマホアプリでは、認可サーバーからのリダイレクト先(redirect_uri)に、com.example.print:/callbackのようなアプリ専用のURL(カスタムURLスキーム)を使うことがあります。ブラウザがこのURLを開くと、OSはそのスキームを登録しているアプリを起動して、URLを渡します。

ところが、同じスキームは別のアプリも登録できてしまいます。悪意のあるアプリが同じスマホに入っていると、次の手順で認可コードを横取りされ、そのままアクセストークンまで取られてしまいます。赤い矢印が、攻撃にあたるステップです。

PKCEがない場合の認可コード横取りのシーケンス図。悪意のあるアプリが正規のアプリと同じカスタムURLスキームを登録しておき、リダイレクトで届いた認可コードをOSから受け取る。シークレットがないので、認可サーバーは区別できずにアクセストークンを渡してしまう。赤い矢印が攻撃のステップ。 ユーザー (スマホのブラウザ) 正規のアプリ (写真プリントアプリ) com.example.print: 悪意のあるアプリ (同じスマホ) com.example.print: 認可サーバー (Instagram) auth.example.net 同じスキームを登録しておく 1 認可画面を開く 2 認可リクエスト 3 ログイン・同意 4 リダイレクト(コード付き) 5 OSが悪意のあるアプリに渡す 6 トークンを要求 7 アクセストークン 正規のアプリと区別できない

リダイレクトで届いた認可コードを、正規のアプリと悪意のあるアプリのどちらに渡すかは、OSの振り分け次第です(4,5)。悪意のあるアプリは、受け取ったコードでそのままトークンを求めます(6)。シークレットを使わないので、認可サーバーは正規のアプリと区別できず、アクセストークンを渡してしまいます(7)。

このように、認可コードを悪意のあるアプリに横取りされる攻撃を、認可コード横取り攻撃(authorization code interception attack)と呼びます。PKCEは、この攻撃を防ぐために作られた仕組みです。

PKCEの仕組み

使い捨ての合言葉

PKCEの考え方は、「認可リクエストのたびに、使い捨ての合言葉をその場で作る」というものです。前もってアプリに埋め込んでおくシークレットと違い、毎回作って使い終わったら捨てるので、アプリを解析されても取り出せません。

合言葉はcode_verifierとcode_challengeの2つで1組です。code_verifierはアプリが作るランダムな文字列で、手元に残しておきます。code_challengeは、code_verifierをSHA-256でハッシュし、Base64URLで文字列にしたものです。アプリは先にcode_challengeだけを認可サーバーへ送っておき、トークンと交換するときに初めてcode_verifierを送ります。

code_verifierとcode_challengeの関係図。code_verifierをSHA-256でハッシュし、Base64URLで文字列にしたものがcode_challenge。code_challengeからcode_verifierには戻せない。 code_verifier(アプリの手元に残す)dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk SHA-256でハッシュ Base64URLで文字列に 元には 戻せない code_challenge(認可リクエストで送る)E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM

ハッシュは一方向の計算なので、code_challengeからcode_verifierを求めることはできません。code_challengeはブラウザを通るURLに載るので見られるかもしれませんが、それを見てもcode_verifierはわかりません。

パラメータ

パラメータ内容
code_verifierアプリが作る、推測できないランダムな文字列(43〜128文字)。トークンリクエストで送る
code_challengecode_verifierをSHA-256でハッシュし、Base64URLで文字列にしたもの。認可リクエストで送る
code_challenge_methodcode_challengeの作り方。S256(SHA-256)を指定する。認可リクエストで送る

code_challenge_methodには、ハッシュせずにそのまま送るplainもあります。ただ、plainではcode_challengeを見られるとcode_verifierもわかってしまいます。PKCEの仕様(RFC 7636)でも、S256を使えるクライアントはS256を使わなければならないとされています。

PKCEを使った認可コードフロー

全体像

前回のフローに、PKCEで増える部分を紫で示しました。ドメインは前回と同じで、スマホアプリのリダイレクト先にはcom.example.print:/callbackを使います。

PKCEを使った認可コードフロー全体のシーケンス図。紫で示した2、4、5、10、11が、PKCEで増える部分。 ユーザー (スマホのブラウザ) クライアント (写真プリントアプリ) com.example.print: 認可サーバー (Instagram) auth.example.net リソースサーバー (Instagram API) api.example.net 1 「写真を選ぶ」を押す 2 verifierを作り、challengeを計算 3 認可画面を開く 4 認可リクエスト(code_challenge付き) 5 code_challengeを保存 6 ログイン・同意画面を表示 7 ログインして許可 8 リダイレクト(認可コード付き) 9 アプリにコードを渡す 10 コード+verifier 11 verifierをハッシュして比べる 12 アクセストークン 13 トークン付きでAPIリクエスト 14 写真データ

前回と違うのは、最初に合言葉を作ること(2)、認可リクエストにcode_challengeを付けること(4,5)、トークンと交換するときにシークレットの代わりにcode_verifierを送り、認可サーバーが確かめること(10,11)の3点です。このあとStepごとに、該当する矢印を緑で示します。

Step 1:合言葉を作る(図の1,2)

ユーザーが「写真を選ぶ」を押すと、アプリはまずcode_verifierを作り、そこからcode_challengeを計算します。

シーケンス図。緑で示した1と2が、Step1の合言葉を作る部分。 ユーザー (スマホのブラウザ) クライアント (写真プリントアプリ) com.example.print: 認可サーバー (Instagram) auth.example.net リソースサーバー (Instagram API) api.example.net 1 「写真を選ぶ」を押す 2 verifierを作り、challengeを計算 3 認可画面を開く 4 認可リクエスト(code_challenge付き) 5 code_challengeを保存 6 ログイン・同意画面を表示 7 ログインして許可 8 リダイレクト(認可コード付き) 9 アプリにコードを渡す 10 コード+verifier 11 verifierをハッシュして比べる 12 アクセストークン 13 トークン付きでAPIリクエスト 14 写真データ

考え方をPythonで書くと、次のようになります。

import base64
import hashlib
import secrets

# 推測できないランダムな文字列(43文字)
code_verifier = secrets.token_urlsafe(32)

# SHA-256でハッシュし、Base64URLで文字列にする(末尾の=は取る)
digest = hashlib.sha256(code_verifier.encode("ascii")).digest()
code_challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")

この記事では、PKCEの仕様(RFC 7636)の付録にある例の値を使います。code_verifierがdBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXkで、そこから計算したcode_challengeがE9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cMです。code_verifierはアプリの中に保存しておき、まだどこにも送りません。

Step 2:認可リクエスト(図の3〜5)

アプリはブラウザで認可画面を開きます。このとき、認可リクエストにcode_challengeとcode_challenge_methodを付けます。

シーケンス図。緑で示した3から5が、Step2の認可リクエスト。 ユーザー (スマホのブラウザ) クライアント (写真プリントアプリ) com.example.print: 認可サーバー (Instagram) auth.example.net リソースサーバー (Instagram API) api.example.net 1 「写真を選ぶ」を押す 2 verifierを作り、challengeを計算 3 認可画面を開く 4 認可リクエスト(code_challenge付き) 5 code_challengeを保存 6 ログイン・同意画面を表示 7 ログインして許可 8 リダイレクト(認可コード付き) 9 アプリにコードを渡す 10 コード+verifier 11 verifierをハッシュして比べる 12 アクセストークン 13 トークン付きでAPIリクエスト 14 写真データ
GET /authorize?response_type=code
  &client_id=s6BhdRkqt3
  &redirect_uri=com.example.print%3A%2Fcallback
  &scope=photos.read
  &state=35ce
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256 HTTP/1.1
Host: auth.example.net

認可サーバーは、受け取ったcode_challengeを保存しておきます(5)。このあと発行する認可コードと紐付けて、トークンリクエストのときに照らし合わせるためです。

なお、スマホアプリでは、認可画面をアプリに埋め込んだWebViewではなく、OSのブラウザやアプリ内ブラウザタブで開くことが求められています(RFC 8252)。WebViewだと、アプリがログイン画面に入力されたパスワードを読み取れてしまうためです。

Step 3:ログインと同意、認可コードの発行(図の6〜9)

ここは前回と同じです。ユーザーがログインして許可すると、認可サーバーはredirect_uriへリダイレクトし、OSが認可コードをアプリに渡します。

シーケンス図。緑で示した6から9が、Step3のログインと同意、認可コードの発行。 ユーザー (スマホのブラウザ) クライアント (写真プリントアプリ) com.example.print: 認可サーバー (Instagram) auth.example.net リソースサーバー (Instagram API) api.example.net 1 「写真を選ぶ」を押す 2 verifierを作り、challengeを計算 3 認可画面を開く 4 認可リクエスト(code_challenge付き) 5 code_challengeを保存 6 ログイン・同意画面を表示 7 ログインして許可 8 リダイレクト(認可コード付き) 9 アプリにコードを渡す 10 コード+verifier 11 verifierをハッシュして比べる 12 アクセストークン 13 トークン付きでAPIリクエスト 14 写真データ
HTTP/1.1 302 Found
Location: com.example.print:/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=35ce

Step 4:トークンとの交換(図の10〜12)

アプリは認可コードと一緒に、合言葉を作るときに保存しておいたcode_verifierを送ります。シークレットを持たないのでAuthorizationヘッダーは付けず、client_idを本文に入れます。

シーケンス図。緑で示した10から12が、Step4のトークンとの交換。 ユーザー (スマホのブラウザ) クライアント (写真プリントアプリ) com.example.print: 認可サーバー (Instagram) auth.example.net リソースサーバー (Instagram API) api.example.net 1 「写真を選ぶ」を押す 2 verifierを作り、challengeを計算 3 認可画面を開く 4 認可リクエスト(code_challenge付き) 5 code_challengeを保存 6 ログイン・同意画面を表示 7 ログインして許可 8 リダイレクト(認可コード付き) 9 アプリにコードを渡す 10 コード+verifier 11 verifierをハッシュして比べる 12 アクセストークン 13 トークン付きでAPIリクエスト 14 写真データ
POST /token HTTP/1.1
Host: auth.example.net
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=com.example.print%3A%2Fcallback
&client_id=s6BhdRkqt3
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

認可サーバーは、届いたcode_verifierを同じ方法でハッシュし、認可リクエストのときに保存しておいたcode_challengeと比べます(11)。一致すれば、認可リクエストを送ったのと同じアプリからのリクエストだとわかるので、アクセストークンを発行します(12)。

認可サーバーの確認の図。届いたcode_verifierをSHA-256でハッシュしBase64URLで文字列にして、保存しておいたcode_challengeと比べる。一致すればアクセストークンを発行する。 届いたcode_verifier(Step 4)dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk SHA-256 → Base64URL 計算したcode_challengeE9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM 一致するか比べる 保存しておいたcode_challenge(Step 2)E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM 一致すれば、アクセストークンを発行する

Step 5:APIへのアクセス(図の13,14)

ここも前回と同じです。アクセストークンをリクエストに付けて、リソースサーバー(api.example.net)から写真データを取得します。

シーケンス図。緑で示した13と14が、Step5のAPIアクセス。 ユーザー (スマホのブラウザ) クライアント (写真プリントアプリ) com.example.print: 認可サーバー (Instagram) auth.example.net リソースサーバー (Instagram API) api.example.net 1 「写真を選ぶ」を押す 2 verifierを作り、challengeを計算 3 認可画面を開く 4 認可リクエスト(code_challenge付き) 5 code_challengeを保存 6 ログイン・同意画面を表示 7 ログインして許可 8 リダイレクト(認可コード付き) 9 アプリにコードを渡す 10 コード+verifier 11 verifierをハッシュして比べる 12 アクセストークン 13 トークン付きでAPIリクエスト 14 写真データ
GET /photos HTTP/1.1
Host: api.example.net
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

横取りされたコードが使えない理由

PKCEを使っていれば、悪意のあるアプリに認可コードを横取りされても、トークンとは交換できません。赤が攻撃のステップ、紫がPKCEによる確認です。a〜cは、合言葉を作る、code_challengeを保存する、code_verifierを確かめる、にあたります。

PKCEで横取りを止めるシーケンス図。a、正規のアプリがcode_verifierを作りcode_challengeを計算する。b、認可サーバーがcode_challengeを保存する。悪意のあるアプリが認可コードを横取りしてトークンを要求しても、c、code_verifierがない、または一致しないので、認可サーバーは拒否する。 ユーザー (スマホのブラウザ) 正規のアプリ (写真プリントアプリ) com.example.print: 悪意のあるアプリ (同じスマホ) com.example.print: 認可サーバー (Instagram) auth.example.net a verifierを作り、challengeを計算 1 認可画面を開く 2 認可リクエスト(code_challenge付き) b code_challengeを保存 3 ログイン・同意 4 リダイレクト(コード付き) 5 OSが悪意のあるアプリに渡す 6 トークンを要求(verifierなし) c verifierがない・一致しない → 拒否 7 エラーを返す

悪意のあるアプリが手に入れられるのは、リダイレクトで届いた認可コードだけです(4,5)。code_verifierは正規のアプリの中にしかなく、まだどこにも送られていません。code_challengeはURLに載るので見られるかもしれませんが、そこからcode_verifierは求められません。そのため、悪意のあるアプリのトークンリクエストは、cの確認で拒否されます。

正規のアプリがcode_verifierを送るトークンリクエストは、アプリから認可サーバーへHTTPSで直接送られ、ブラウザやOSの振り分けを通りません。そのため、code_verifierが途中で横取りされることもありません。

stateとの違い

PKCEと前回のstateは、どちらも「リクエストを始めた相手と、戻ってきた相手が同じか」を確かめる仕組みです。ただ、確かめる人と、主に防ぐ攻撃が違います。

statePKCE
確かめる人クライアント認可サーバー
比べるものセッションに保存した値と、リダイレクトで戻ってきた値保存したcode_challengeと、届いたcode_verifierのハッシュ
主に防ぐ攻撃CSRF(攻撃者のコードを被害者に使わせる)認可コードの横取り(被害者のコードを攻撃者が使う)

なお、OAuthのセキュリティのベストプラクティス(RFC 9700)では、認可サーバーがPKCEに対応していると確認できる場合は、PKCEでCSRFも防げるとして、PKCEに頼ってよいとしています。

Webアプリでの利用

PKCEは、スマホアプリのためだけの仕組みではありません。同じベストプラクティス(RFC 9700)では、パブリッククライアントにはPKCEを必須とし、Webアプリのようなコンフィデンシャルクライアントにも使うことを推奨しています。シークレットがあっても、認可コードを横取りされたり、攻撃者のコードを送り込まれたりするのを防ぐのに役立つためです。

OAuthの新しい版であるOAuth 2.1でも、認可コードフローではPKCEを使うのが基本になっています。前回のWebアプリのフローも、実際に作るときはPKCEを組み合わせておくのが安全です。

まとめ

  • スマホアプリはシークレットを持てないので、認可コードを横取りされると、そのままトークンと交換されてしまう
  • PKCEは、認可リクエストのたびに使い捨ての合言葉(code_verifier)を作り、そのハッシュ(code_challenge)を先に送っておく仕組み
  • トークンと交換するときにcode_verifierを送り、認可サーバーがハッシュを比べるので、合言葉を知らない相手はトークンを受け取れない
  • stateはクライアントがCSRFを防ぎ、PKCEは認可サーバーが認可コードの横取りを防ぐ

次回予告

ここまでのOAuthとPKCEは、どれも「プリントサービスに何をさせてよいか」を決める仕組みでした。では、同じプリントサービスに「Instagramでログイン」を付けて、ログインしたのが誰かを知りたいときはどうするのか。

そこで使われるのが、OAuthの上に乗るOpenID Connect(OIDC)です。OIDCについては、次の記事で図を使って整理しました。

参考