本記事は Digital Identity技術勉強会 #iddance Advent Calendar 2020 17日目の記事です。
こんにちは、富士榮です。
今日は年末ということもあり、普段はあまり表舞台に出てこないOpenID ConnectのOptionalなオプションにフォーカスを当ててみようかと思います。
対象とする仕様は「OpenID Connect Core 1.0」とします。
- 日本語訳（By OpenIDファウンデーションジャパン翻訳・教育WG）
- オリジナル
OpenID Connectの設計思想
OpenID ConnectはいわゆるID連携（Federation）を行うための仕様として、OAuth2.0の上位にアイデンティティ層を載せる形で定義されています。
そして、その設計思想は、
- 簡単なことは簡単に
- 難しいことも可能に
- モジュラーデザイン
という原則に則っています。
この中の最初の原則である「簡単なことは簡単に」という部分が普段みなさんが使っているOpenID Connectを使ったログオンの実装の大半で、上記の仕様の第2章「Authentication」に定義されているAuthorization code flow、Implicit flow、Hybrid flowの3つ、特にAuthorization code flowを覚えておけば基本的なWebアプリケーションへのログインのシナリオでは何も難しいことはありません。
※当然、セキュリティ上の考慮事項などはそれなりに存在するため、stateやnonceを正しく使ってcodeを横取りされたりid_tokenを使いまわされることを防いだりする必要はありますので運用環境で使うためにはちゃんと仕様を理解して実装する必要はありますが。。。
また、2つ目の「難しいことも簡単に」、3つ目の「モジュラーデザイン」の原則の通り、OpenID Connect DiscoveryやOpenID Connect Dynamic Client Registrationなど関連仕様との組み合わせでより高度なシナリオにも対応することができるようになっています。
今回はニッチを狙いますので、OPTIONALなパラメータを重点的に見ていきたいと思います。
RFCにおける要求レベルの定義
仕様を読んでいるとMUST、SHOULD、MAY、OPTIONALなど各パラメータ毎に要求レベルが定義されています。
この要求レベル自体はRFC2119で以下の通り定義されています。
※RFC2119の日本語訳はIPAのホームページで公開されています。
以下、IPAの日本語訳です（赤字・太字は筆者）。
- 「しなければならない（ MUST ）」
- この語句、もしくは「要求されている（ REQUIRED ）」および「することになる（ SHALL ）」は、その規定が当該仕様の絶対的な 要請事項であることを意味します。
- 「してはならない（ MUST NOT ）」
- この語句、もしくは「することはない（ SHALL NOT ）」は、その規定が当該仕様の絶対的な禁止事項であることを意味します。
- 「する必要がある（ SHOULD ）」
- この語句もしくは「推奨される（ RECOMMENDED ）」という形容表現は、 特定の状況下では、特定の項目を無視する正当な理由が存在するかもしれませんが、 異なる選択をする前に、当該項目の示唆するところを十分に理解し、 慎重に重要性を判断しなければならない、ということを意味します。
- 「しないほうがよい（ SHOULD NOT ）」
- この語句もしくは「推奨されない（ NOT RECOMENDED ）」という形容表現は、 特定の動作が容認できる、ないし、非常に有用である、というような 特定の状況下では、正当な理由が存在するかもしれませんが、 このレベルの動作を実装する前に、当該項目の示唆するところを十分に理解し、慎重に重要性を判断しなければならない、ということを意味します。
- 「してもよい（ MAY ）」
- この語句、もしくは「選択できる（ OPTIONAL ）」という形容表現は、ある要素が、まさに選択的であることを意味します。 その要素を求めている特定の市場があるから、あるいは、 他のベンダーはその要素を提供しないだろうが、その製品機能を拡張する と察知して、その要素を含む選択をするベンダーがあるかもしれません。 特定の選択事項（オプション）を含まない実装は、おそらく機能的には劣る ことになるでしょうが、そのオプションを含む他の実装との相互運用に備えなければなりません（ MUST ）。 同様に、特定のオプションを含む実装は、そのオプションを含まない実装 との相互運用に備えなければなりません（ MUST ）。（当然ながら、そのオプションが提供する機能は除かれます。）
まさに今回のターゲットはMAY、もしくはOPTIONALな部分です。
MAYとOPTIONALを仕様から抽出する
早速、仕様の中にどのくらいMAYとOPTIONALがあるのか抽出してみます。
- MAY：87個
- OPTIONAL：53個
・・・結構ありますね。
全部カバーしているとキリがないので、独断と偏見でMAY/OPTIONALを5個選んで番付的に紹介してみようと思います。
※もちろんOPTIONALなので実装しているOpenID Providerばかりではありませんので、動かしてみても期待する反応がえられないケースが多いので悪しからず。
十両：prompt
認証リクエストにpromptパラメータを付加することで再認証や同意を求めることができます。
仕様では3.1.2.1のAuthentication Requestの項に定義されています。（OpenIDファウンデーションジャパンの日本語訳から引用）
OPTIONAL. Authorization Server が End-User に再認証および同意を再度要求するかどうか指定するための, スペース区切りの ASCII 文字列のリスト. 以下の値が定義されている.prompt パラメータは Client に対して, End-User のセッションがアクティブであることを確認したり, End-User にリクエストに対する注意を促すことを可能にする. none がその他の値とともに用いられる場合はエラーとなる.
- none
- Authorization Server はいかなる認証および同意 UI をも表示してはならない (MUST NOT). End-User が認証済でない場合, Client が要求する Claim 取得に十分な事前同意を取得済でない場合, またはリクエストを処理するために必要な何らかの条件を満たさない場合には, エラーが返される. 典型的なエラーコードは login_required, interaction_required であり, その他のコードは Section 3.1.2.6 で定義されている. これは既存の認証と同意の両方, またはいずれかを確認する方法として使用できる.
- login
- Authorization Server は End-User を再認証するべきである (SHOULD). 再認証が不可能な場合はエラーを返す (MUST). 典型的なエラーコードは login_required である.
- consent
- Authorization Server は Client にレスポンスを返す前に End-User に同意を要求するべきである (SHOULD). 同意要求が不可能な場合はエラーを返す (MUST). 典型的なエラーコードは consent_required である.
- select_account
- Authorization Server は End-User にアカウント選択を促すべきである (SHOULD). この prompt 値は, End-User が Authorization Server 上に複数アカウントを持っているとき, 現在のセッションに紐づくアカウントの中から一つを選択することを可能にする. End-User によるアカウント選択が不可能な場合はエラーを返す (MUST). 典型的なエラーコードは account_selection_required である.
アプリの仕様でトランザクションの種類によって強制再認証を求めたり、同意を求めたりするケースもあると思うので、そのような場合はうまくpromptパラメータを使うと良いですね。
前頭：target_link_uri
SAMLでいうrelayStateですね。
仕様にも記載がありますが、全てのログインフローがRelying PartyからOPへのリクエストによって始まるわけではなく、OP起点だったり別のシステム（ポータルなど）から起動されることもあります。そのような場合、ログインフローを起動するシステムはRPのログイン開始エンドポイントへユーザをリダイレクトしてフローを起動するわけですが、ログインが完了した後、必ずしもRPのデフォルトのランディングページに着地させたいわけではなく、別のページへ飛ばしたい、というケースもあります。そのような場合にtarget_link_uriに指定するとログイン完了後に望むページへ遷移させることができます。
ただ、注意点として記載がある通りOpenリダイレクタにならないように指定できるURLはきちんと検証しないといけません。
仕様では4のInitiating Login from a Third Partyの項に定義されています。（OpenIDファウンデーションジャパンの日本語訳から引用）
target_link_uri OPTIONAL. 認証後, RP がリダイレクトするよう要求された URL. RP は外部サイトへのオープンリダイレクターとして使用されることを防ぐために target_link_uri の値を検証しなければならない(MUST).
SAMLを使ったシステム導入の際はrelayStateに関する要望は結構あったので、今後このパラメータもメジャーになってくるかな？と思います。
関脇：request/request_uri
いわゆるRequest Objectです。FAPI Part2では認可要求自体への署名が要求されるので、普通にQuery Stringに各種リクエストパラメータをくっつけるのではなく、JWTとして認可サーバへ渡してあげる必要があります。また認可要求にJWTそのものを渡すこともできますが、request_uriに指定したエンドポイントを参照させることによりリクエストパラメータを取りに来てもらうこともできます。
仕様では6のPassing Request Parameters as JWTsの項に定義されています。（OpenIDファウンデーションジャパンの日本語訳から引用）
request OPTIONAL. このパラメータにより, OpenID Connect リクエストを単一の self-contained なパラメータとすることができ, 任意で署名および暗号化を施せるようになる. パラメータ値は Request Object 値である (Section 6.1 参照). Request Object は, 各 Claim がリクエストパラメータとなる JWT である. request_uri OPTIONAL. このパラメータにより, 値そのものではなく参照を送ることが可能になる. request_uri 値は https スキーマで始まる URL であり, Request Object 値を含むリソースへの参照となる. 参照先の Request Object は, リクエストパラメータを含む JWT である.
金融サービスに限らず要求についても隠蔽したいケースや署名をつけて確実に渡したいケースではこのパラメータは活躍する場面がありそうです。
大関：id_token_hint
完全に個人的な趣味です。実はAzure ADを使っていると結構活躍の機会が多いんです。例えば今はもう新規のサポートは受け付けていませんがPremium P2の機能のカスタムMFAプロバイダへのセッション引き継ぎはid_token_hintを使って行っていましたし、そもそもOffice365→Azure AD→外部IdPというようなチェーン構成のフェデレーションでは前段で入力されたユーザ名のドメインパートに基づきログイン先のIdPを動的に変更する、なんということもよくやります。そのようなケースでは前段のIdPでのユーザの挙動（入力した値や、その値から導き出された値など）を連鎖する後段のIdPにも伝えないと、ユーザ名を2回入力する必要が出てきたり、とUXを毀損してしまいがちです。
このようなケースではid_token_hintの中に必要なパラメータを詰め込んで後段のIdPへJWTとして渡してあげることで格段にUXが向上します。
(Office365のケースではOpenID Connect→ws-federationの連鎖なのでusernameというパラメータを使っていますが）
仕様では3.1.2.1のAuthentication Requestの項に定義されています。（OpenIDファウンデーションジャパンの日本語訳から引用）
id_token_hint OPTIONAL. Authorization Server が以前発行した ID Token. Client が認証した End-User の現在もしくは過去のセッションに関するヒントとして利用される. もしこの ID Token に紐づく End-User が認証済, もしくはこのリクエスト中で認証された場合, Authorization Server はポジティブレスポンスを返す. さもなければ, Authorization Server は login_required のようなエラーを返す (SHOULD). prompt=none を利用する場合は, 可能であれば id_token_hint を指定するべきであり (SHOULD), さもなければ invalid_request を返しても良い (MAY). ただしサーバーはその場合可能な限りサクセスレスポンスを返すこと. id_token_hint 利用時は, ID Token の audience に Authorization Server 自身が含まれている必要はない. id_token_hint として使用するために RP によって受信された OP からの ID Token が暗号化されていた場合, クライアントは暗号化された ID Token を含んだ署名済みの ID Token を復号しなければならない (MUST). クライアントは Authentication Server に送信する署名済みの ID Token をサーバーが ID Token を復号できる鍵を用いて再暗号化し, id_token_hint の値として使用してもよい (MAY).
横綱：claims
最後の横綱級はなんといってもclaimsでしょう。理由はシンプルで私も共同議長を勤めさせていただいるOpenID FoundationのeKYC and Identity Assurance WGで策定中のOpenID Connect for Identity Assuranceの仕様はclaimsがあるから成り立っている、といっても過言ではないからです。
パラメータの意味合いとしてはRPからOPへの認証要求時にclaimsに指定した属性をid_tokenもしくはuserInfoとして提供することを明示的に求める、というものです。OpenID Connect for Identity Assuranceではこの機能を拡張してRPがOPに検証済みの属性を要求する、ということを実現しています。
仕様では5.5のRequesting Claims using the "claims" Request Parameterの項に定義されています。（OpenIDファウンデーションジャパンの日本語訳から引用）
- claims
- OPTIONAL. 当パラメータは, 特定の Claim の返却を要求するのに用いられる. 値は要求する Claim をリスト化した JSON オブジェクトである.
claims Authentication Request パラメータは, 特定の Claim を UserInfo Endpoint から, かつ/または ID Token 内で, 返却することを要求する. これは要求する Claim のリストを含む JSON オブジェクトとして表される. 要求する Claim のプロパティが指定されていてもよい (MAY).
claims パラメータのサポートは任意である (OPTIONAL). 当パラメータをサポートしない OP に対して RP が当パラメータを使用したとき, OP は 適切と思われるヒューリスティックな方法を用いて, RP と End-User にとって有益と思われる Claim のセットを返すべきである (SHOULD). Discovery で得られる claims_parameter_supported は, OP が当パラメータをサポートしているかどうかを示す.
claims パラメータ値は, OAuth 2.0 要求の中で, UTF-8 でエンコードされた JSON として表される (最終的には OAuth パラメータとして受け渡されるときに form-urlencoded される). Request Object 値として使用される際は, Section 6.1 により, JSON が claims メンバーの値として使用される.
Claim 要求 JSON オブジェクトのトップレベルメンバーは以下の通り:
- userinfo
- OPTIONAL. UserInfo Endpoint へ返却を要求する個々の Claim のリストを示す. 当メンバーが存在した場合, scope 値で要求された Claim に加え, 当メンバーでリストされた Claim も返却される. 当メンバーが存在しなかった場合, scope 値で要求された Claim のみが返却される.
- userinfo メンバーを指定する際は, UserInfo Endpoint を使用するために, response_type に対し, Access Token を Client に発行するタイプの値を指定しなければならない (MUST).
- id_token
- OPTIONAL. ID Token 内に格納して返却を要求する個々の Claim のリストを示す. 当メンバーが存在した場合, デフォルトの Claim に加え, 当メンバーでリストされた Claim も返却される. 当メンバーが存在しなかった場合, デフォルトの Claim のみが返却される. デフォルトの Claim 等の ID Token の定義については Section 2を, フロー毎の ID Token 要件については Section 3.1.3.6, 3.2.2.10, 3.3.2.11, 3.3.3.6 を参照すること.
上記以外のメンバーが存在してもよい (MAY). 認識できないメンバーが使用された場合は無視しなければならない (MUST).
通常のOPでclaimsを利用している実装ってあまり見かけないのですが、先日某芸能事務所のファンクラブサイトに娘がログインするところをトレースしていたらclaimsを使っているのが判明し驚愕しました(w)
いかがでしたか？
他にもご紹介したいニッチなパラメータもいっぱいあるので、また機会があればご紹介できればと思います。