EN

OpenID Connectを図で整理する

目次

はじめに

前々回はOAuthの認可コードフローを、前回はPKCEを、写真プリントサービスがInstagramの写真を取り込む例で整理しました。どちらも、テーマは「プリントサービスに写真を読ませてよいか」でした。

今回は、同じプリントサービスに「Instagramでログイン」を付けるケースを考えます。会員登録をしなくても、Instagramのアカウントでログインでき、注文履歴もそのアカウントにひもづく、という機能です。

ここで必要になるのは「何をしてよいか」ではなく、「ログインしたのは誰か」という情報です。OAuthはもともとこれに答える仕組みではないので、OAuthの上にOpenID Connect(OIDC)を重ねて使います。今回は、OIDCがOAuthに何を足すのかを、前回までと同じ例とシーケンス図で整理します。

登場人物とドメインは前回までと同じです。実際のInstagramがOIDCに対応しているかは別として、ここでは認可サーバー(auth.example.net)がOIDCに対応しているものとして進めます。

OAuthだけでログインすると困ること

前回までのフローで、プリントサービスの手元に残るのはアクセストークンです。アクセストークンは「写真を読んでよい」という入館証のようなもので、持ち主が誰なのかは書かれていません。そもそも、プリントサービスが中身を読めるとも限りません。

それでも「誰か」を知ろうとすると、アクセストークンでプロフィールを返すAPIを呼び、返ってきたIDでログインさせる作りになりがちです。ただ、この作りには2つの問題があります。

1つ目は、プロフィールを返すAPIの形がサービスごとにばらばらなことです。Instagram用、X用、Google用と、つなぐ先ごとに別の実装が要ります。

2つ目は、アクセストークンが誰宛てに発行されたのかを、受け取った側が確かめられないことです。たとえば、ブラウザやスマホアプリからアクセストークンを受け取ってログインさせる作りだと、別のアプリ向けに発行されたトークンを持ち込まれても見分けられません。持ち込んだ人は、トークンの持ち主としてログインできてしまいます。

OIDCは、この2つを「誰がログインしたか」を伝える専用の入れ物と、その受け渡しの決まりを用意して解決します。

OpenID Connectとは

OpenID Connectは、OAuth 2.0の上に乗る、認証(ログインしたのは誰かを確かめること)のための仕様です。新しいフローを一から作るのではなく、前回までの認可コードフローに、いくつかのパラメータとトークンを足します。

OAuth 2.0の認可コードフローの上に、PKCEとOpenID Connectが並んで乗っている図。PKCEは認可コードの横取りを防ぎ、OpenID Connectは誰がログインしたかを伝える。OAuth 2.0そのものは何をしてよいかを決める。 PKCE(前回) code_verifier code_challenge 認可コードの横取りを防ぐ OpenID Connect(今回) scope=openid・IDトークン・nonce UserInfo・Discovery 「誰がログインしたか」を伝える OAuth 2.0の認可コードフロー 認可コード・アクセストークン 「何をしてよいか」を決める

PKCEもOIDCも、同じ認可コードフローに足す拡張で、両方をいっしょに使えます。PKCEが守るのは認可コードの受け渡しで、OIDCが足すのは「誰か」を伝える仕組みなので、役割はぶつかりません。

OIDCでは、OAuthの登場人物を別の名前で呼びます。

OIDCでの呼び名OAuthでの呼び名写真プリントの例
OP(OpenID Provider)認可サーバーInstagramの認可サーバー(auth.example.net)
RP(Relying Party)クライアント写真プリントサービス(print.example.com)
エンドユーザーリソースオーナーInstagramでログインするあなた

OPは「ユーザーが誰かを証明する側」、RPは「その証明を信頼して(rely on)ログインさせる側」です。IdP(Identity Provider)と呼ぶこともありますが、この記事ではOPで通します。

IDトークンとアクセストークン

OIDCで増えるいちばん大きなものが、IDトークンです。認可コードと交換すると、OPはアクセストークンと一緒にIDトークンを返します。手元のトークンは2つになります。

IDトークンとアクセストークンの行き先の図。OPは2つをまとめてRPに渡す。RPはIDトークンを読んで誰がログインしたかを知り、IDトークンはRPで止まる。APIに送るのはアクセストークンだけ。 OP 認可サーバー RP クライアント API リソースサーバー IDトークン アクセストークン 送らない アクセストークン 2つまとめて発行 「誰か」を知る 権限を確かめる

2つのトークンは、読む人も行き先も違います。

IDトークンアクセストークン
たとえ身分証入館証
伝えることログインしたのは誰か何をしてよいか
読む人RPAPI(リソースサーバー)
宛先RP(中にclient_idが入る)API
形式必ずJWTOPしだい(JWTとは限らない)

IDトークンはRPが読んで、そこで役目を終えます。APIを呼ぶときに送るのはアクセストークンだけで、IDトークンをAPIに送ってはいけません。逆に、アクセストークンを「誰か」の証明に使うのも、「OAuthだけでログインすると困ること」で見たとおり避けます。

IDトークンには宛先(RPのclient_id)が書かれていて、OPの署名も付いています。そのため、RPは「自分宛てに、正しいOPが発行したものか」を自分で確かめられます。さきほどの2つ目の問題(別のアプリ向けのトークンを持ち込まれる)は、これで解決します。

OIDCの認可コードフロー

全体像

前回までのフローに、OIDCで増える部分を緑で、前回のPKCEの部分を紫で示しました。今回のプリントサービスはWebアプリなので、リダイレクト先はhttps://print.example.com/callbackです。

OpenID Connectの認可コードフロー全体のシーケンス図。緑で示した2、4、10、11、12がOIDCで増える部分、紫の9が前回のPKCE。2でRPがstate・code_verifier・nonceを作り、4でscope=openidとnonceを付けて認可リクエストを送る。10でOPがIDトークンとアクセストークンを返し、11でRPがIDトークンを検証してログイン完了。12で必要ならUserInfoから属性を取り、13でアクセストークンを付けてAPIを呼ぶ。 ユーザー (ブラウザ) RP / クライアント (写真プリント) print.example.com OP / 認可サーバー (Instagram) auth.example.net リソースサーバー (Instagram API) api.example.net 1 「Instagramでログイン」を押す 2 state・verifier・nonceを作って保存 3 認可画面を開く 4 認可リクエスト(scope=openid・nonce付き) 5 ログイン・同意画面を表示 6 ログインして許可 7 リダイレクト(認可コード付き) 8 コードとstateを渡す 9 コード+verifier 10 IDトークン+アクセストークン 11 IDトークンを検証 → ログイン完了 12 UserInfo(必要なとき) 13 トークン付きでAPIリクエスト

番号の流れは前回までとほとんど同じです。違うのは、nonceを作ること(2)、認可リクエストにscope=openidとnonceを付けること(4)、IDトークンが返ってくること(10)、RPがそれを検証してログインを終えること(11)です。12のUserInfoは、IDトークンに入っていない属性がほしいときだけ使います。

ログインが目的なら、13のAPI呼び出しはなくてもかまいません。写真も読みたいなら、同じフローで受け取ったアクセストークンをそのまま使えます。

認可リクエスト(図の4)

ブラウザがOPに送るリクエストは次のとおりです(見やすさのため改行しています)。

GET /authorize?response_type=code
  &client_id=s6BhdRkqt3
  &redirect_uri=https%3A%2F%2Fprint.example.com%2Fcallback
  &scope=openid%20profile%20email%20photos.read
  &state=35ce
  &nonce=n-0S6_WzA2Mj
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256 HTTP/1.1
Host: auth.example.net

前々回のリクエストに足したのは、scopeのopenid・profile・emailと、nonce、それに前回のPKCEの2つです。

パラメータ内容
scope=openidOIDCを使うという合図。これがないと、ただのOAuthとして扱われ、IDトークンは返ってこない
profile・email名前やメールアドレスなど、ほしい属性の範囲。OIDCで決められているスコープ
nonceRPが作る使い捨てのランダムな値。OPはこれをIDトークンの中にそのまま入れて返す(後述)

photos.readは前々回からある、写真を読むためのスコープです。ログインだけが目的なら要りません。

トークンレスポンス(図の10)

認可コードを交換するリクエストは、前々回と前回のものを合わせた形です。Webアプリなのでクライアントシークレットを送り、PKCEのcode_verifierも送ります。OIDCで変わるのは、返ってくるレスポンスのほうです。

{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.eyJpc3Mi...(長いので省略)"
}

前々回のレスポンスにid_tokenが1つ増えただけです。この文字列がIDトークンで、中身はこのあと見ていきます。

使い捨ての値3つ

ここまでで、RPが手順2で作る使い捨ての値が3つになりました。どれもランダムな値ですが、確かめる人と場所、防ぐものが違います。

値確かめる人確かめる場所防ぐもの
state(OAuth)RPコールバック(図の8)CSRF(攻撃者が始めたフローに乗せられる)
code_verifier(PKCE)OPトークンリクエスト(図の9)認可コードの横取り
nonce(OIDC)RPIDトークンの中(図の11)IDトークンの使い回し(リプレイ)

nonceの流れはstateに似ています。RPが作ってセッションに保存し、認可リクエストに付けます。違うのは戻ってくる場所で、stateはリダイレクトのURLに、nonceはOPの署名付きのIDトークンの中に入って戻ってきます。RPはセッションの値と比べ、一致しなければログインさせません。

これで、以前に別の場面で発行されたIDトークンを持ち込まれても、nonceが今回のものと合わないので弾けます。署名の中に入っているので、書き換えることもできません。

IDトークンの中身

JWTの形

IDトークンはJWT(JSON Web Token)という形式で、3つの部分を.でつないだ文字列です。

eyJhbGciOiJSUzI1NiIs...  .  eyJpc3MiOiJodHRwczov...  .  NHVaYe26MbtOYhSKkoKY...
 ヘッダー                    ペイロード                   署名

ヘッダーには署名のアルゴリズム(alg)と鍵のID(kid)が、ペイロードにはユーザーの情報が入ります。署名はOPの秘密鍵で作られていて、RPはOPの公開鍵で確かめます。ヘッダーとペイロードはBase64URLで文字列にしただけなので、誰でも読めます。秘密にしたい情報を入れる場所ではありません。

ペイロード

ペイロードを開くと、次のようなJSONが入っています。JWTの中の項目は「クレーム」と呼びます。

{
  "iss": "https://auth.example.net",
  "sub": "248289761001",
  "aud": "s6BhdRkqt3",
  "exp": 1793581200,
  "iat": 1793577600,
  "nonce": "n-0S6_WzA2Mj",
  "auth_time": 1793577590,
  "amr": ["pwd", "otp"],
  "name": "山田 花子",
  "email": "hanako@example.com",
  "picture": "https://auth.example.net/p/248289761001.jpg"
}
クレーム内容
iss発行したOP。必須
subOPの中でのユーザーID。必須
aud宛先。RPのclient_idが入る。必須
exp・iat有効期限と発行時刻。必須
nonce認可リクエストでRPが送った値。リクエストに付けたなら必ず入る
auth_time・acr・amrログインした時刻、認証の強さ、使った方法(この例ではパスワードとワンタイムパスワード)。任意
name・email・pictureユーザーの属性。scopeのprofile・emailで求めたもの。OPによってはIDトークンに入れず、UserInfoでだけ返す

RPの中でユーザーを見分けるキーには、issとsubの組を使います。subはOPごとに決まる値なので、issと組にしないと、別のOPの同じsubと混ざります。emailはユーザーが変えられるので、キーには向きません。

RPがする検証

IDトークンを受け取ったRPは、ログインさせる前に次の点を確かめます(図の11)。

確かめるもの確かめ方
署名OPの公開鍵(後述のjwks_uriで公開されている)で、改ざんされていないか確かめる
issやり取りしているOPの識別子と同じか
aud自分のclient_idが入っているか
exp有効期限が今より後か
nonce手順2でセッションに保存した値と同じか

1つでも合わなければ、ログインさせません。audの確認が、「OAuthだけでログインすると困ること」で見た、別のアプリ向けのトークンを持ち込まれる問題への答えです。

すべて通ったら、RPはissとsubでユーザーを探し(いなければ作り)、自分のセッションを作ってログインを終えます。IDトークンは「ログインした瞬間に誰だったか」の証明なので、そのままセッションのクッキー代わりに持ち回るものではありません。

実際には、署名の確認も含めてOIDCのライブラリがやってくれることがほとんどです。ただ、何を確かめているのかを知っておくと、設定の漏れに気づきやすくなります。

UserInfoとDiscovery

UserInfo

IDトークンに入っていない属性がほしいときは、UserInfoエンドポイントにアクセストークンを付けて問い合わせます(図の12)。

GET /userinfo HTTP/1.1
Host: auth.example.net
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
{
  "sub": "248289761001",
  "name": "山田 花子",
  "email": "hanako@example.com",
  "email_verified": true
}

UserInfoはアクセストークンで呼ぶ、OP側のAPIです。返ってきたsubがIDトークンのsubと同じかは、RPが確かめます。違う人の情報を取り込まないためです。

Discovery

RPがOPとやり取りするには、認可エンドポイント、トークンエンドポイント、公開鍵の場所などを知っている必要があります。OIDCでは、OPがこれらを決まったURLにJSONで公開します。この仕組みをDiscoveryと呼びます。

URLは、OPの識別子(iss)の後ろに/.well-known/openid-configurationを付けたものです。Googleの実物から抜粋すると、次のようになっています。

https://accounts.google.com/.well-known/openid-configuration
{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "id_token_signing_alg_values_supported": ["RS256"],
  "code_challenge_methods_supported": ["plain", "S256"]
}
項目使う場面
issuerIDトークンのissと比べる
authorization_endpoint認可リクエストの送り先(図の4)
token_endpoint認可コードをトークンと交換する先(図の9)
userinfo_endpoint属性を追加で取る先(図の12)
jwks_uriIDトークンの署名を確かめる公開鍵の置き場所
code_challenge_methods_supported使えるPKCEの方式。前回見たとおりS256を使う

RPの設定に書くのはOPの識別子とクライアントID・シークレットくらいで、残りはDiscoveryから読み込むのが一般的です。OPが鍵を入れ替えても、RPはjwks_uriから新しい鍵を取り直せばよいので、設定を変えずに済みます。

まとめ

  • OAuthは「何をしてよいか」を決める仕組みで、「ログインしたのは誰か」はOIDCが伝える
  • OIDCは新しいフローではなく、認可コードフローにscope=openid・nonce・IDトークンを足したもので、PKCEとも組み合わせられる
  • IDトークンはRP宛ての署名付きJWTで、RPは署名・iss・aud・exp・nonceを確かめてからログインさせる
  • ユーザーはissとsubの組で見分け、エンドポイントや公開鍵の場所はDiscoveryから読み込む

参考