This page is for Authlete 2.x. For current (3.0) documentation, see this page.
概要
RFC 9470: 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」より抜粋) まず初めに、クライアントアプリケーション (リライングパーティー) がアクセストークンを添えて保護リソースエンドポイントにアクセスします。






ユーザー認証に関する要求事項
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 theacrvalues 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 theacrClaim Value, as specified in Section 2. TheacrClaim is requested as a Voluntary Claim by this parameter.
acr_values リクエストパラメーターの値は、ACR 群をスペース区切りで列挙したものです。認可リクエストでは次のように使われます。
claims リクエストパラメーター
ACR リストを指定する二番目の方法は claims リクエストパラメーターを使うものです。このパラメーターは OpenID Connect Core 1.0 の Section 5.5 で定義されています。このパラメーターは値として JSON オブジェクトを取り、その構文は複雑です。
次の JSON は、OpenID Connect Core 1.0 から抜粋した claims リクエストパラメーターの値の例です。
urn:mace:incommon:iap:silver という要素を一つだけ持つ ACR リストが指定されています。この JSON を値として持つ claims リクエストパラメーターを認可リクエストが含んでいれば、認可サーバーは urn:mace:incommon:iap:silver の基準を満たすユーザー認証を試みます。
指定された ACR 群の一つも満たすことができない場合に認可サーバーにエラーを返させるようにするには、クライアントアプリケーションは acr を必須 (essential) として要求しなければなりません。クレーム名に続く JSON に "essential":true を追加することにより、クライアントはそのクレームを必須として要求することができます。次の例では、auth_time クレームと acr クレームが必須として要求されています。
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 defaultacrvalues 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 theacrClaim Value in the issued ID Token. TheacrClaim is requested as a Voluntary Claim by this parameter. Theacr_values_supporteddiscovery element contains a list of the supportedacrvalues supported by this server. Values specified in theacr_valuesrequest parameter or an individualacrClaim request override these default values.
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 claimacrclaim 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_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. (Themax_agerequest parameter corresponds to the OpenID 2.0 PAPE [OpenID.PAPE]max_auth_agerequest parameter.) Whenmax_ageis used, the ID Token returned MUST include anauth_timeClaim Value.
max_age の値は、秒単位での最大認証時間です。認可リクエスト内では次のように使われます。
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. Themax_agerequest parameter overrides this default value. If omitted, no default Maximum Authentication Age is specified.
prompt リクエストパラメーター
認可フローの過程で (最大認証時間が経過したかどうかに関わらず) 無条件でユーザー認証を実行するように認可サーバーに依頼したい場合、クライアントアプリケーションは、login を含めた prompt リクエストパラメーターを使うことができます。次のように使います。
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 ヘッダーで次のように用いられます。
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 と併せて次のように用いられます (仕様書から抜粋):
values に myACR を含めて acr クレームを必須クレームとして要求する必要があります。例内の改行は見やすくするためだけに使っています。実際のリクエストは改行を含みません。
認可サーバーが 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 と併せて次のように用いられます (仕様書から抜粋):
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. |
acr 属性と auth_time 属性がどのように使われるかを示しています。
Authlete の実装
Authlete はバージョン 2.3 以降で OAuth 2.0 Step Up Authentication Challenge Protocol 仕様をサポートします。認証情報の紐付け
/auth/authorization/issue API (AuthorizationIssueRequest 参照) など、いくつかの Authlete API は acr リクエストパラメーターと authTime リクエストパラメーターを受け取り、生成する ID トークンのペイロード部に埋め込む acr クレームと auth_time クレームの値として用います。Authlete 2.3 以降では、これらのリクエストパラメーターで渡された情報は、アクセストークンにも紐付けられます。
以下のシェルコマンド群は、ACR (acr) と認証時刻 (auth_time) に関する情報を保持するアクセストークンを発行する認可コードフロー (RFC 6749 Section 4.1) を擬似的に実行するものです。
(1) /auth/authorization API を呼びます。この API は、認可リクエストを parameters として受け取り、当リクエストに関する情報を JSON フォーマット (AuthorizationResponse 参照) で返します。
上記のコマンドライン内の
${ACR} の値は、(acr_values_supported サーバーメタデータに相当する)「サポートする認証コンテキスト」の値の一つとしてあらかじめ登録しておく必要があります。登録されていない場合、指定された ACR は無視されます。認可リクエストの ACR 群は、その出所がどこであるかに関わらず (
acr_values、claims、または default_acr_values)、/auth/authorization API のレスポンス内に acrs パラメーターとして列挙されます。加えて、acr クレームが必須として要求されている場合、/auth/authorization API のレスポンス内の真偽値パラメーター acrEssential の値は true になります。/auth/authorization/issue API を呼びます。この API は、/auth/authorization API が発行したチケットを受け取り、トークン群 (認可コード、アクセストークン、ID トークン等) を生成し、関連仕様に準拠する認可レスポンスを用意し、JSON (AuthorizationIssueResponse 参照) を返します。
/auth/token API を呼びます。この API は、トークンリクエストを parameters として受け取り、トークン群 (アクセストークンや ID トークン) を生成し、関連仕様に準拠するトークンレスポンスを用意し、JSON (TokenResponse 参照) を返します。
上記の API コールでは、クライアントのクライアントタイプが confidential で、トークンエンドポイントにおけるクライアント認証方式 (
token_endpoint_auth_method) が client_secret_basic であると想定しています。/auth/token API (TokenRequest 参照) の clientId リクエストパラメーターと clientSecret リクエストパラメーターが使用されているため、クライアント認証方式が client_secret_basic であることが示唆されています。未達認証要求事項
認可エンドポイントの実装は、/auth/authorization/issue API ではなく /auth/authorization/fail API を呼ぶことで、認可リクエストが失敗したことを示すことができます。
/auth/authorization/fail API (AuthorizationFailRequest 参照) は、エラーの理由を示す reason リクエストパラメーターを要求します。reason リクエストパラメーターの値として [ACR_NOT_SATISFIED](https://authlete.github.io/authlete-java-common/com/authlete/common/dto/AuthorizationFailRequest.Reason.html#ACR_NOT_SATISFIED) が指定された場合、Authlete 2.3 以降では、OpenID Connect Core Error Code unmet_authentication_requirements に準拠するため、error が unmet_authentication_requirements のエラー応答を用意します。
/auth/authorization/fail API のレスポンス (AuthorizationFailResponse 参照) に含まれる responseContent パラメーターは、クライアントアプリケーションのリダイレクションエンドポイントを指す URL で、error や他のパラメーターを伴っています。
Service の errorDescriptionOmitted プロパティー (Service.[isErrorDescriptionOmitted()](https://authlete.github.io/authlete-java-common/com/authlete/common/dto/Service.html#isErrorDescriptionOmitted--) 参照) が true でない限り、URL には error_description が含まれます。次のものは、error_description の値を URL デコードした結果得られる文字列です。
[A060305] The authorization request requests ‘acr’ as essential, but the authentication performed for the end-user satisfies none of the requested ACRs.
認可リクエストが
response_mode=form_post または response_mode=form_post.jwt を含む場合、/auth/authorization/fail API レスポンスの responseContent パラメーターの値は URL ではなく HTML になります。JWT 型アクセストークン
Authlete が発行するアクセストークンのフォーマットは設定で変更可能です。Service の accessTokenSignAlg プロパティー (Service.[getAccessTokenSignAlg()](https://authlete.github.io/authlete-java-common/com/authlete/common/dto/Service.html#getAccessTokenSignAlg--) 参照) がセットされている場合、アクセストークンのフォーマットは JWT になります (「JWT ベースのアクセストークン」の有効化)。バージョン 2.3 以降の Authlete は、仕様で定義されているように、acr と auth_time を JWT 型アクセストークンのペイロードに埋め込みます。
サービスが JWT 型アクセストークンを生成するように設定されている場合、/auth/token API レスポンス (TokenResponse 参照) の jwtAccessToken レスポンスパラメーターに JWT 型アクセストークンがセットされています。
acr クレームと auth_time クレームが埋め込まれていることが分かります。
トークンレスポンス (標準)
Authlete を用いる認可サーバーは、Authlete の/auth/introspection/standard API を用いて、RFC 7662 に準拠するトークンイントロスペクションエンドポイントを実装することができます。保護リソースエンドポイントの実装は、アクセストークンの詳細情報を取得するために、そのトークンイントロスペクションエンドポイントを使うことができます。
/auth/introspection/standard API はトークンイントロスペクションリクエストを parameters として受け取り、JSON ( StandardIntrospectionResponse 参照) を返します。
responseContent パラメーターが含まれています。パラメーターの値は RFC 7662 に準拠する JSON です。
次のコマンドラインは responseContent の値を取り出し、JSON として解釈しています。
acr プロパティーと auth_time プロパティーがあることを確認できます。
トークンイントロスペクション (Authlete)
Authlete は/auth/introspection API を提供します。この API もアクセストークンのイントロスペクションのためのものですが、標準のイントロスペクションエンドポイントとは異なります。
標準のイントロスペクションエンドポイントと比べた際の /auth/introspection API の主な利点は次の通りです。
- 標準のイントロスペクションエンドポイントでは実行不可能なバリデーションを実行できる。
- RFC 6750 に準拠するエラーメッセージを用意できる。
/auth/introspection API (IntrospectionRequest 参照) は次のリクエストパラメーター群を受け取ります。
| パラメーター | 分類 | バージョン | 説明 |
|---|---|---|---|
token | 共通 | 1.1 | イントロスペクションの対象とするアクセストークン。 |
scopes | 共通 | 1.1 | アクセストークンに付与されているべきスコープ群。 |
subject | 共通 | 1.1 | アクセストークンに関連付けられているべきサブジェクト (ユーザー識別子)。 |
clientCertificate | RFC 8705 | 2.0 | クライアントアプリケーションと保護リソースエンドポイント間の相互 TLS 接続で使われているクライアント証明書。 |
dpop | DPoP | 2.2 | DPoP HTTP ヘッダーの値。 |
htm | DPoP | 2.2 | 保護リソースエンドポイントに対するリクエストの HTTP メソッド。 |
htu | DPoP | 2.2 | 保護リソースエンドポイントの URL。 |
resources | RFC 8707 | 2.2 | アクセストークンが対象としているべきリソース群。 |
targetUri | HTTP Msg Sig | 2.3 | リクエストの完全 URL。 |
headers | HTTP Msg Sig | 2.3 | リクエストの HTTP ヘッダー群。 |
requestBodyContained | HTTP Msg Sig | 2.3 | リクエストがメッセージボディーを含んでいるかどうか。 |
acrValues | Step Up Auth | 2.3 | アクセストークン発行過程で実行されたユーザー認証が満たすべき認証コンテキストクラス群。 |
maxAge | Step Up Auth | 2.3 | アクセストークン発行過程で実行されたユーザー認証の実行時刻からの経過時間の最大許容値。 |
token 以外のリクエストパラメーターはアクセストークンのバリデーションに関連しています。ここで注目すべきは、acrValues リクエストパラメーターと maxAge リクエストパラメーターです。
ACR バリデーション
acrValues リクエストパラメーターが与えられた場合、/auth/introspection API はアクセストークンに紐付く ACR が acrValues 配列内に含まれているかどうかを調べます。もし ACR が含まれていなかった場合、API は OAuth 2.0 Step Up Authentication Challenge Protocol に準拠するエラー応答を用意します。
次のコマンドラインは /auth/introspection API に ACR のバリデーションを実行させます。
responseContent パラメーターは WWW-Authenticate HTTP ヘッダーの値として用いるべき文字列を保持しています。error が insufficient_user_authentication であること、acr_values が含まれていることを確認できます。
Max Age バリデーション
maxAge リクエストパラメーターが与えられた場合、/auth/introspection API はアクセストークンに紐付くユーザー認証時刻から指定された時間が経過済みであるかどうかを調べます。もし経過済みであれば、API は OAuth 2.0 Step Up Authentication Challenge Protocol に準拠するエラー応答を用意します。
次のコマンドラインは /auth/introspection API に認証時刻のバリデーションを実行させます。
WWW-Authenticate HTTP ヘッダー用の文字列は max_age を含みます。