Table of Contents
本リリースは Authlete バージョン 2.2 の最初の一般公開版です。変更点を以下に示します。
Authlete 2.2 は、2021 年 1 月に承認された “Finanicial-grade API” (略称 FAPI) の最終版をサポートします。
最終版と実装者向け草案第 2 版 (2018 年 10 月) との差分のうち、次の要求事項は比較的大きな影響があります。必要に応じ、現在ご使用中のソフトウェアの設定やソースコードを更新する必要があるのでご注意ください。
FAPI 最終版の第 2 部は、リクエストオブジェクトが nbf クレームを含むこと、および、リクエストオブジェクトの生存期間 (exp - nbf) が 60 分以内であることを要求します。
FAPI 最終版の第 2 部は、JWE アルゴリズム RSA1_5 の使用を禁止します。
稼働中のシステムを破壊することなく実装者向け草稿第 2 版から最終版への移行をスムーズにおこなうため、Authlete 2.2 には『nbf クレーム』という設定項目があります。この項目を「任意」としておくと、認可リクエストが FAPI-Part2 リクエストとみなされる場合でも nbf クレームは任意扱いとなります。すなわち、認可サーバーはリクエストオブジェクトの生存期間に関する検証をおこないません。
「任意」とすることで部分的に仕様違反状態とはなりますが、リクエストオブジェクトに nbf を含めるよう全てのクライアントアプリケーションの実装が更新されたことを確認した後にこの設定項目を「必須」に変更することにより、クライアントアプリケーションの不通状態の発生を回避しながら FAPI 最終版に移行することができます。
この設定項目は、authlete-java-common ライブラリ では Service.nbfOptional に対応し、 true が「任意」、 false が「必須」を意味します。
Authlete 2.2 は “JWT Secured Authorization Request” (略称 JAR) をサポートします。
JAR は、OpenID Connect Core 1.0 で定義されているリクエストオブジェクトの後継となるものです。JAR は下記の破壊的変更を導入しました。必要に応じ、現在ご使用中のソフトウェアの設定やソースコードを更新する必要があるので注意してください。
response_type リクエストパラメーターは必須ではなくなる。scope クレームが openid を含んでいても、リクエストオブジェクト外の scope リクエストパラメーターは必須ではなくなる。JAR の技術詳細および Authlete の JAR サポートについては次のブログ記事を参照してください。
稼働中のシステムを破壊することなく JAR への移行をスムーズにおこなうため、Authlete 2.2 には『リクエストオブジェクト処理』という設定項目があります。この項目を「後方互換」としておくと、リクエストオブジェクトは OpenID Connect Core 1.0 の規則に従って処理されます。この設定項目は、authlete-java-common ライブラリ では Service.traditionalRequestObjectProcessingApplied に対応し、 true が「後方互換」、 false が「JAR 互換」を意味します。
全てのクライアントアプリケーションの実装が JAR 対応を済ませたことを確認した後、この設定項目を「JAR 互換」に変更することにより、クライアントアプリケーションの不通状態の発生を回避しながら JAR に移行することができます。
なお、『リクエストオブジェクト処理』を「JAR 互換」にし、『リクエストオブジェクト』を「必須」とすると、当該認可サーバーのディスカバリードキュメント内の require_signed_request_object メタデータの値が true になります。このメタデータの説明ついては JAR 仕様書を参照してください。
注意：認可リクエストの request_uri が、“OAuth 2.0 Pushed Authorization Requests” という仕様で定義されている「Pushed Authorization Request エンドポイント」から発行されたものである場合、『リクエストオブジェクト処理』の設定に関わらず、当該リクエストオブジェクトは JAR 規則に従って処理されます。
Authlete 2.2 は “OAuth 2.0 Pushed Authorization Requests” (略称 PAR) をサポートします。
PAR は、認可エンドポイントに対して実際に認可リクエストをおこなう前に、事前に認可サーバーに認可リクエストを登録するための仕組みです。
PAR の概要については次のブログ記事を参照してください。
サービスとクライアントの双方に『PAR 利用』という設定項目を追加しました。
サービスの設定で「必須」を選ぶと、認可サーバーは PAR 方式でしか認可リクエストデータを受け取らなくなります。結果として、PAR エンドポイントから発行されたリクエスト URI を伴わない認可リクエストは全て拒否されるようになります。
クライアントの設定で「必須」を選ぶと、当該クライアントからの認可リクエストは全て PAR 方式であることが要求されるようになります。
サービスの「PAR 利用」とクライアントの「PAR 利用」はそれぞれ、サーバーメタデータ require_pushed_authorization_requests とクライアントメタデータ require_pushed_authorization_requests に対応します。
Authlete 2.2 は “OAuth 2.0 Rich Authorization Requests” (略称 RAR) をサポートします。
RAR は、認可リクエストに詳細情報を添付するための仕組みです。この仕様により、新しいパラメーター authorization_details が追加されます。パラメーターの値は、詳細情報を表す JSON オブジェクトの配列です。 authorization_details パラメーターは scope パラメーターが使える場所、例えば認可リクエストやトークンレスポンス内で使うことができます。加えて、バックチャネル認証エンドポイント (CIBA) およびデバイス認可エンドポイント (RFC 8628) でも同様に、当該パラメーターをサポートします。
以前は、リクエストパラメーターの scope の値を構造化するなどの手法を用いて認可リクエストの詳細を表現する例などが見受けられました。RAR により、標準仕様を用いて柔軟に認可リクエストの詳細情報を表現することができるようになりました。
authorization_details の各要素の type が取りうる値を列挙する場所として、サービスに『サポートする認可データタイプ』という設定項目を用意しました。この設定項目は、サーバーメタデータ authorization_data_types_supported に対応します。
authorization_details の各要素の type としてクライアントが利用する可能性のある値を列挙する場所として、クライアントに『認可データタイプ群』という設定項目を用意しました。この設定項目は、クライアントメタデータ authorization_data_types に対応します。
Authlete 2.2 は “OAuth 2.0 Demonstration of Proof-of-Posession at the Application Layer” (略称 DPoP) をサポートします。
DPoP は、アクセストークンの所持証明 (Proof-of-Possession) の新しい仕組みです。DPoP は、証明書バインディング (RFC 8705) を使用するのが難しい際の代替となります。
DPoP の技術詳細および Authlete の DPoP サポートについては次のブログ記事を参照してください。
Authlete 2.2 は、2020 年 5 月 19 日にリリースされた ”OpenID Connect for Identity Assurance 1.0" (略称 IDA) の実装者向け草案第 2 版をサポートします。
IDA は、KYC 結果を検証可能な方法で流通させるための仕様です。 技術詳細および Authlete の IDA サポートについては次のブログ記事を参照してください。
Authlete 2.2 は “Resource Indicators for OAuth 2.0” をサポートします。
“Resource Indicators for OAuth 2.0” はアクセストークンのオーディエンス (audience) を指定するための仕組みです。この仕様により、新しいリクエストパラメーター resource が、認可リクエストとトークンリクエストに追加されます。加えて、バックチャネル認証エンドポイント (CIBA) およびデバイス認可エンドポイント (RFC 8628) でも同様に、当該リクエストパラメーターをサポートします。
resource 群は、イントロスペクションレスポンス内の aud の値として設定されます。また、アクセストークンの形式が JWT の場合、その JWT 内の aud の値として設定されます。なお、Authlete では、『アクセストークン署名アルゴリズム』を設定すると、アクセストークンの形式が JWT になります。
アクセストークンのオーディエンス情報を API アクセス制御にどのように活用するかは、リソースサーバーの実装次第です。
Authlete 2.2 は “OAuth 2.0 Authorization Server Issuer Identifier in Authorization Response” をサポートします。
“OAuth 2.0 Authorization Server Issuer Identifier in Authorization Response” は、mix-up 攻撃の一種に対する対抗策として iss という新しい認可レスポンスパラメーターを定義しています。
この仕様は、JARM (JWT Secured Authorization Response Mode) が使われていない限り、認可レスポンスに iss レスポンスパラメーターを含めることを要求します。クライアントアプリケーションは、認可レスポンスに含まれる iss が対象としている認可サーバーの識別子と一致することを確認することで、当該 mix-up 攻撃を受けていないことを保証できます。なお、クライアントアプリケーションがやりとりする認可サーバーが一つしかない場合、当該 mix-up 攻撃を心配する必要はないため、 iss の検証は不要です。詳細については仕様書を参照してください。
Authlete 2.2 には『iss レスポンスパラメーター』という設定項目があります。この設定項目を「含めない」としておくと、認可レスポンスに iss パラメーターが含まれなくなります。この設定項目を切り替えることにより、mix-up 攻撃と iss レスポンスパラメーターの効果を実験することができます。
この設定項目が「含める」となっている場合、当該認可サーバーのディスカバリードキュメント内の authorization_response_iss_parameter_supported メタデータの値が true になります。このメタデータの説明については当該仕様書を参照してください。
この設定項目は、authlete-java-common ライブラリ では Service.issSuppressed に対応し、 true が「含めない」、 false が「含める」を意味します。
注意：特別な理由がない限り、本番環境では「含める」を選択してください。
リクエストが scope パラメーターを含んでおらず (または与えられたスコープがどれも有効ではなく)、サービスにより事前定義されたデフォルトのスコープセットも空の場合、認可サーバーはそのリクエストがスコープを要求していないとみなします。この設定項目で「必須」を設定しておくと、そのようなリクエストが拒否されるようになります。
「制限的」を選択すると、ショートカットスコープ (例： profile) で指定されたクレーム群は、アクセストークンが発行されない場合のみ (response_type が id_token の場合のみ)、ID トークンに含まれます。一方、「非制限的」を選んだ場合は、アクセストークンが発行されるかどうかに関係なく、当該クレーム群は常に ID トークンに含まれます。
「必須」を選択すると、全ての認可リクエストにリクエストオブジェクトの使用を強制します。
「有効」を選択すると、使用されたリフレッシュトークンの残り有効期間が新しく発行されるリフレッシュトークンへと引き継がれます。ただし、『リフレッシュトークンの継続使用』が「有効」になっている場合、この設定値は何の効果もありません。
ID トークンを発行する可能性のある API に idtHeaderParams リクエストパラメーターを追加しました。ID トークンのヘッダー部分に任意のクレームを埋め込むことができます。
/api/auth/introspection/standard API に withHiddenProperties リクエストパラメーターを追加しました。 withHiddenProperties=true が与えられると、 hidden=true となっているプロパティー群もイントロスペクションレスポンスに含まれるようになります。
subject リクエストパラメーターの許容文字数を 100 から 255 に変更しました。