OAuth 2.0 Step-up Authentication Challenge Protocol

:::note info
本記事は [Authlete 社ウェブサイト](https://www.authlete.com/ja/)上の記事『[OAuth 2.0 Step-up Authentication Challenge Protocol](https://www.authlete.com/ja/developers/stepup_authn/)』の一部転載です。
:::

# 概要

**[OAuth 2.0 Step-up Authentication Challenge Protocol](https://datatracker.ietf.org/doc/draft-ietf-oauth-step-up-authn-challenge/)** は *「リクエストのアクセストークンに紐付く認証イベントが認証要求事項を満たさないこと及びその満たし方をリソースサーバーがクライアントに伝える仕組みを導入します。」* (*"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」より抜粋)

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

![stepup_authn_1.ja.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/106044/4a4dd452-b94a-1a5a-db5a-9dc79457b5bb.png)

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

![stepup_authn_2.ja.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/106044/ee4081b1-a495-e3ca-5d52-42b9488e9914.png)

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

![stepup_authn_3.ja.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/106044/e1dc2b06-0e0e-4761-84cb-23b07e1b32b1.png)

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

![stepup_authn_4.ja.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/106044/e1b47398-8a45-c9fa-03e3-47ad34e5618d.png)

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

![stepup_authn_5.ja.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/106044/b6c4468a-be65-30cb-2cb3-5c7dae77b849.png)

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

![stepup_authn.ja.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/106044/7b19dcdd-37e7-0539-31bd-229cb7abafa1.png)

ユーザー認証に関する要求事項を伴うエラー応答を受け取った後、クライアントは再び**認可リクエスト**を投げます。ここでクライアントは、ユーザー認証に関する要求事項を満たすアクセストークンの発行を認可サーバーに依頼する必要があります。
![stepup_authn_6.ja.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/106044/5cd30367-2b55-d91a-3252-571a246529f6.png)
# ユーザー認証に関する要求事項

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](https://openid.net/specs/openid-connect-core-1_0.html) の [Section 3.1.2.1](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) で次のように定義されています。

- `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](https://openid.net/specs/openid-connect-core-1_0.html) の [Section 5.5](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter) で定義されています。このパラメーターは値として JSON オブジェクトを取り、その構文は複雑です。

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

```json
{
 "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` クレームが必須として要求されています。

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

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

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

最後は `default_acr_values` クライアントメタデータを使う方法です。このメタデータは [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) の [Section 2](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata) で次のように定義されています。

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

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

### 未達認証要求事項

`acr` クレームが必須クレームとして要求されている場合、指定された ACR のいずれも満たせなければ認可サーバーはエラー応答を返します。認可サーバーが [OpenID Connect Core Error Code unmet_authentication_requirements](https://openid.net/specs/openid-connect-unmet-authentication-requirements-1_0.html) をサポートしていれば、`error` レスポンスパラメーターの値として `unmet_authentication_requirements` が使用されます。

![unmet_authentication_requirements.ja.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/106044/88bab959-7a31-3192-18ee-9a1f090de50b.png)

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

- `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](https://openid.net/specs/openid-connect-core-1_0.html) の文脈では、`acr` クレームが必須クレームとして要求されていない限り、条件を満たすユーザー認証を実行できなくても認可サーバーはエラーを返しません。

しかし、[OAuth 2.0 Step-up Authentication Challenge Protocol](https://datatracker.ietf.org/doc/draft-ietf-oauth-step-up-authn-challenge/) は、(`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` <br> `urn:openbanking:psd2:sca` |
| オーストラリア消費者データ権 | `urn:cds:au:cdr:2` <br> `urn:cds:au:cdr:3` |
| ブラジルオープンバンキング | `urn:brasil:openbanking:loa2` <br> `urn:brasil:openbanking:loa3` |

認可サーバーはディスカバリー文書を通じてサポートする ACR 値の情報を公開すべきです。この用途のため、[OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) は `acr_values_supported` サーバーメタデータを次のように定義しています。

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

![acr_values_supported.ja.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/106044/25f055ec-b89d-4943-c19a-e4c005ce3f71.png)

## 最大認証時間 (Max Age)

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

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

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

[OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) の [Section 3.1.2.1](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) は、クライアントアプリケーションが最大認証時間を指定することを可能とするため、次のように `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](https://openid.net/specs/openid-connect-registration-1_0.html) の [Section 2](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata) は当メタデータを次のように定義しています。

- `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](https://openid.net/specs/openid-connect-core-1_0.html) の [Section 3.1.2.1](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) を参照してください。

# 認証要求事項チャレンジ

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

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

![insufficient_user_authentication.ja.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/106044/e66e92c6-5281-7315-af0f-c7e16b2a2dc9.png)

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

## `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 ヘッダーで次のように用いられます。

```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
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" ]
        }
    }
}&...
```

:::note info
認可サーバーが 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
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](https://www.rfc-editor.org/rfc/rfc7662.html) 参照) のメッセージボディーに埋め込まれるアクセストークンの属性として、次の二つを定義しています。

| 属性 | 説明 (仕様から抜粋) |
|:--|:--|
| `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` 属性がどのように使われるかを示しています。

```json
{
    "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 の実装](https://www.authlete.com/ja/developers/stepup_authn/#authlete-%E3%81%AE%E5%AE%9F%E8%A3%85)』をご参照ください。

# 最後に

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