平素より弊社サービスをご利用いただき誠にありがとうございます。
この度、ビジネスプランご契約者さま向けサービス (https://api.authlete.com) について、Authlete 新バージョン（2.2）の提供を開始いたします。本記事では主に、新バージョンへの更新に伴うサービスの一時停止と API 仕様の変更についてお知らせいたします。
なお今回の更新は、エンタープライズプランご契約者さまへの影響はございません。
今回の更新では、以下の期間に上記サービスを一時的に中断させていただきます。
日本標準時間 2021 年 7 月 29 日（木） 23:00 - 24:00 (UTC 14:00 - 15:00)
本アップデートにより、Authlete API のバージョンを 2.1 から 2.2 に更新いたします。 API について、廃止されるものはありませんが、一部（リクエストオブジェクト関連）に仕様変更が発生します。 変更内容を以下に記述します。
nbf クレームが必須となりました。また、リクエストオブジェクトの有効期間（exp と nbf の差分）が 60 分以内であることが求められます。Authlete 2.1 から Authlete 2.2 へのバージョンアップにより、新たに以下の機能が利用可能となります。
2021 年 1 月に承認された “Finanicial-grade API” (FAPI) の最終版をサポートします。
最終版と、実装者向け草案第 2 版 (2018 年 10 月) との差分のうち、以下の要求事項は比較的大きな影響があります。必要に応じ、現在ご使用中のソフトウェアの設定やソースコードを更新する必要があるのでご注意ください。
nbf クレームを含むこと、および、リクエストオブジェクトの有効期間（exp と nbf の差分）が 60 分以内であることを要求します。参考: 実装者による Financial-grade API (FAPI) 解説
OpenID Connect Core 1.0 で定義されているリクエストオブジェクトの後継となる JAR が利用可能になります。
JAR は下記の破壊的変更を導入しております。必要に応じ、現在ご使用中のソフトウェアの設定やソースコードを更新する必要があるのでご注意ください。
response_type リクエストパラメーターは必須ではなくなる。scope クレームが openid を含んでいても、リクエストオブジェクト外の scope リクエストパラメーターは必須ではなくなる。参考: JAR (JWT Secured Authorization Request) に関する実装者の覚書
認可エンドポイントに対して実際に認可リクエストをおこなう前に、事前に認可サーバーに認可リクエストを登録するための仕組みとなる PAR が利用可能になります。
参考: 図解 PAR : OAuth 2.0 Pushed Authorization Requests
認可リクエストに詳細情報を添付するための仕組みとなる RAR が利用可能になります。
新しいパラメーター authorization_details が追加されます。パラメーターの値は、詳細情報を表す JSON オブジェクトの配列です。 authorization_details パラメーターは scope パラメーターが使える以下の場所で利用可能です。
RAR により、標準仕様を用いて柔軟に認可リクエストの詳細情報を表現することが可能になります。
アクセストークンの所持証明 (Proof-of-Possession) をするための仕組みとなる DPoP が利用可能になります。
証明書バインディング (RFC 8705) を使用するのが難しい際の代替手段となります。
参考: 図解 DPoP (OAuth アクセストークンのセキュリティ向上策の一つ)
2020 年 5月 19 日にリリースされた、KYC 結果を検証可能な方法で流通させるための仕様となる IDA が利用可能になります。
参考: Identity Assurance - eKYC 時代の OpenID Connect
アクセストークンのオーディエンス (audience) を指定するための仕組みとなる“Resource Indicators for OAuth 2.0” が利用可能になります。
新しいリクエストパラメーター resource が、以下のエンドポイントに追加されます。
resource 群は、イントロスペクションレスポンス内の aud の値として設定されます。また、アクセストークンの形式が JWT の場合、その JWT 内の aud の値として設定されます。
mix-up 攻撃の一種に対する対抗策として iss という新しい認可レスポンスパラメーターを追加します。
JARM (JWT Secured Authorization Response Mode) が使われていない限り、認可レスポンスに iss レスポンスパラメーターを含めることを要求することが可能になります。
クライアントアプリケーションは、認可レスポンスに含まれる iss が対象としている認可サーバーの識別子と一致することを確認することで、当該 mix-up 攻撃を受けていないことを保証できます。なお、クライアントアプリケーションがやりとりする認可サーバーが一つしかない場合、当該 mix-up 攻撃を心配する必要はないため、 iss の検証は不要です。
サービスオーナーコンソールに『iss レスポンスパラメーター』という設定項目が追加されます。特別な理由がない限り、本番環境では この設定項目を「含める」に設定してください。
スコープ文字列の一部に動的な値を利用することが可能になります。
スコープ属性のキーに “regex” を設定し、値に任意の正規表現を設定することで、 Authlete は正規表現にマッチするスコープ文字列を受け入れるようになります。
サービスオーナーコンソールの「トークン」タブより設定可能です。
参考: 「パラメーター化されたスコープ」の利用 — Authlete ナレッジベース
リクエストが scope パラメーターを含んでおらず (または与えられたスコープがどれも有効ではなく)、サービスにより事前定義されたデフォルトのスコープセットも空の場合、認可サーバーはそのリクエストがスコープを要求していないとみなします。
この設定項目で「必須」を設定しておくと、そのようなリクエストが拒否されるようになります。
サービスオーナーコンソールの「トークン」タブより設定可能です。
この設定項目で「制限的」を選択すると、ショートカットスコープ (例： profile) で指定されたクレーム群は、アクセストークンが発行されない場合のみ (response_type が id_token の場合のみ)、ID トークンに含まれます。一方、「非制限的」を選んだ場合は、アクセストークンが発行されるかどうかに関係なく、当該クレーム群は常に ID トークンに含まれます。
サービスオーナーコンソールの「ID トークン」タブより設定可能です。
『リフレッシュトークンの継続使用』を「無効」にし、 『リフレッシュトークン有効期間引継』を「有効」にすると、使用されたリフレッシュトークンの残り有効期間が新しく発行されるリフレッシュトークンへと引き継がれます。
『リフレッシュトークンの継続使用』が「有効」になっている場合、この設定値は使用されません。
サービスオーナーコンソールの「トークン」タブより設定可能です。
以下の API に idtHeaderParams リクエストパラメーターを追加します（任意）。
このリクエストパラメーターを用いて、ID トークンのヘッダー部分に任意のクレームを埋め込むことが可能になります。
参考: ID トークンのヘッダーへの独自クレーム追加 — Authlete ナレッジベース
Introspection API (Standard) に withHiddenProperties リクエストパラメーターを追加します（任意）。
withHiddenProperties=true が与えられると、 hidden=true となっているプロパティー群もイントロスペクションレスポンスに含まれるようになります。
subject リクエストパラメーターの許容文字数を 100 から 255 に変更いたします。
任意のキー・バリューの組を、任意の目的のためにサービスにひもづけることが可能になります。
ひもづけられた属性群は、いくつかの Authlete API (例: /auth/introspection API) のレスポンスに埋め込まれます。多くのケースでは serviceAttributes の値として埋め込まれますが、レスポンスが service を含む場合は、その service JSON オブジェクト内に attributes の値として埋め込まれます。
サービスオーナーコンソールの「基本情報」タブより設定可能です。
任意のキー・バリューの組を、任意の目的のためにクライアントにひもづけることが可能になります。
ひもづけられた属性群は、いくつかの Authlete API (例: /auth/introspection API) のレスポンスに埋め込まれます。多くのケースでは clientAttributes の値として埋め込まれますが、レスポンスが client を含む場合は、その client JSON オブジェクト内に attributes の値として埋め込まれます。
クライアントコンソールの「基本情報」タブより設定可能です。
トークン削除 API (/auth/token/delete) のリクエストパラメーターに、リフレッシュトークンおよびそのハッシュも指定できるようなります。
本機能追加により、トークン削除 API は以下の 4 種類の値を削除対象として指定可能になります。
リフレッシュトークンを削除した場合には、関連するアクセストークンも同時に削除されます。逆も同様です（アクセストークン削除によってリフレッシュトークンも削除されます）。
事前に Authlete 2.2 の API を確認するための、テスト用の環境（商用利用はお控えください）を一時的に提供いたします。利用を希望されるご契約者さまは、2021 年 7 月 9 日までにログイン ID またはメールアドレスをお知らせください。
テスト環境提供期間（予定）: 2021 年 7 月 12 日 〜 2021 年 7 月 29 日 23:00
お問い合わせフォーム、または営業担当者までお願いいたします。