概要

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
    }
  }
}

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 リストとして使われます。

未達認証要求事項

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 値の情報を公開すべきです。この用途のため、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" ]
        }
    }
}&...

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 参照) のメッセージボディーに埋め込まれるアクセストークンの属性として、次の二つを定義しています。

次の 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 仕様をサポートします。

認証情報の紐付け

/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 参照) で返します。

$ curl -u ${API_KEY}:${API_SECRET} ${BASE_URL}/api/auth/authorization --data-urlencode parameters="response_type=code&scope=openid&client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&state=${STATE}&claims={\"id_token\":{\"acr\":{\"essential\":true,\"values\":[\"${ACR}\"]}}}" > authorization_response.json

(2) /auth/authorization/issue API を呼びます。この API は、/auth/authorization API が発行したチケットを受け取り、トークン群 (認可コード、アクセストークン、ID トークン等) を生成し、関連仕様に準拠する認可レスポンスを用意し、JSON (AuthorizationIssueResponse 参照) を返します。

$ TICKET=`jq -r .ticket authorization_response.json`
$ AUTH_TIME=`date +%s`
$ curl -u ${API_KEY}:${API_SECRET} ${BASE_URL}/api/auth/authorization/issue -d ticket=$TICKET -d subject=$SUBJECT -d authTime=$AUTH_TIME -d acr=$ACR > authorization_issue_response.json

(3) /auth/token API を呼びます。この API は、トークンリクエストを parameters として受け取り、トークン群 (アクセストークンや ID トークン) を生成し、関連仕様に準拠するトークンレスポンスを用意し、JSON (TokenResponse 参照) を返します。

$ AUTHORIZATION_CODE=`jq -r .authorizationCode authorization_issue_response.json`
$ curl -u ${API_KEY}:${API_SECRET} ${BASE_URL}/api/auth/token --data-urlencode parameters="client_id=${CLIENT_ID}&grant_type=authorization_code&code=${AUTHORIZATION_CODE}&redirect_uri=${REDIRECT_URI}" -d clientId=${CLIENT_ID} -d clientSecret=${CLIENT_SECRET} > token_response.json

未達認証要求事項

認可エンドポイントの実装は、/auth/authorization/issue API ではなく /auth/authorization/fail API を呼ぶことで、認可リクエストが失敗したことを示すことができます。

/auth/authorization/fail API (AuthorizationFailRequest 参照) は、エラーの理由を示す reason リクエストパラメーターを要求します。reason リクエストパラメーターの値として ACR_NOT_SATISFIED が指定された場合、Authlete 2.3 以降では、OpenID Connect Core Error Code unmet_authentication_requirements に準拠するため、error が unmet_authentication_requirements のエラー応答を用意します。

$ curl -u ${API_KEY}:${API_SECRET} ${BASE_URL}/api/auth/authorization/fail -d ticket=$TICKET -d reason=ACR_NOT_SATISFIED > authorization_fail_response.json

/auth/authorization/fail API のレスポンス (AuthorizationFailResponse 参照) に含まれる responseContent パラメーターは、クライアントアプリケーションのリダイレクションエンドポイントを指す URL で、error や他のパラメーターを伴っています。

$ jq -r .responseContent authorization_fail_response.json
http://localhost:4000/api/mock/redirection/4803170471?error=unmet_authentication_requirements&error_description=%5BA060305%5D+The+authorization+request+requests+%27acr%27+as+essential%2C+but+the+authentication+performed+for+the+end-user+satisfies+none+of+the+requested+ACRs.&error_uri=https%3A%2F%2Fdocs.authlete.com%2F%23A060305&state=917bdc1ef38ba6f6c297b4e31ac84007&iss=https%3A%2F%2Fauthlete.com

Service の errorDescriptionOmitted プロパティー (Service.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.

JWT 型アクセストークン

Authlete が発行するアクセストークンのフォーマットは設定で変更可能です。Service の accessTokenSignAlg プロパティー (Service.getAccessTokenSignAlg() 参照) がセットされている場合、アクセストークンのフォーマットは JWT になります (「JWT ベースのアクセストークン」の有効化)。バージョン 2.3 以降の Authlete は、仕様で定義されているように、acr と auth_time を JWT 型アクセストークンのペイロードに埋め込みます。

サービスが JWT 型アクセストークンを生成するように設定されている場合、/auth/token API レスポンス (TokenResponse 参照) の jwtAccessToken レスポンスパラメーターに JWT 型アクセストークンがセットされています。

$ JWT_AT=`jq -r .jwtAccessToken token_response.json`

JWT 型アクセストークンのペイロード部をデコードすると、

$ echo $JWT_AT | ruby -paF\\. -rbase64 -e '$_=Base64.urlsafe_decode64 $F[1]' | jq .

acr クレームと auth_time クレームが埋め込まれていることが分かります。

{
  "sub": "taka",
  "acr": "acr1",
  "scope": "openid",
  "auth_time": 1667321595,
  "iss": "https://authlete.com",
  "exp": 1667408271,
  "iat": 1667321871,
  "client_id": "5575687621",
  "jti": "A1pURs-TMuyvueCoP2mSsntQX4-0IvYxlvectI4E2h8"
}

トークンレスポンス (標準)

Authlete を用いる認可サーバーは、Authlete の /auth/introspection/standard API を用いて、RFC 7662 に準拠するトークンイントロスペクションエンドポイントを実装することができます。保護リソースエンドポイントの実装は、アクセストークンの詳細情報を取得するために、そのトークンイントロスペクションエンドポイントを使うことができます。

/auth/introspection/standard API はトークンイントロスペクションリクエストを parameters として受け取り、JSON ( StandardIntrospectionResponse 参照) を返します。

$ AT=`jq -r .accessToken token_response.json`
$ curl -u ${API_KEY}:${API_SECRET} ${BASE_URL}/api/auth/introspection/standard --data-urlencode parameters="token=${AT}" > introspection_standard_response.json

その JSON には responseContent パラメーターが含まれています。パラメーターの値は RFC 7662 に準拠する JSON です。

次のコマンドラインは responseContent の値を取り出し、JSON として解釈しています。

$ jq -r .responseContent introspection_standard_response.json | jq .

上記のコマンドラインの結果は次のようになります。acr プロパティーと auth_time プロパティーがあることを確認できます。

{
  "sub": "taka",
  "acr": "acr1",
  "scope": "openid",
  "auth_time": 1667321595,
  "iss": "https://authlete.com",
  "active": true,
  "token_type": "Bearer",
  "exp": 1667408271,
  "client_id": "5575687621"
}

トークンイントロスペクション (Authlete)

Authlete は /auth/introspection API を提供します。この API もアクセストークンのイントロスペクションのためのものですが、標準のイントロスペクションエンドポイントとは異なります。

標準のイントロスペクションエンドポイントと比べた際の /auth/introspection API の主な利点は次の通りです。

1. 標準のイントロスペクションエンドポイントでは実行不可能なバリデーションを実行できる。
2. RFC 6750 に準拠するエラーメッセージを用意できる。

この文書を書いている時点では、/auth/introspection API (IntrospectionRequest 参照) は次のリクエストパラメーター群を受け取ります。

token 以外のリクエストパラメーターはアクセストークンのバリデーションに関連しています。ここで注目すべきは、acrValues リクエストパラメーターと maxAge リクエストパラメーターです。

ACR バリデーション

acrValues リクエストパラメーターが与えられた場合、/auth/introspection API はアクセストークンに紐付く ACR が acrValues 配列内に含まれているかどうかを調べます。もし ACR が含まれていなかった場合、API は OAuth 2.0 Step-up Authentication Challenge Protocol に準拠するエラー応答を用意します。

次のコマンドラインは /auth/introspection API に ACR のバリデーションを実行させます。

$ curl -u ${API_KEY}:${API_SECRET} ${BASE_URL}/api/auth/introspection -d token=$AT -d acrValues="acrX acrY" > introspection_response-acrValues.json

API レスポンス (IntrospectionResponse 参照) 内の responseContent パラメーターは WWW-Authenticate HTTP ヘッダーの値として用いるべき文字列を保持しています。error が insufficient_user_authentication であること、acr_values が含まれていることを確認できます。

$ jq -r .responseContent introspection_response-acrValues.json
Bearer error="insufficient_user_authentication",error_description="[A341302] The authentication context class 'acr1' of the user authentication that the authorization server performed during the course of issuing the access token is insufficient. User authentication of an access token must satisfy one of [acrX acrY] to access the protected resource.",error_uri="https://docs.authlete.com/#A341302",acr_values="acrX acrY"

Max Age バリデーション

maxAge リクエストパラメーターが与えられた場合、/auth/introspection API はアクセストークンに紐付くユーザー認証時刻から指定された時間が経過済みであるかどうかを調べます。もし経過済みであれば、API は OAuth 2.0 Step-up Authentication Challenge Protocol に準拠するエラー応答を用意します。

次のコマンドラインは /auth/introspection API に認証時刻のバリデーションを実行させます。

$ curl -u ${API_KEY}:${API_SECRET} ${BASE_URL}/api/auth/introspection -d token=$AT -d maxAge=600 > introspection_response-maxAge.json

この場合、WWW-Authenticate HTTP ヘッダー用の文字列は max_age を含みます。

$ jq -r .responseContent introspection_response-maxAge.json
Bearer error="insufficient_user_authentication",error_description="[A340301] The time of the user authentication that the authorization server performed during the course of issuing the access token is too old, so re-authentication is needed. The maximum authentication age (max_age) required by the protected resource is 600.",error_uri="https://docs.authlete.com/#A340301",max_age="600"

最後に

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