> ## Documentation Index
> Fetch the complete documentation index at: https://developers.authlete.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authlete 2.2 2021年02月リリースノート

##### バージョン番号：2.2.2

# 本リリースの概要

本リリースは Authlete バージョン 2.2 の最初の一般公開版です。変更点を以下に示します。

# 新たにサポートする標準仕様

## Financial-grade API (FAPI)

Authlete 2.2 は、2021 年 1 月に承認された "Finanicial-grade API" (略称 FAPI) の最終版をサポートします。

最終版と実装者向け草案第 2 版 (2018 年 10 月) との差分のうち、次の要求事項は比較的大きな影響があります。必要に応じ、現在ご使用中のソフトウェアの設定やソースコードを更新する必要があるのでご注意ください。

* FAPI 最終版の第 2 部は、リクエストオブジェクトが `nbf` クレームを含むこと、および、リクエストオブジェクトの生存期間 (`exp - nbf`) が 60 分以内であることを要求します。

* FAPI 最終版の第 2 部は、JWE アルゴリズム `RSA1_5` の使用を禁止します。

### 関連する設定項目

#### nbf クレーム

稼働中のシステムを破壊することなく実装者向け草稿第 2 版から最終版への移行をスムーズにおこなうため、Authlete 2.2 には『nbf クレーム』という設定項目があります。この項目を「任意」としておくと、認可リクエストが FAPI-Part2 リクエストとみなされる場合でも `nbf` クレームは任意扱いとなります。すなわち、認可サーバーはリクエストオブジェクトの生存期間に関する検証をおこないません。

「任意」とすることで部分的に仕様違反状態とはなりますが、リクエストオブジェクトに `nbf` を含めるよう全てのクライアントアプリケーションの実装が更新されたことを確認した後にこの設定項目を「必須」に変更することにより、クライアントアプリケーションの不通状態の発生を回避しながら FAPI 最終版に移行することができます。

この設定項目は、[authlete-java-common ライブラリ](https://github.com/authlete/authlete-java-common/) では `Service.nbfOptional` に対応し、 `true` が「任意」、 `false` が「必須」を意味します。

## JWT Secured Authorization Request (JAR)

Authlete 2.2 は "JWT Secured Authorization Request" (略称 JAR) をサポートします。

JAR は、OpenID Connect Core 1.0 で定義されているリクエストオブジェクトの後継となるものです。JAR は下記の破壊的変更を導入しました。必要に応じ、現在ご使用中のソフトウェアの設定やソースコードを更新する必要があるので注意してください。

* リクエストオブジェクト外のリクエストパラメーター群は使用されない。
* リクエストオブジェクト外の `response_type` リクエストパラメーターは必須ではなくなる。
* リクエストオブジェクト内の `scope` クレームが `openid` を含んでいても、リクエストオブジェクト外の `scope` リクエストパラメーターは必須ではなくなる。
* リクエストオブジェクトの署名が必須となる。

JAR の技術詳細および Authlete の JAR サポートについては次のブログ記事を参照してください。

* [JAR (JWT Secured Authorization Request) に関する実装者の覚書](https://qiita.com/TakahikoKawasaki/items/d52ce91866ae0dcc2ff7)

### 関連する設定項目

#### リクエストオブジェクト処理

稼働中のシステムを破壊することなく JAR への移行をスムーズにおこなうため、Authlete 2.2 には『リクエストオブジェクト処理』という設定項目があります。この項目を「後方互換」としておくと、リクエストオブジェクトは OpenID Connect Core 1.0 の規則に従って処理されます。この設定項目は、[authlete-java-common ライブラリ](https://github.com/authlete/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 規則に従って処理されます。

## OAuth 2.0 Pushed Authorization Requests (PAR)

Authlete 2.2 は "OAuth 2.0 Pushed Authorization Requests" (略称 PAR) をサポートします。

PAR は、認可エンドポイントに対して実際に認可リクエストをおこなう前に、事前に認可サーバーに認可リクエストを登録するための仕組みです。

PAR の概要については次のブログ記事を参照してください。

* [図解 PAR : OAuth 2.0 Pushed Authorization Requests](https://qiita.com/TakahikoKawasaki/items/97563be46b62a0e02fe6)

### 関連する設定項目

#### PAR 利用

サービスとクライアントの双方に『PAR 利用』という設定項目を追加しました。

サービスの設定で「必須」を選ぶと、認可サーバーは PAR 方式でしか認可リクエストデータを受け取らなくなります。結果として、PAR エンドポイントから発行されたリクエスト URI を伴わない認可リクエストは全て拒否されるようになります。

クライアントの設定で「必須」を選ぶと、当該クライアントからの認可リクエストは全て PAR 方式であることが要求されるようになります。

サービスの「PAR 利用」とクライアントの「PAR 利用」はそれぞれ、サーバーメタデータ `require_pushed_authorization_requests` とクライアントメタデータ `require_pushed_authorization_requests` に対応します。

## OAuth 2.0 Rich Authorization Requests (RAR)

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` に対応します。

## OAuth 2.0 Demonstration of Proof-of-Posession at the Application Layer (DPoP)

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 サポートについては次のブログ記事を参照してください。

* [図解 DPoP (OAuth アクセストークンのセキュリティ向上策の一つ)](https://qiita.com/TakahikoKawasaki/items/34c82fb5c0595b6fc289)

## OpenID Connect for Identity Assurance 1.0 (IDA)

Authlete 2.2 は、2020 年 5 月 19 日にリリースされた ”OpenID Connect for Identity Assurance 1.0" (略称 IDA) の実装者向け草案第 2 版をサポートします。

IDA は、KYC 結果を検証可能な方法で流通させるための仕様です。
技術詳細および Authlete の IDA サポートについては次のブログ記事を参照してください。

* [Identity Assurance - eKYC 時代の OpenID Connect](https://qiita.com/TakahikoKawasaki/items/55b54d4b09826a9605e5)

## RFC 8707: Resource Indicators for OAuth 2.0

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 アクセス制御にどのように活用するかは、リソースサーバーの実装次第です。

## OAuth 2.0 Authorization Server Issuer Identifier in Authorization Response

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` の検証は不要です。詳細については仕様書を参照してください。

### 関連する設定項目

#### iss レスポンスパラメーター

Authlete 2.2 には『iss レスポンスパラメーター』という設定項目があります。この設定項目を「含めない」としておくと、認可レスポンスに `iss` パラメーターが含まれなくなります。この設定項目を切り替えることにより、mix-up 攻撃と `iss` レスポンスパラメーターの効果を実験することができます。

この設定項目が「含める」となっている場合、当該認可サーバーのディスカバリードキュメント内の `authorization_response_iss_parameter_supported` メタデータの値が `true` になります。このメタデータの説明については当該仕様書を参照してください。

この設定項目は、[authlete-java-common ライブラリ](https://github.com/authlete/authlete-java-common/) では `Service.issSuppressed` に対応し、 `true` が「含めない」、 `false` が「含める」を意味します。

注意：特別な理由がない限り、本番環境では「含める」を選択してください。

# 新たに追加された設定項目

## スコープ要求

リクエストが `scope` パラメーターを含んでおらず (または与えられたスコープがどれも有効ではなく)、サービスにより事前定義されたデフォルトのスコープセットも空の場合、認可サーバーはそのリクエストがスコープを要求していないとみなします。この設定項目で「必須」を設定しておくと、そのようなリクエストが拒否されるようになります。

## クレームショートカット

「制限的」を選択すると、ショートカットスコープ (例： `profile`) で指定されたクレーム群は、アクセストークンが発行されない場合のみ (`response_type` が `id_token` の場合のみ)、ID トークンに含まれます。一方、「非制限的」を選んだ場合は、アクセストークンが発行されるかどうかに関係なく、当該クレーム群は常に ID トークンに含まれます。

## リクエストオブジェクト

「必須」を選択すると、全ての認可リクエストにリクエストオブジェクトの使用を強制します。

## リフレッシュトークン有効期間引継

「有効」を選択すると、使用されたリフレッシュトークンの残り有効期間が新しく発行されるリフレッシュトークンへと引き継がれます。ただし、『リフレッシュトークンの継続使用』が「有効」になっている場合、この設定値は何の効果もありません。

# 追加・変更された API

## idtHeaderParams (追加)

ID トークンを発行する可能性のある API に `idtHeaderParams` リクエストパラメーターを追加しました。ID トークンのヘッダー部分に任意のクレームを埋め込むことができます。

## withHiddenProperties (追加)

`/api/auth/introspection/standard` API に `withHiddenProperties` リクエストパラメーターを追加しました。 `withHiddenProperties=true` が与えられると、 `hidden=true` となっているプロパティー群もイントロスペクションレスポンスに含まれるようになります。

## subject (変更)

`subject` リクエストパラメーターの許容文字数を 100 から 255 に変更しました。