News

重要: ビジネスプランご契約者さま向けサービスにおける Authlete 2.2 提供の事前ご案内

概要
  1. 2021 年 7 月 29 日、ビジネスプランご契約者さま向けサービスを Authlete 2.2 に更新予定
  2. 更新にあたり、サービスの一時停止を実施
  3. 更新後、一部の API 仕様に変更が発生
  4. 事前検証を希望されるご契約者さまに、テスト環境を提供

平素より弊社サービスをご利用いただき誠にありがとうございます。

この度、ビジネスプランご契約者さま向けサービス (https://api.authlete.com) について、Authlete 新バージョン(2.2)の提供を開始いたします。本記事では主に、新バージョンへの更新に伴うサービスの一時停止と API 仕様の変更についてお知らせいたします。

なお今回の更新は、エンタープライズプランご契約者さまへの影響はございません。

サービス停止期間

今回の更新では、以下の期間に上記サービスを一時的に中断させていただきます。

日本標準時間 2021 年 7 月 29 日(木) 23:00 - 24:00 (UTC 14:00 - 15:00)

重要: API 仕様の変更

本アップデートにより、Authlete API のバージョンを 2.1 から 2.2 に更新いたします。 API について、廃止されるものはありませんが、一部(リクエストオブジェクト関連)に仕様変更が発生します。 変更内容を以下に記述します。

1. FAPI におけるリクエストオブジェクトの nbf クレームの必須化

  • FAPI 最終版にて認可リクエストのリクエストオブジェクト内に nbf クレームが必須となりました。また、リクエストオブジェクトの有効期間(expnbf の差分)が 60 分以内であることが求められます。
  • Authlete 2.2 からは、この仕様に基づいた検証が既定となります。
  • FAPI およびリクエストオブジェクトをご利用中のお客さまは、必要に応じて、Authlete 2.2 で追加される新規パラメーターの「nbf クレーム」の設定値を、後方互換性のある「任意」に設定してください。

2. リクエストオブジェクトのパラメーターチェック内容の変更

  • OpenID Connect Core 1.0 のリクエストオブジェクトと、Authlete 2.2 から新たにサポートする JWT Authorization Request (JAR) のリクエストオブジェクトの仕様には衝突する点があります。
  • Authlete 2.2 では、JAR の仕様に準拠したパラメーターチェック(「JAR 互換」)が既定となります。
  • OpenID Connect Core 1.0 の仕様に準拠したリクエストオブジェクトをご利用中のお客さまは、必要に応じて、Authlete 2.2 で追加される新規パラメーターの「リクエストオブジェクト処理」の設定値を、後方互換性のある「後方互換」に設定してください。

新規に追加される API・機能

Authlete 2.1 から Authlete 2.2 へのバージョンアップにより、新たに以下の機能が利用可能となります。

  • Finanicial-grade API (FAPI) の最終版のサポート(商用利用時は別途追加契約が必要です)
  • JWT Secured Authorization Request (JAR) サポート
  • OAuth 2.0 Pushed Authorization Requests (PAR) サポート
  • OAuth 2.0 Rich Authorization Requests (RAR) サポート
  • OAuth 2.0 Demonstration of Proof-of-Posession at the Application Layer (DPoP) サポート
  • OpenID Connect for Identity Assurance 1.0 (IDA) サポート
  • RFC 8707 Resource Indicators for OAuth 2.0 サポート
  • OAuth 2.0 Authorization Server Issuer Identifier in Authorization Response サポート
  • Parameterized Scope サポート
  • 設定項目の追加
  • API の機能追加・変更

Finanicial-grade API (FAPI)の最終版のサポート

2021 年 1 月に承認された “Finanicial-grade API” (FAPI) の最終版をサポートします。

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

  • FAPI 最終版パート 2 は、リクエストオブジェクトが nbf クレームを含むこと、および、リクエストオブジェクトの有効期間(expnbf の差分)が 60 分以内であることを要求します。
  • FAPI 最終版パート 2 は、JWE アルゴリズム RSA1_5 の使用を禁止します。

参考: 実装者による Financial-grade API (FAPI) 解説


JWT Secured Authorization Request (JAR) サポート

OpenID Connect Core 1.0 で定義されているリクエストオブジェクトの後継となる JAR が利用可能になります。

JAR は下記の破壊的変更を導入しております。必要に応じ、現在ご使用中のソフトウェアの設定やソースコードを更新する必要があるのでご注意ください。 - リクエストオブジェクト外のリクエストパラメーター群は使用されない。 - リクエストオブジェクト外の response_type リクエストパラメーターは必須ではなくなる。 - リクエストオブジェクト内の scope クレームが openid を含んでいても、リクエストオブジェクト外の scope リクエストパラメーターは必須ではなくなる。 - リクエストオブジェクトの署名が必須となる。

参考: JAR (JWT Secured Authorization Request) に関する実装者の覚書


OAuth 2.0 Pushed Authorization Requests (PAR) サポート

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

参考: 図解 PAR : OAuth 2.0 Pushed Authorization Requests


OAuth 2.0 Rich Authorization Requests (RAR) サポート

認可リクエストに詳細情報を添付するための仕組みとなる RAR が利用可能になります。

新しいパラメーター authorization_details が追加されます。パラメーターの値は、詳細情報を表す JSON オブジェクトの配列です。 authorization_details パラメーターは scope パラメーターが使える以下の場所で利用可能です。

  • 認可リクエスト
  • トークンレスポンス
  • バックチャネル認証エンドポイント (CIBA)
  • デバイス認可エンドポイント (RFC 8628)

RAR により、標準仕様を用いて柔軟に認可リクエストの詳細情報を表現することが可能になります。


OAuth 2.0 Demonstration of Proof-of-Posession at the Application Layer (DPoP) サポート

アクセストークンの所持証明 (Proof-of-Possession) をするための仕組みとなる DPoP が利用可能になります。

証明書バインディング (RFC 8705) を使用するのが難しい際の代替手段となります。

参考: 図解 DPoP (OAuth アクセストークンのセキュリティ向上策の一つ)


OpenID Connect for Identity Assurance 1.0 (IDA) サポート

2020 年 5月 19 日にリリースされた、KYC 結果を検証可能な方法で流通させるための仕様となる IDA が利用可能になります。

参考: Identity Assurance - eKYC 時代の OpenID Connect


RFC 8707 Resource Indicators for OAuth 2.0 サポート

アクセストークンのオーディエンス (audience) を指定するための仕組みとなる“Resource Indicators for OAuth 2.0” が利用可能になります。

新しいリクエストパラメーター resource が、以下のエンドポイントに追加されます。 - 認可エンドポイント - トークンエンドポイント - バクチャネル認証エンドポイント(CIBA) - デバイス認可エンドポイント(RFC 8628)

resource 群は、イントロスペクションレスポンス内の aud の値として設定されます。また、アクセストークンの形式が JWT の場合、その JWT 内の aud の値として設定されます。


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 レスポンスパラメーター』という設定項目が追加されます。特別な理由がない限り、本番環境では この設定項目を「含める」に設定してください。


Parameterized Scope サポート

スコープ文字列の一部に動的な値を利用することが可能になります。

スコープ属性のキーに “regex” を設定し、値に任意の正規表現を設定することで、 Authlete は正規表現にマッチするスコープ文字列を受け入れるようになります。

サービスオーナーコンソールの「トークン」タブより設定可能です。

参考: 「パラメーター化されたスコープ」の利用 — Authlete ナレッジベース


設定項目の追加: スコープ要求

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

この設定項目で「必須」を設定しておくと、そのようなリクエストが拒否されるようになります。

サービスオーナーコンソールの「トークン」タブより設定可能です。


設定項目の追加: クレームショートカット

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

サービスオーナーコンソールの「ID トークン」タブより設定可能です。


設定項目の追加: リフレッシュトークン有効期間引継

『リフレッシュトークンの継続使用』を「無効」にし、 『リフレッシュトークン有効期間引継』を「有効」にすると、使用されたリフレッシュトークンの残り有効期間が新しく発行されるリフレッシュトークンへと引き継がれます。

『リフレッシュトークンの継続使用』が「有効」になっている場合、この設定値は使用されません。

サービスオーナーコンソールの「トークン」タブより設定可能です。


API の機能追加・変更: ID トークンのヘッダーへの独自クレーム追加機能

以下の API に idtHeaderParams リクエストパラメーターを追加します(任意)。

  • /auth/authorization/issue
  • /backchannel/authentication/complete
  • /device/complete

このリクエストパラメーターを用いて、ID トークンのヘッダー部分に任意のクレームを埋め込むことが可能になります。

参考: ID トークンのヘッダーへの独自クレーム追加 — Authlete ナレッジベース


API の機能追加・変更: introspection API (Standard) のレスポンスに非表示設定のプロパティの追加機能

Introspection API (Standard) に withHiddenProperties リクエストパラメーターを追加します(任意)。

  • RFC 7662 準拠の /auth/introspection/standard が対象となります。Authlete 独自の /auth/introspection は変更ありません。

withHiddenProperties=true が与えられると、 hidden=true となっているプロパティー群もイントロスペクションレスポンスに含まれるようになります。


API の機能追加・変更: subject リクエストパラメーターの許容文字数拡張

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


API の機能追加・変更: サービス属性の追加

任意のキー・バリューの組を、任意の目的のためにサービスにひもづけることが可能になります。 ひもづけられた属性群は、いくつかの Authlete API (例: /auth/introspection API) のレスポンスに埋め込まれます。多くのケースでは serviceAttributes の値として埋め込まれますが、レスポンスが service を含む場合は、その service JSON オブジェクト内に attributes の値として埋め込まれます。 サービスオーナーコンソールの「基本情報」タブより設定可能です。


API の機能追加・変更: クライアント属性の追加

任意のキー・バリューの組を、任意の目的のためにクライアントにひもづけることが可能になります。

ひもづけられた属性群は、いくつかの Authlete API (例: /auth/introspection API) のレスポンスに埋め込まれます。多くのケースでは clientAttributes の値として埋め込まれますが、レスポンスが client を含む場合は、その client JSON オブジェクト内に attributes の値として埋め込まれます。

クライアントコンソールの「基本情報」タブより設定可能です。


API の機能追加・変更: リフレッシュトークンおよびそのハッシュによるトークン削除機能

トークン削除 API (/auth/token/delete) のリクエストパラメーターに、リフレッシュトークンおよびそのハッシュも指定できるようなります。

本機能追加により、トークン削除 API は以下の 4 種類の値を削除対象として指定可能になります。 - アクセストークン - アクセストークンのハッシュ - リフレッシュトークン(新規) - リフレッシュトークンのハッシュ(新規)

リフレッシュトークンを削除した場合には、関連するアクセストークンも同時に削除されます。逆も同様です(アクセストークン削除によってリフレッシュトークンも削除されます)。


テスト環境の提供

事前に Authlete 2.2 の API を確認するための、テスト用の環境(商用利用はお控えください)を一時的に提供いたします。利用を希望されるご契約者さまは、2021 年 7 月 9 日までにログイン ID またはメールアドレスをお知らせください

テスト環境提供期間(予定): 2021 年 7 月 12 日 〜 2021 年 7 月 29 日 23:00

本件に関する連絡先

お問い合わせフォーム、または営業担当者までお願いいたします。

参考情報