本記事は Authlete 社ウェブサイト上の記事『OAuth 2.0 Step-up Authentication Challenge Protocol』の一部転載です。

概要

OAuth 2.0 Step-up Authentication Challenge Protocol は「リクエストのアクセストークンに紐付く認証イベントが認証要求事項を満たさないこと及びその満たし方をリソースサーバーがクライアントに伝える仕組みを導入します。」 ("introduces a mechanism for a resource server to signal to a client that the authentication event associated with the access token of the current request doesn't meet its authentication requirements and specify how to meet them." 「Abstract」より抜粋)

まず初めに、クライアントアプリケーション (リライングパーティー) がアクセストークンを添えて保護リソースエンドポイントにアクセスします。

エンドポイントの実装はリクエストからアクセストークンを取り出します。

次に、エンドポイントの実装はアクセストークンから (当該アクセストークンを発行する過程で認可サーバーが実行した) ユーザー認証に関する情報を取り出します。

そして、エンドポイントの実装は、当情報が自身の課すユーザー認証に関する要求事項を満たすかどうかを調べます。

もし要求事項が満たされていなければ、エンドポイントの実装は、ユーザー認証に関する要求事項を添えたエラー応答をクライアントアプリケーションに返します。

次の図は、アクセストークンを伴うリクエストを投げてからユーザー認証に関する要求事項を伴うエラー応答を返却するまでの流れを示しています。

ユーザー認証に関する要求事項を伴うエラー応答を受け取った後、クライアントは再び認可リクエストを投げます。ここでクライアントは、ユーザー認証に関する要求事項を満たすアクセストークンの発行を認可サーバーに依頼する必要があります。

ユーザー認証に関する要求事項

The OAuth 2.0 Step-up Authentication Challenge Protocol 仕様は、ユーザー認証に関する要求事項について、二つのものを想定しています。

一つは、ユーザー認証の認証コンテキストクラスリファレンス (Authentication Context Class Reference) で、ACR と呼ばれるものです。もう一方は、最大認証時間 (Maximum Authentication Age) で、Max Age と呼ばれるものです。

認証コンテキストクラスリファレンス (ACR)

認可フローのどこかの時点でユーザー認証が行われます。OAuth 2.0 と OpenID Connect はユーザー認証方法の詳細を定義していませんが、クライアントアプリケーションは ACR のリストを認可リクエストに含めることにより、ユーザー認証の基準を指定することができます。

認可サーバーは、指定された ACR 群のうち少なくとも一つを満たすユーザー認証を試みます。しかし、acr クレームが必須 (essential) として要求されていない限り (後述)、条件を満たすユーザー認証を実行できなくても認可サーバーはエラーを返しません。

`acr_values` リクエストパラメーター

ACR のリストを指定する方法は三つあります。一番目は acr_values リクエストパラメーターを使う方法です。このパラメーターは、OpenID Connect Core 1.0 の Section 3.1.2.1 で次のように定義されています。

acr_values: OPTIONAL. Requested Authentication Context Class Reference values. Space-separated string that specifies the acr values that the Authorization Server is being requested to use for processing this Authentication Request, with the values appearing in order of preference. The Authentication Context Class satisfied by the authentication performed is returned as the acr Claim Value, as specified in Section 2. The acr Claim is requested as a Voluntary Claim by this parameter.

acr_values リクエストパラメーターの値は、ACR 群をスペース区切りで列挙したものです。認可リクエストでは次のように使われます。

https://as.example.com/authorize?acr_values=acr1+acr2+acr3&...

`claims` リクエストパラメーター

ACR リストを指定する二番目の方法は claims リクエストパラメーターを使うものです。このパラメーターは OpenID Connect Core 1.0 の Section 5.5 で定義されています。このパラメーターは値として JSON オブジェクトを取り、その構文は複雑です。

次の JSON は、OpenID Connect Core 1.0 から抜粋した claims リクエストパラメーターの値の例です。

{
 "userinfo":
  {
   "given_name": {"essential": true},
   "nickname": null,
   "email": {"essential": true},
   "email_verified": {"essential": true},
   "picture": null,
   "http://example.info/claims/groups": null
  },
 "id_token":
  {
   "auth_time": {"essential": true},
   "acr": {"values": ["urn:mace:incommon:iap:silver"] }
  }
}

この例では、urn:mace:incommon:iap:silver という要素を一つだけ持つ ACR リストが指定されています。この JSON を値として持つ claims リクエストパラメーターを認可リクエストが含んでいれば、認可サーバーは urn:mace:incommon:iap:silver の基準を満たすユーザー認証を試みます。

指定された ACR 群の一つも満たすことができない場合に認可サーバーにエラーを返させるようにするには、クライアントアプリケーションは acr を必須 (essential) として要求しなければなりません。クレーム名に続く JSON に "essential":true を追加することにより、クライアントはそのクレームを必須として要求することができます。次の例では、auth_time クレームと acr クレームが必須として要求されています。

{
  "id_token":
  {
    "auth_time": {
      "essential": true
    },
    "acr": {
      "values": ["urn:mace:incommon:iap:silver"],
      "essential": true
    }
  }
}

acr_values リクエストパラメーターでは acr クレームを必須として要求できません。

`default_acr_values` クライアントメタデータ

最後は default_acr_values クライアントメタデータを使う方法です。このメタデータは OpenID Connect Dynamic Client Registration 1.0 の Section 2 で次のように定義されています。

default_acr_values: OPTIONAL. Default requested Authentication Context Class Reference values. Array of strings that specifies the default acr values that the OP is being requested to use for processing requests from this Client, with the values appearing in order of preference. The Authentication Context Class satisfied by the authentication performed is returned as the acr Claim Value in the issued ID Token. The acr Claim is requested as a Voluntary Claim by this parameter. The acr_values_supported discovery element contains a list of the supported acr values supported by this server. Values specified in the acr_values request parameter or an individual acr Claim request override these default values.

認可リクエストが ACR リストを明示的に指定していない場合、default_acr_values の値が、もしセットされていれば、ACR リストとして使われます。

default_acr_values クライアントメタデータでは acr クレームを必須として要求できません。

未達認証要求事項

acr クレームが必須クレームとして要求されている場合、指定された ACR のいずれも満たせなければ認可サーバーはエラー応答を返します。認可サーバーが OpenID Connect Core Error Code unmet_authentication_requirements をサポートしていれば、error レスポンスパラメーターの値として unmet_authentication_requirements が使用されます。

次のものは、仕様から抜粋した当エラーコードに関する説明です。

unmet_authentication_requirements: The Authorization Server is unable to meet the requirements of the Relying Party for the authentication of the End-User. This error code SHALL be used if the Relying Party wants the OP to conform to a certain Authentication Context Class Reference value using an essential claim acr claim as specified in Section 5.5.1.1. of OpenID Connect Core [OpenID.Core] and the OP is unable to meet this requirement and MAY be used in other cases, if appropriate.

認可サーバーがこの仕様をサポートしていなければ、どのエラーコードが使われるかは認可サーバー次第です。

ステップアップ認証用の未達認証要求事項

OpenID Connect Core 1.0 の文脈では、acr クレームが必須クレームとして要求されていない限り、条件を満たすユーザー認証を実行できなくても認可サーバーはエラーを返しません。

しかし、OAuth 2.0 Step-up Authentication Challenge Protocol は、(acr クレームを任意クレームとして要求する) acr_values リクエストパラメーターによる ACR リクエストを必須として扱い ("treated as required")、指定された ACR のいずれも満たせない場合に認可サーバーが unmet_authentication_requirements エラーを返すことを勧めています。

この推奨は、OpenID Connect Core 1.0 から抜粋した下記の文とやや衝突します。

Note that even if the Claims are not available because the End-User did not authorize their release or they are not present, the Authorization Server MUST NOT generate an error when Claims are not returned, whether they are Essential or Voluntary, unless otherwise specified in the description of the specific claim.

しかし、現実的には、このわずかな衝突が大きな問題となることはないでしょう。

実際の ACR 値

OpenID Connect Core 1.0 は実際の ACR 値を定義していません。そのため、ACR を活用するには、運用毎にそれぞれ実際の ACR 値を定義する必要があります。次の表は実際の ACR 値の例を示しています。

運用	ACR 値
英国オープンバンキング	`urn:openbanking:psd2:ca` `urn:openbanking:psd2:sca`
オーストラリア消費者データ権	`urn:cds:au:cdr:2` `urn:cds:au:cdr:3`
ブラジルオープンバンキング	`urn:brasil:openbanking:loa2` `urn:brasil:openbanking:loa3`

認可サーバーはディスカバリー文書を通じてサポートする ACR 値の情報を公開すべきです。この用途のため、OpenID Connect Discovery 1.0 は acr_values_supported サーバーメタデータを次のように定義しています。

acr_values_supported: OPTIONAL. JSON array containing a list of the Authentication Context Class References that this OP supports.

最大認証時間 (Max Age)

先の節の冒頭で 「認可フローのどこかの時点でユーザー認証が行われます」 と述べました。しかし実際には、ユーザーが既に認証済み (= ユーザーが既にログイン済み) であることを検出した場合、認可サーバーはユーザー認証処理を省略するかもしれません。そのため、認可リクエストが行われた時刻と、その認可リクエスト用のユーザー認証が行われた時刻は、必ずしも一致しません。

最後のユーザー認証から経過した時間は認証時間 (authentication age) と呼ばれます。クライアントアプリケーションは、認証時間が特定の閾値を超えた際に認可フローの過程でユーザー認証を行うよう、認可サーバーに依頼することができます。この閾値は最大認証時間 (maximum authentication age) と呼ばれます。

`max_age` リクエストパラメーター

OpenID Connect Core 1.0 の Section 3.1.2.1 は、クライアントアプリケーションが最大認証時間を指定することを可能とするため、次のように max_age リクエストパラメーターを定義しています。

max_age: OPTIONAL. Maximum Authentication Age. Specifies the allowable elapsed time in seconds since the last time the End-User was actively authenticated by the OP. If the elapsed time is greater than this value, the OP MUST attempt to actively re-authenticate the End-User. (The max_age request parameter corresponds to the OpenID 2.0 PAPE [OpenID.PAPE] max_auth_age request parameter.) When max_age is used, the ID Token returned MUST include an auth_time Claim Value.

max_age の値は、秒単位での最大認証時間です。認可リクエスト内では次のように使われます。

https://as.example.com/authorize?max_age=600&...

`default_max_age` クライアントメタデータ

認可リクエストが max_age リクエストパラメーターを含んでいなくても、クライアントの default_max_age クライアントメタデータが設定されていれば、そのメタデータの値が最大認証時間として使用されます。OpenID Connect Dynamic Client Registration 1.0 の Section 2 は当メタデータを次のように定義しています。

default_max_age: OPTIONAL. Default Maximum Authentication Age. Specifies that the End-User MUST be actively authenticated if the End-User was authenticated longer ago than the specified number of seconds. The max_age request parameter overrides this default value. If omitted, no default Maximum Authentication Age is specified.

`prompt` リクエストパラメーター

認可フローの過程で (最大認証時間が経過したかどうかに関わらず) 無条件でユーザー認証を実行するように認可サーバーに依頼したい場合、クライアントアプリケーションは、login を含めた prompt リクエストパラメーターを使うことができます。次のように使います。

https://as.example.com/authorize?prompt=login&...

prompt パラメーターの詳細については OpenID Connect Core 1.0 の Section 3.1.2.1 を参照してください。

認証要求事項チャレンジ

OAuth 2.0 Step-up Authentication Challenge Protocol 仕様を利用する保護リソースエンドポイントは、提示されたアクセストークンが認証要求事項 (つまり ACR と Max Age) のどちらかもしくは両方を満たさない場合、エラー応答を返します。

次の図は、エラー応答を返すところから、認証要求事項を満たすアクセストークンを要求する認可リクエストを投げるまでの流れを示しています。

エラー応答内のパラメーター群については以降の節で説明します。

`insufficient_user_authentication` エラーコード

認証要求事項が満たされないことがエラー応答の理由であることを示すため、仕様はエラコード insufficient_user_authentication を次のように定義しています。

insufficient_user_authentication: The authentication event associated with the access token presented with the request doesn't meet the authentication requirements of the protected resource.

このエラーコードは、エラー応答内の WWW-Authenticate HTTP ヘッダーで次のように用いられます。

WWW-Authenticate: Bearer error="insufficient_user_authentication",...

`acr_values` パラメーター

アクセストークンが満たさなければならない ACR を推奨順で並べるため、仕様はパラメーター acr_values を次のように定義しています。

acr_values: A space-separated string listing the authentication context class reference values, in order of preference, one of which the protected resource requires for the authentication event associated with the access token.

このパラメーターはエラーコード insufficent_user_authentication と併せて次のように用いられます (仕様書から抜粋):

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="insufficient_user_authentication",
  error_description="A different authentication level is required",
  acr_values="myACR"

クライアントアプリケーションが上記のエラー応答を受け取った場合、次の例が示すように、values に myACR を含めて acr クレームを必須クレームとして要求する必要があります。例内の改行は見やすくするためだけに使っています。実際のリクエストは改行を含みません。

https://as.example.com/authorize?claims={
    "id_token": {
        "acr": {
            "essential": true,
            "values": [ "myACR" ]
        }
    }
}&...

認可サーバーが OAuth 2.0 Step-up Authentication Challenge Protocol 仕様が推奨する方法で acr_values リクエストパラメーターを処理する場合、acr_values=myACR で十分です。

`max_age` パラメーター

アクセストークンが満たさなければならない最大認証時間を示すため、仕様はパラメーター max_age を次のように定義しています。

max_age: Indicates the allowable elapsed time in seconds since the last active authentication event associated with the access token.

このパラメーターはエラーコード insufficent_user_authentication と併せて次のように用いられます (仕様書から抜粋):

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="insufficient_user_authentication",
  error_description="More recent authentication is required",
  max_age="5"

クライアントアプリケーションが上記のエラー応答を受け取った場合、次の例が示すように、login を含む prompt リクエストパラメーターを添えて認可リクエストを行う必要があります。

アクセストークンに紐付く認証情報

提示されたアクセストークンが認証要求事項を満たすかどうかを保護リソースエンドポイントがチェックすることを可能とするためには、アクセストークンの発行過程で実行されたユーザー認証に関する情報をアクセストークンが保持していなければなりません。

OAuth 2.0 Step-up Authentication Challenge Protocol 仕様は、JWT 型アクセストークンのペイロード部やイントロスペクションレスポンス (RFC 7662 参照) のメッセージボディーに埋め込まれるアクセストークンの属性として、次の二つを定義しています。

属性	説明 (仕様から抜粋)
`acr`	Authentication Context Class Reference. String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the user authentication performed satisfied.
`auth_time`	Time when the user authentication occurred. A JSON numeric value representing the number of seconds from 1970-01-01T00:00:00Z UTC until the time of date/time of the authentication event.

次の JSON は仕様からの抜粋で、JWT 型アクセストークンのペイロード部で acr 属性と auth_time 属性がどのように使われるかを示しています。

{
    "active": true,
    "client_id": "s6BhdRkqt3",
    "scope": "purchase",
    "sub": "someone@example.net",
    "aud": "https://rs.example.com",
    "iss": "https://as.example.net",
    "exp": 1639528912,
    "iat": 1618354090,
    "auth_time": 1646340198,
    "acr": "myACR"
}

Authlete の実装

Authlete はバージョン 2.3 以降で OAuth 2.0 Step-up Authentication Challenge Protocol 仕様をサポートします。

詳細については Authlete 社ウェブサイト上の『Authlete の実装』をご参照ください。

最後に

この文書を書いている時点 (2022 年 11 月) では、Authlete 2.3 は開発段階であり、安定バージョンは公にリリースされていません。最新の Authlete バージョンへの早期アクセスにご興味のある方はお問い合わせください。