EN

OAuthの認可コードフローを図で整理する

目次

はじめに

9月下旬から10月上旬にかけて、「情報漏洩のバーゲンセールか」と、野菜の国の王子様のセリフをもじりたくなるほど、情報漏洩のニュースをよく耳にしました。

セキュリティは以前からずっと大事だと思っていたので、OAuthの仕組みもQiitaやZennの記事、本で読んで、理解したつもりになっていました。ところが、設計の仕事でチームメンバーや取引先に説明する場面や、アウトプットがてら同業の友人に話す場面を思い浮かべると、途中で説明に詰まる自分が想像できます。登場人物の役割や、誰と誰がどの順番で何をやり取りしているのかが、いまいち頭に定着していないからです。

身近なところでは、InstagramやXを別のアプリと連携しようとすると、「このアプリにアカウントへのアクセスを許可しますか?」という画面が出てきます。この裏で動いているのがOAuthです。

最近は認証・認可まわりの設計の仕事も増えてきたので、この機会に、身近なSNSの例とシーケンス図を使って、OAuthの基本と「認可コードフロー」の流れを整理します。

OAuthとは

OAuth(Open Authorization)は、アクセス権限を委譲するためのプロトコルです。ユーザーはパスワードを渡さずに、自分のデータへのアクセスを別のアプリケーションに許可できます。

例で解説

写真プリントサービスに自分の権限を委譲して、Instagramに投稿した写真を印刷したいケースを考えます。

この場合、ユーザーのIDとパスワードをそのままプリントサービスに預けて(委譲して)、代わりにInstagramにログインしてもらうのが楽です。ただ、そうすると、IDとパスワードを受け取ったプリントサービスがInstagramアカウントで何でもできてしまいます(勝手に投稿する、DMを読む、パスワードを変えることさえできてしまい危険です)。

サードパーティ(プリントサービス)にアクセスを許可するなら、そのアクセスは次の条件を満たすべきです。

  • 特定のデータ・操作に限定されている(例:写真の読み取りだけ)
  • 有効な期間が限られている

OAuthでは、このあと紹介する登場人物が、次の3つの概念を使ってこれを実現します。

概念説明
認可フローアプリ※にアクセスを許可するまでの手順。アプリの種類に応じて複数ある
スコープアクセスできるデータと操作の範囲。アプリ※はリクエスト時に指定する
アクセストークン他サイトのデータにアクセスするための鍵。有効期限があり、権限はスコープの範囲に限られる

※アプリは、アクセスを許可される側(この例ではプリントサービス)です。アクセスする先のデータは、Instagramにあります。

登場人物

役割説明写真プリントの例
リソースオーナーデータの持ち主(ユーザー)Instagramに写真を載せているあなた
クライアントユーザーのデータにアクセスしたいアプリ写真プリントサービス(print.example.com)
認可サーバーユーザーを認証し、アクセストークンを発行するInstagramのログイン・許可画面を出すサーバー(auth.example.net)
リソースサーバーユーザーデータを保持し、アクセスを制御する(API)Instagramの写真データを返すAPI(api.example.net)

この記事では、次のドメインで説明します。

  • プリントサービスはprint.example.com
  • Instagram側はexample.net(認可サーバーはauth.example.net、リソースサーバーはapi.example.net)

どちらも説明用の例で、実際のInstagramのドメインではありません。

4者の関係を図にすると、次のようになります。番号は、やり取りが起きる順番です。

登場人物の関係図。リソースオーナー(あなた)がクライアント(写真プリントサービス、print.example.com)を使い(1)、認可サーバー(auth.example.net)でログインして許可する(2)。認可サーバーはクライアントにアクセストークンを発行し(3)、クライアントはトークンを付けてリソースサーバー(api.example.net)から写真を取得する(4)。 Instagram(example.net) リソースオーナーあなた クライアント写真プリントサービスprint.example.com 認可サーバーログイン・許可の画面auth.example.net リソースサーバー写真データのAPIapi.example.net 1 使う 2 ログインして許可 3 トークンを発行 4 トークンを付けて 写真を取得

2種類のクライアント

種類特徴例
コンフィデンシャルクライアント秘密情報(クライアントシークレット)を安全に保管でき、それを使って認可サーバーに自分を証明できるWebアプリ
パブリッククライアントアプリ本体が利用者の端末に配られるため秘密を守れず、クライアントシークレットを使えないスマホアプリ

Webアプリはプログラムがクライアント(写真プリントサービス)自身のサーバー上で動くので、シークレットを利用者から見えない場所に置いておけます。一方、スマホアプリはアプリ本体を各自の端末にダウンロードして動かすので、中にシークレットを埋め込んでも、解析されれば取り出されてしまいます。

認可フローの種類

OAuthには、アプリの種類や使う場面に応じて、いくつかの認可フローがあります。代表的なものは次のとおりです。

フロー使う場面
認可コードフローユーザーがブラウザでログインし、アプリへのアクセスを許可する
クライアントクレデンシャルフローユーザーが関わらず、サーバー同士でやり取りする
デバイス認可グラントテレビやゲーム機など、文字を入力しにくい機器でログインする

このうち、Webアプリでよく使われているのが認可コードフローです。写真プリントサービスの例もこれにあたります。ここからは、認可コードフローを詳しく見ていきます。

認可コードフロー

概要

認可コードフローは、認可サーバーから受け取った「認可コード」を、アクセストークンと交換するフローです。

  • ブラウザのリダイレクトを使ってユーザーを認可サーバーへ送り、最後にクライアントへ戻す
  • トークンとの交換にクライアントシークレットを使うため、シークレットを保管できるWebアプリ(コンフィデンシャルクライアント)向けのフロー

全体像

まずは全体の流れです。上の箱には、各登場人物のドメインも書いています。このあとStepごとに、該当する矢印を緑で示します。

認可コードフロー全体のシーケンス図。1から11の矢印で、ユーザー、クライアント、認可サーバー、リソースサーバーがやり取りする。 ユーザー (ブラウザ) クライアント (写真プリントサービス) print.example.com 認可サーバー (Instagram) auth.example.net リソースサーバー (Instagram API) api.example.net 1 「写真を選ぶ」を押す 2 認可画面へリダイレクト 3 認可リクエスト 4 ログイン・同意画面を表示 5 ログインして許可 6 redirect_uriへリダイレクト(認可コード付き) 7 認可コードを届ける 8 コード+ID+シークレット 9 アクセストークン 10 トークン付きでAPIリクエスト 11 写真データ

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

ユーザーが「Instagramから写真を選ぶ」をクリックすると、クライアントは認可URLを組み立て、ユーザーを認可サーバーへリダイレクトします。

シーケンス図。緑で示した1から3の矢印が、Step1の認可リクエスト。 ユーザー (ブラウザ) クライアント (写真プリントサービス) print.example.com 認可サーバー (Instagram) auth.example.net リソースサーバー (Instagram API) api.example.net 1 「写真を選ぶ」を押す 2 認可画面へリダイレクト 3 認可リクエスト 4 ログイン・同意画面を表示 5 ログインして許可 6 redirect_uriへリダイレクト(認可コード付き) 7 認可コードを届ける 8 コード+ID+シークレット 9 アクセストークン 10 トークン付きでAPIリクエスト 11 写真データ

このリダイレクトを受けて、ブラウザが認可サーバー(auth.example.net)に送るHTTPリクエストは次のとおりです(見やすさのため改行しています)。

GET /authorize?response_type=code
  &client_id=s6BhdRkqt3
  &redirect_uri=https%3A%2F%2Fprint.example.com%2Fcallback
  &scope=photos.read
  &state=35ce HTTP/1.1
Host: auth.example.net
パラメータ内容
response_type使用する認可フロー。認可コードフローならcode
client_idクライアントの識別子
redirect_uriユーザーが許可した後に、認可サーバーがリダイレクトする先のURL。ここではクライアントのコールバックURL(https://print.example.com/callback)
scope要求するアクセス権限の範囲(この例では写真の読み取り)
stateCSRF対策用の推測できない値(後述)

Step 2:ログインと同意(図の4,5)

ユーザーは認可サーバー(Instagram)でログインし、クライアントが写真にアクセスすることに同意します。冒頭で触れた「このアプリにアカウントへのアクセスを許可しますか?」という画面が、この同意画面です。パスワードを入力する相手は認可サーバーだけで、クライアントには渡りません。

シーケンス図。緑で示した4と5の矢印が、Step2のログインと同意。 ユーザー (ブラウザ) クライアント (写真プリントサービス) print.example.com 認可サーバー (Instagram) auth.example.net リソースサーバー (Instagram API) api.example.net 1 「写真を選ぶ」を押す 2 認可画面へリダイレクト 3 認可リクエスト 4 ログイン・同意画面を表示 5 ログインして許可 6 redirect_uriへリダイレクト(認可コード付き) 7 認可コードを届ける 8 コード+ID+シークレット 9 アクセストークン 10 トークン付きでAPIリクエスト 11 写真データ

Step 3:認可コードの発行(図の6,7)

同意後、認可サーバーはユーザーをredirect_uri(=クライアント(print.example.com))へリダイレクトします。このときURLに認可コードが埋め込まれ、ブラウザ経由でクライアントに届きます。

シーケンス図。緑で示した6と7の矢印が、Step3の認可コードの発行。 ユーザー (ブラウザ) クライアント (写真プリントサービス) print.example.com 認可サーバー (Instagram) auth.example.net リソースサーバー (Instagram API) api.example.net 1 「写真を選ぶ」を押す 2 認可画面へリダイレクト 3 認可リクエスト 4 ログイン・同意画面を表示 5 ログインして許可 6 redirect_uriへリダイレクト(認可コード付き) 7 認可コードを届ける 8 コード+ID+シークレット 9 アクセストークン 10 トークン付きでAPIリクエスト 11 写真データ

認可サーバーがブラウザに返すのは、次のHTTPレスポンスです。

HTTP/1.1 302 Found
Location: https://print.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=35ce

1行目の302 Foundはステータスコードで、「別のURLに移ってほしい」という意味です。移る先のURLは、2行目のLocationヘッダーに書かれています。この仕組みをHTTPリダイレクトと呼びます。

ブラウザは302を受け取ると、LocationのURLへ自動でアクセスし直します。認可サーバーはクライアントに直接コードを送るのではなく、ブラウザに「このURLへ行って」と伝えているわけです。図の6が302レスポンス、7がブラウザのアクセスし直しにあたります。図の2と3(Step 1)も同じ仕組みです。

HTTPリダイレクトの図。認可サーバーが302 FoundとLocationヘッダーをブラウザに返し、ブラウザはLocationのURLへ自動でアクセスし直して、クライアントに認可コードを届ける。 ユーザー (ブラウザ) クライアント (写真プリントサービス) print.example.com 認可サーバー (Instagram) auth.example.net 6 302 Found(Location: https://print.example.com/callback?code=…) LocationのURLへ自動でアクセスし直す 7 GET /callback?code=…

認可サーバーは、発行した認可コード(code=SplxlOBeZQQYbYS6WxSbIA)を、認可リクエストに含まれていたclient_id(s6BhdRkqt3)と紐付けておきます。

Step 4:認可コードをアクセストークンと交換(図の8,9)

クライアントはURLから取り出した認可コードを、クライアントID・クライアントシークレットと一緒に認可サーバーへ送り、アクセストークンを受け取ります。この通信はブラウザを経由しない、サーバー間のやり取りです。

シーケンス図。緑で示した8と9の矢印が、Step4のトークン交換。 ユーザー (ブラウザ) クライアント (写真プリントサービス) print.example.com 認可サーバー (Instagram) auth.example.net リソースサーバー (Instagram API) api.example.net 1 「写真を選ぶ」を押す 2 認可画面へリダイレクト 3 認可リクエスト 4 ログイン・同意画面を表示 5 ログインして許可 6 redirect_uriへリダイレクト(認可コード付き) 7 認可コードを届ける 8 コード+ID+シークレット 9 アクセストークン 10 トークン付きでAPIリクエスト 11 写真データ
POST /token HTTP/1.1
Host: auth.example.net
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fprint.example.com%2Fcallback

Authorizationヘッダーの値はclient_id:client_secretをBase64エンコードしたものです。シークレットを提示することで、リクエストが正当なクライアントから来たことを証明します。

{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "token_type": "Bearer",
  "expires_in": 3600
}

ポイントは次の3つです。

  • クライアントシークレットは機密性が非常に高く、外部に公開してはいけない
  • 認可コードは使い捨て(1回限り)にするのがベストプラクティス
  • 交換時のredirect_uriは、認可リクエスト時と同じ値を送る

Step 5:APIへのアクセス(図の10,11)

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

シーケンス図。緑で示した10と11の矢印が、Step5のAPIアクセス。 ユーザー (ブラウザ) クライアント (写真プリントサービス) print.example.com 認可サーバー (Instagram) auth.example.net リソースサーバー (Instagram API) api.example.net 1 「写真を選ぶ」を押す 2 認可画面へリダイレクト 3 認可リクエスト 4 ログイン・同意画面を表示 5 ログインして許可 6 redirect_uriへリダイレクト(認可コード付き) 7 認可コードを届ける 8 コード+ID+シークレット 9 アクセストークン 10 トークン付きでAPIリクエスト 11 写真データ
GET /photos HTTP/1.1
Host: api.example.net
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

認可コードを一度挟む理由

認可コードフローには、データの通り道が2つあります。ブラウザを通る道と、サーバー同士で直接やり取りする道です。

データの通り道の図。認可コードは認可サーバーからブラウザを通ってクライアントへ届き、URLに載るため、途中で傍受される可能性がある。アクセストークンは、クライアントと認可サーバーのあいだでブラウザを通らずに直接受け渡される。 ユーザーのブラウザURLが履歴やログに残る 認可サーバーauth.example.net クライアントprint.example.com 認可コード (URLに載る) 認可コード (URLに載る) 傍受される 可能性がある コード+シークレット アクセストークン サーバー同士で直接(ブラウザを通らない)

ブラウザのリダイレクトでURLに載るのは認可コードだけで、アクセストークンはサーバー同士の道でしか受け渡されません。URLはブラウザの履歴やログに残りやすく、途中で傍受されて第三者に見られるおそれがあります。認可コードは単体ではAPIにアクセスできず、トークンに交換するにはクライアントシークレットが必要です。そのため、仮に認可コードが漏れても、すぐには悪用されません。

攻撃への対応

認可コードフローの手順どおりに作っても、ブラウザのリダイレクトを悪用する攻撃があります。ここでは代表的な2つと、その防ぎ方を図で見ていきます。

CSRF対策

プリントサービスに、加工した写真を連携先のInstagramへ保存する機能もあるとします。stateを使っていない場合、次の手順で被害者の写真が攻撃者に取られてしまいます。赤い矢印が、攻撃にあたるステップです。

stateがない場合のCSRF攻撃のシーケンス図。攻撃者は自分のアカウントの認可コードを手に入れ、そのコードを付けた罠のリンクを被害者に開かせる。被害者のアカウントに攻撃者のInstagramが連携され、被害者が保存した写真が攻撃者のアカウントに届く。赤い矢印が攻撃のステップ。 攻撃者 被害者 (ブラウザ) クライアント (写真プリントサービス) print.example.com Instagram (認可サーバー・API) *.example.net 1 自分のアカウントでログイン・許可 2 攻撃者用の認可コード クライアントに送らず止めておく 3 罠のリンクを送る 4 攻撃者のコードを届ける 5 コードをトークンに交換 6 攻撃者のトークン 被害者に攻撃者のInstagramが連携される 7 写真をInstagramに保存 8 被害者の写真を保存 攻撃者のアカウントに保存される

攻撃者は、自分のInstagramアカウントで認可コードを手に入れ、それをクライアントに送らずに止めておきます(1,2)。そして、このコードを付けたコールバックURL(https://print.example.com/callback?code=攻撃者のコード)を罠のリンクとして被害者に開かせます(3,4)。

クライアントには、届いたコードが被害者の操作によるものか、攻撃者が仕込んだものかを見分ける手段がありません。そのままトークンに交換し、被害者のプリントサービスのアカウントに、攻撃者のInstagramアカウントを連携してしまいます(5,6)。この状態で被害者が写真を保存すると、写真は攻撃者のアカウントに届きます(7,8)。

このように、罠のリンクなどを使って、本人が意図していないリクエストを送らせる攻撃をCSRF(クロスサイトリクエストフォージェリ)と呼びます。

そこで登場するのがstateパラメータです。役割は主に、クライアントに戻ってきたコードが、同じブラウザで自分が始めた認可リクエストに対するものかを確かめることです。次の流れで確かめます。

  • a:クライアントは推測できないランダムな値を作ってセッションに保存し、認可リクエストに付ける
  • b:認可サーバーは、リダイレクトのときに同じstateをそのまま返す
  • c:クライアントは、返ってきた値とセッションの値を比べ、一致しなければ処理を中断する
stateの流れのシーケンス図。a、クライアントがstateを作ってセッションに保存し、認可リクエストに付ける。b、認可サーバーがリダイレクトで同じstateを返す。c、クライアントがセッションの値と比べて確認する。 ユーザー (ブラウザ) クライアント (写真プリントサービス) print.example.com 認可サーバー (Instagram) auth.example.net a state=35ceを作り、セッションに保存 リダイレクト(state=35ce) 認可リクエスト(state=35ce) ログイン・同意 b リダイレクト(code=…&state=35ce) codeとstateを届ける c セッションの値と一致 → 続ける

攻撃者が罠のリンクを使っても、リンクに入っているstateは、攻撃者が自分のブラウザで手に入れた値です。被害者のセッションに保存された値とは一致しないので、cの確認で止まります。

stateでCSRF攻撃を止めるシーケンス図。攻撃者が罠のリンクを送り、被害者がクライアントに攻撃者のコードとstateを届けるが、cの確認で被害者のセッションの値と一致しないため中断する。 攻撃者 被害者 (ブラウザ) クライアント (写真プリントサービス) print.example.com 3 罠のリンクを送る 4 攻撃者のcodeとstateを届ける c セッションの値と不一致 → 中断

オープンリダイレクト対策

認可サーバーがredirect_uriに許可する値を制限していないと、攻撃者はredirect_uriを自分のサーバー(evil.example.org)にした罠のリンクを作れます。

https://auth.example.net/authorize?response_type=code
  &client_id=s6BhdRkqt3
  &redirect_uri=https%3A%2F%2Fevil.example.org%2Fcallback

被害者がこのリンクを開いた場合、次の手順で認可コードが攻撃者に取られてしまいます。

オープンリダイレクト攻撃のシーケンス図。攻撃者がredirect_uriを攻撃者のURLにした罠のリンクを送り、被害者のブラウザが認可リクエストを送る。ログイン済みなので認可サーバーはすぐに攻撃者のURLへリダイレクトし、認可コードが攻撃者に届く。赤い矢印が攻撃のステップ。 攻撃者 (攻撃者のサーバー) evil.example.org 被害者 (ブラウザ) 認可サーバー (Instagram) auth.example.net 1 罠のリンクを送る 2 認可リクエスト(redirect_uri=攻撃者のURL) ログイン済みなので、すぐにコードを発行 3 攻撃者のURLへリダイレクト(code付き) 4 認可コードが届く

被害者がすでにInstagramにログインしていて、以前に許可も済ませていれば、ログイン画面も同意画面も出ません(2,3)。認可サーバーはそのままredirect_uriへリダイレクトし、認可コードが攻撃者のサーバーに届きます(4)。認可コードはアクセストークンと交換するための引換券なので、これを取られるのは危険です。

2と3は、通常の認可コードフローとまったく同じやり取りです。違うのはredirect_uriの中身だけなので、認可サーバーがここを確かめないと防げません。

そこで認可サーバーは、redirect_uriを事前に登録された値と完全一致で比べます。役割は、認可コードの送り先を、クライアントが登録したURLだけに限ることです。次の流れで確かめます。

  • a:クライアントは事前に、自分のコールバックURL(https://print.example.com/callback)を認可サーバーに登録しておく
  • b:認可リクエストが来たら、認可サーバーはredirect_uriが登録済みのURLと完全に一致するかを確かめる
  • c:一致しなければリダイレクトせず、エラー画面を出す
redirect_uriの完全一致でオープンリダイレクト攻撃を止めるシーケンス図。a、クライアントが事前にコールバックURLを登録する。b、認可サーバーがredirect_uriを登録済みのURLと比べる。c、一致しないのでリダイレクトせずエラー画面を出す。 攻撃者 (攻撃者のサーバー) evil.example.org 被害者 (ブラウザ) 認可サーバー (Instagram) auth.example.net クライアント (写真プリントサービス) print.example.com a コールバックURLを登録 あとで、攻撃者が罠を仕掛ける 1 罠のリンクを送る 2 redirect_uri=攻撃者のURL b 登録済みのURLと完全一致? → 不一致 c エラー画面を表示 リダイレクトしない(コードは出ない)

cでリダイレクトしないので、認可コードは攻撃者に届きません。前方一致や部分一致で比べると、https://print.example.com.evil.example.org/callbackのようなURLにすり抜けられることがあるため、完全一致で比べます。

まとめ

  • OAuthは、パスワードを渡さずに「範囲」と「期間」を限定したアクセス権を委譲する仕組み
  • 認可コードフローは「認可コード → アクセストークン」の2段階で、トークンをURLに露出させない
  • stateでCSRFを、redirect_uriの完全一致でオープンリダイレクトを防ぐ

次回予告

今回の認可コードフローは、クライアントシークレットを安全に保管できるWebアプリ(コンフィデンシャルクライアント)が前提でした。では、シークレットを持てないスマホアプリ(パブリッククライアント)はどうするのか。

そこで使われるのがPKCE(Proof Key for Code Exchange)という仕組みです。OAuthの新しい版であるOAuth 2.1では、PKCEと組み合わせることで、パブリッククライアントもこのフローを使います。PKCEについては、次の記事で図を使って整理しました。

参考