Proof Key for Code Exchange by OAuth Public Clients

Abstract

概要

OAuth 2.0 public clients utilizing the Authorization Code Grant are susceptible to the authorization code interception attack. This specification describes the attack as well as a technique to mitigate against the threat through the use of Proof Key for Code Exchange (PKCE, pronounced "pixy").

認可コードグラントを利用する OAuth 2.0 のパブリッククライアントは、認可コード横取り攻撃 (authorization code interception attack) に対して脆弱である。本仕様はこの攻撃を説明するとともに、Proof Key for Code Exchange (PKCE、「ピクシー」と発音する) を用いてこの脅威を緩和する手法を記述する。

1.Introduction

1.はじめに

OAuth 2.0 [RFC6749] public clients are susceptible to the authorization code interception attack.

OAuth 2.0 [RFC6749] のパブリッククライアントは、認可コード横取り攻撃に対して脆弱である。

In this attack, the attacker intercepts the authorization code returned from the authorization endpoint within a communication path not protected by Transport Layer Security (TLS), such as inter- application communication within the client's operating system.

この攻撃では、攻撃者は、クライアントのオペレーティングシステム内でのアプリケーション間通信など、Transport Layer Security (TLS) で保護されていない通信経路において、認可エンドポイントから返された認可コードを横取りする。

Once the attacker has gained access to the authorization code, it can use it to obtain the access token.

攻撃者はいったん認可コードを入手すると、それを使ってアクセストークンを取得できる。

Figure 1 shows the attack graphically. In step (1), the native application running on the end device, such as a smartphone, issues an OAuth 2.0 Authorization Request via the browser/operating system. The Redirection Endpoint URI in this case typically uses a custom URI scheme. Step (1) happens through a secure API that cannot be intercepted, though it may potentially be observed in advanced attack scenarios. The request then gets forwarded to the OAuth 2.0 authorization server in step (2). Because OAuth requires the use of TLS, this communication is protected by TLS and cannot be intercepted. The authorization server returns the authorization code in step (3). In step (4), the Authorization Code is returned to the requester via the Redirection Endpoint URI that was provided in step (1).

図 1 はこの攻撃を図示したものである。ステップ (1) では、スマートフォンなどの端末上で動作するネイティブアプリケーションが、ブラウザー／オペレーティングシステムを介して OAuth 2.0 認可リクエストを発行する。この場合のリダイレクトエンドポイント URI は、通常カスタム URI スキームを用いる。ステップ (1) は横取りできない安全な API を通じて行われるが、高度な攻撃シナリオでは観測される可能性はある。リクエストはその後ステップ (2) で OAuth 2.0 認可サーバーへ転送される。OAuth は TLS の使用を要求するため、この通信は TLS で保護されており横取りできない。認可サーバーはステップ (3) で認可コードを返す。ステップ (4) では、認可コードはステップ (1) で提供されたリダイレクトエンドポイント URI を介して要求元へ返される。

Note that it is possible for a malicious app to register itself as a handler for the custom scheme in addition to the legitimate OAuth 2.0 app. Once it does so, the malicious app is now able to intercept the authorization code in step (4). This allows the attacker to request and obtain an access token in steps (5) and (6), respectively.

悪意のあるアプリが、正規の OAuth 2.0 アプリに加えて、そのカスタムスキームのハンドラーとして自身を登録することが可能である点に注意すること。そうすると、悪意のあるアプリはステップ (4) で認可コードを横取りできるようになる。これにより攻撃者は、ステップ (5) および (6) でそれぞれアクセストークンを要求し、取得できる。

A number of pre-conditions need to hold for this attack to work:

この攻撃が成立するには、いくつかの前提条件が成り立っている必要がある:

1. The attacker manages to register a malicious application on the client device and registers a custom URI scheme that is also used by another application. The operating systems must allow a custom URI scheme to be registered by multiple applications.

1. 攻撃者がクライアント端末上に悪意のあるアプリケーションを登録することに成功し、別のアプリケーションも使用しているカスタム URI スキームを登録する。オペレーティングシステムが、複数のアプリケーションによる同一のカスタム URI スキームの登録を許可している必要がある。

2. The OAuth 2.0 authorization code grant is used.

2. OAuth 2.0 の認可コードグラントが使用されている。

3. The attacker has access to the OAuth 2.0 [RFC6749] "client_id" and "client_secret" (if provisioned). All OAuth 2.0 native app client-instances use the same "client_id". Secrets provisioned in client binary applications cannot be considered confidential.

3. 攻撃者が OAuth 2.0 [RFC6749] の "client_id" および "client_secret" (プロビジョニングされている場合) にアクセスできる。OAuth 2.0 のネイティブアプリのクライアントインスタンスはすべて同じ "client_id" を使用する。クライアントのバイナリアプリケーションにプロビジョニングされたシークレットは、機密であるとはみなせない。

4. Either one of the following condition is met:

4. 次の条件のいずれかが満たされている:

4a. The attacker (via the installed application) is able to observe only the responses from the authorization endpoint. When "code_challenge_method" value is "plain", only this attack is mitigated.

4a. 攻撃者が (インストールされたアプリケーションを通じて) 認可エンドポイントからのレスポンスのみを観測できる。"code_challenge_method" の値が "plain" の場合、この攻撃だけが緩和される。

4b. A more sophisticated attack scenario allows the attacker to observe requests (in addition to responses) to the authorization endpoint. The attacker is, however, not able to act as a man in the middle. This was caused by leaking http log information in the OS. To mitigate this, "code_challenge_method" value must be set either to "S256" or a value defined by a cryptographically secure "code_challenge_method" extension.

4b. より高度な攻撃シナリオでは、攻撃者は認可エンドポイントへのリクエスト (レスポンスに加えて) も観測できる。ただし攻撃者は中間者として振る舞うことはできない。これは OS 内で http ログ情報が漏洩したことに起因する。これを緩和するには、"code_challenge_method" の値を "S256" か、暗号学的に安全な "code_challenge_method" 拡張で定義された値のいずれかに設定しなければならない。

While this is a long list of pre-conditions, the described attack has been observed in the wild and has to be considered in OAuth 2.0 deployments. While the OAuth 2.0 threat model (Section 4.4.1 of [RFC6819]) describes mitigation techniques, they are, unfortunately, not applicable since they rely on a per-client instance secret or a per-client instance redirect URI.

前提条件のリストは長いものの、ここで述べた攻撃は実際に観測されており、OAuth 2.0 の運用において考慮しなければならない。OAuth 2.0 脅威モデル ([RFC6819] の 4.4.1 節) は緩和手法を記述しているが、残念ながらそれらはクライアントインスタンスごとのシークレットまたはクライアントインスタンスごとのリダイレクト URI に依存しているため、適用できない。

To mitigate this attack, this extension utilizes a dynamically created cryptographically random key called "code verifier". A unique code verifier is created for every authorization request, and its transformed value, called "code challenge", is sent to the authorization server to obtain the authorization code. The authorization code obtained is then sent to the token endpoint with the "code verifier", and the server compares it with the previously received request code so that it can perform the proof of possession of the "code verifier" by the client. This works as the mitigation since the attacker would not know this one-time key, since it is sent over TLS and cannot be intercepted.

この攻撃を緩和するため、本拡張は「コードベリファイア (code verifier)」と呼ばれる、動的に生成される暗号学的にランダムな鍵を利用する。一意のコードベリファイアが認可リクエストごとに生成され、その変換値である「コードチャレンジ (code challenge)」が、認可コードを取得するために認可サーバーへ送られる。取得した認可コードは次に「コードベリファイア」とともにトークンエンドポイントへ送られ、サーバーはそれを以前に受け取ったリクエストのコード (チャレンジ) と比較することで、クライアントによる「コードベリファイア」の所有証明を行える。攻撃者はこの一回限りの鍵を知り得ないため、これが緩和策として機能する。鍵は TLS 上で送られ、横取りできないからである。

1.1.Protocol Flow

1.1.プロトコルフロー

This specification adds additional parameters to the OAuth 2.0 Authorization and Access Token Requests, shown in abstract form in Figure 2.

本仕様は OAuth 2.0 の認可リクエストおよびアクセストークンリクエストに追加のパラメーターを加える。図 2 にその抽象的な形を示す。

A. The client creates and records a secret named the "code_verifier" and derives a transformed version "t(code_verifier)" (referred to as the "code_challenge"), which is sent in the OAuth 2.0 Authorization Request along with the transformation method "t_m".

A. クライアントは "code_verifier" という名前のシークレットを生成して記録し、その変換版 "t(code_verifier)" ("code_challenge" と呼ぶ) を導出する。これは変換方式 "t_m" とともに OAuth 2.0 認可リクエストで送られる。

B. The Authorization Endpoint responds as usual but records "t(code_verifier)" and the transformation method.

B. 認可エンドポイントは通常どおり応答するが、"t(code_verifier)" と変換方式を記録する。

C. The client then sends the authorization code in the Access Token Request as usual but includes the "code_verifier" secret generated at (A).

C. クライアントは次に、通常どおりアクセストークンリクエストで認可コードを送るが、(A) で生成した "code_verifier" シークレットを含める。

D. The authorization server transforms "code_verifier" and compares it to "t(code_verifier)" from (B). Access is denied if they are not equal.

D. 認可サーバーは "code_verifier" を変換し、(B) で得た "t(code_verifier)" と比較する。等しくなければアクセスは拒否される。

An attacker who intercepts the authorization code at (B) is unable to redeem it for an access token, as they are not in possession of the "code_verifier" secret.

(B) で認可コードを横取りした攻撃者は、"code_verifier" シークレットを所有していないため、それをアクセストークンと引き換えることができない。

2.Notational Conventions

2.表記規約

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119]. If these words are used without being spelled in uppercase, then they are to be interpreted with their natural language meanings.

本文書におけるキーワード "MUST"、"MUST NOT"、"REQUIRED"、"SHALL"、"SHALL NOT"、"SHOULD"、"SHOULD NOT"、"RECOMMENDED"、"NOT RECOMMENDED"、"MAY"、"OPTIONAL" は、"Key words for use in RFCs to Indicate Requirement Levels" [RFC2119] に記述されたとおりに解釈される。これらの語が大文字で綴られずに使われている場合は、自然言語としての意味で解釈される。

This specification uses the Augmented Backus-Naur Form (ABNF) notation of [RFC5234].

本仕様は [RFC5234] の Augmented Backus-Naur Form (ABNF) 表記を使用する。

STRING denotes a sequence of zero or more ASCII [RFC20] characters.

STRING は 0 個以上の ASCII [RFC20] 文字の並びを表す。

OCTETS denotes a sequence of zero or more octets.

OCTETS は 0 個以上のオクテットの並びを表す。

ASCII(STRING) denotes the octets of the ASCII [RFC20] representation of STRING where STRING is a sequence of zero or more ASCII characters.

ASCII(STRING) は、STRING の ASCII [RFC20] 表現のオクテット列を表す。ここで STRING は 0 個以上の ASCII 文字の並びである。

BASE64URL-ENCODE(OCTETS) denotes the base64url encoding of OCTETS, per Appendix A, producing a STRING.

BASE64URL-ENCODE(OCTETS) は、付録 A に従った OCTETS の base64url エンコーディングを表し、STRING を生成する。

BASE64URL-DECODE(STRING) denotes the base64url decoding of STRING, per Appendix A, producing a sequence of octets.

BASE64URL-DECODE(STRING) は、付録 A に従った STRING の base64url デコーディングを表し、オクテットの並びを生成する。

SHA256(OCTETS) denotes a SHA2 256-bit hash [RFC6234] of OCTETS.

SHA256(OCTETS) は OCTETS の SHA2 256 ビットハッシュ [RFC6234] を表す。

3.Terminology

3.用語

In addition to the terms defined in OAuth 2.0 [RFC6749], this specification defines the following terms:

OAuth 2.0 [RFC6749] で定義された用語に加えて、本仕様は次の用語を定義する:

code verifier A cryptographically random string that is used to correlate the authorization request to the token request.

コードベリファイア (code verifier) 認可リクエストとトークンリクエストを関連付けるために用いられる、暗号学的にランダムな文字列。

code challenge A challenge derived from the code verifier that is sent in the authorization request, to be verified against later.

コードチャレンジ (code challenge) コードベリファイアから導出されるチャレンジ。認可リクエストで送られ、後で照合に用いられる。

code challenge method A method that was used to derive code challenge.

コードチャレンジメソッド (code challenge method) コードチャレンジの導出に用いられた方式。

Base64url Encoding Base64 encoding using the URL- and filename-safe character set defined in Section 5 of [RFC4648], with all trailing '=' characters omitted (as permitted by Section 3.2 of [RFC4648]) and without the inclusion of any line breaks, whitespace, or other additional characters. (See Appendix A for notes on implementing base64url encoding without padding.)

Base64url エンコーディング [RFC4648] の 5 節で定義された URL およびファイル名に安全な文字集合を用いた Base64 エンコーディングで、末尾の '=' 文字をすべて省略し ([RFC4648] の 3.2 節で許されているとおり)、改行、空白、その他の追加文字を一切含めないもの。(パディングなしの base64url エンコーディングの実装に関する注記は付録 A を参照。)

3.1.Abbreviations

3.1.略語

ABNF Augmented Backus-Naur Form

ABNF Augmented Backus-Naur Form (拡張バッカス・ナウア記法)

Authz Authorization

Authz Authorization (認可)

PKCE Proof Key for Code Exchange

PKCE Proof Key for Code Exchange

MITM Man-in-the-middle

MITM Man-in-the-middle (中間者)

MTI Mandatory To Implement

MTI Mandatory To Implement (実装必須)

4.Protocol

4.プロトコル

4.1.Client Creates a Code Verifier

4.1.クライアントがコードベリファイアを生成する

The client first creates a code verifier, "code_verifier", for each OAuth 2.0 [RFC6749] Authorization Request, in the following manner:

クライアントはまず、OAuth 2.0 [RFC6749] 認可リクエストごとに、次の方法でコードベリファイア "code_verifier" を生成する:

code_verifier = high-entropy cryptographic random STRING using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" from Section 2.3 of [RFC3986], with a minimum length of 43 characters and a maximum length of 128 characters.

code_verifier = [RFC3986] の 2.3 節の非予約文字 [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" を用いた、高エントロピーの暗号学的にランダムな STRING で、最小長 43 文字、最大長 128 文字のもの。

ABNF for "code_verifier" is as follows.

"code_verifier" の ABNF は次のとおりである。

code-verifier = 43*128unreserved unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" ALPHA = %x41-5A / %x61-7A DIGIT = %x30-39

code-verifier = 43*128unreserved unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" ALPHA = %x41-5A / %x61-7A DIGIT = %x30-39

NOTE: The code verifier SHOULD have enough entropy to make it impractical to guess the value. It is RECOMMENDED that the output of a suitable random number generator be used to create a 32-octet sequence. The octet sequence is then base64url-encoded to produce a 43-octet URL safe string to use as the code verifier.

注: コードベリファイアは、値の推測が現実的でなくなるだけの十分なエントロピーを持つべきである (SHOULD)。適切な乱数生成器の出力を用いて 32 オクテットの列を生成することが推奨される (RECOMMENDED)。このオクテット列を base64url エンコードして 43 オクテットの URL 安全な文字列を生成し、それをコードベリファイアとして用いる。

4.2.Client Creates the Code Challenge

4.2.クライアントがコードチャレンジを生成する

The client then creates a code challenge derived from the code verifier by using one of the following transformations on the code verifier:

クライアントは次に、コードベリファイアに対して次の変換のいずれかを適用し、コードベリファイアから導出されるコードチャレンジを生成する:

plain code_challenge = code_verifier

plain code_challenge = code_verifier

S256 code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

S256 code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

If the client is capable of using "S256", it MUST use "S256", as "S256" is Mandatory To Implement (MTI) on the server. Clients are permitted to use "plain" only if they cannot support "S256" for some technical reason and know via out-of-band configuration that the server supports "plain".

クライアントが "S256" を使用できる場合、"S256" を使用しなければならない (MUST)。"S256" はサーバー側で実装必須 (MTI) だからである。クライアントが "plain" を使用することが許されるのは、何らかの技術的理由で "S256" をサポートできず、かつサーバーが "plain" をサポートしていることを帯域外の設定によって知っている場合に限られる。

The plain transformation is for compatibility with existing deployments and for constrained environments that can't use the S256 transformation.

plain 変換は、既存の運用環境との互換性のため、および S256 変換を使用できない制約のある環境のために用意されている。

ABNF for "code_challenge" is as follows.

"code_challenge" の ABNF は次のとおりである。

code-challenge = 43*128unreserved unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" ALPHA = %x41-5A / %x61-7A DIGIT = %x30-39

code-challenge = 43*128unreserved unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" ALPHA = %x41-5A / %x61-7A DIGIT = %x30-39

4.3.Client Sends the Code Challenge with the Authorization Request

4.3.クライアントが認可リクエストとともにコードチャレンジを送る

The client sends the code challenge as part of the OAuth 2.0 Authorization Request (Section 4.1.1 of [RFC6749]) using the following additional parameters:

クライアントは、次の追加パラメーターを用いて、OAuth 2.0 認可リクエスト ([RFC6749] の 4.1.1 節) の一部としてコードチャレンジを送る:

code_challenge REQUIRED. Code challenge.

code_challenge 必須 (REQUIRED)。コードチャレンジ。

code_challenge_method OPTIONAL, defaults to "plain" if not present in the request. Code verifier transformation method is "S256" or "plain".

code_challenge_method 任意 (OPTIONAL)。リクエストに存在しない場合、既定値は "plain"。コードベリファイアの変換方式で、"S256" または "plain" である。

4.4.Server Returns the Code

4.4.サーバーがコードを返す

When the server issues the authorization code in the authorization response, it MUST associate the "code_challenge" and "code_challenge_method" values with the authorization code so it can be verified later.

サーバーが認可レスポンスで認可コードを発行する際、後で検証できるように、"code_challenge" および "code_challenge_method" の値を認可コードに関連付けなければならない (MUST)。

Typically, the "code_challenge" and "code_challenge_method" values are stored in encrypted form in the "code" itself but could alternatively be stored on the server associated with the code. The server MUST NOT include the "code_challenge" value in client requests in a form that other entities can extract.

典型的には、"code_challenge" および "code_challenge_method" の値は "code" 自体の中に暗号化された形で格納されるが、代わりにサーバー側でコードに関連付けて格納してもよい。サーバーは、他のエンティティが取り出せる形で "code_challenge" の値をクライアントへのリクエストに含めてはならない (MUST NOT)。

The exact method that the server uses to associate the "code_challenge" with the issued "code" is out of scope for this specification.

サーバーが "code_challenge" を発行した "code" に関連付けるための具体的な方法は、本仕様の範囲外である。

4.4.1.Error Response

4.4.1.エラーレスポンス

If the server requires Proof Key for Code Exchange (PKCE) by OAuth public clients and the client does not send the "code_challenge" in the request, the authorization endpoint MUST return the authorization error response with the "error" value set to "invalid_request". The "error_description" or the response of "error_uri" SHOULD explain the nature of error, e.g., code challenge required.

サーバーが OAuth パブリッククライアントに対して Proof Key for Code Exchange (PKCE) を要求しており、かつクライアントがリクエストで "code_challenge" を送らなかった場合、認可エンドポイントは "error" の値を "invalid_request" に設定した認可エラーレスポンスを返さなければならない (MUST)。"error_description" または "error_uri" のレスポンスは、エラーの性質 (例えば、コードチャレンジが必要であること) を説明すべきである (SHOULD)。

If the server supporting PKCE does not support the requested transformation, the authorization endpoint MUST return the authorization error response with "error" value set to "invalid_request". The "error_description" or the response of "error_uri" SHOULD explain the nature of error, e.g., transform algorithm not supported.

PKCE をサポートするサーバーが、要求された変換をサポートしていない場合、認可エンドポイントは "error" の値を "invalid_request" に設定した認可エラーレスポンスを返さなければならない (MUST)。"error_description" または "error_uri" のレスポンスは、エラーの性質 (例えば、変換アルゴリズムが未サポートであること) を説明すべきである (SHOULD)。

4.5.Client Sends the Authorization Code and the Code Verifier to the Token Endpoint

4.5.クライアントが認可コードとコードベリファイアをトークンエンドポイントへ送る

Upon receipt of the Authorization Code, the client sends the Access Token Request to the token endpoint. In addition to the parameters defined in the OAuth 2.0 Access Token Request (Section 4.1.3 of [RFC6749]), it sends the following parameter:

認可コードを受け取ると、クライアントはトークンエンドポイントへアクセストークンリクエストを送る。OAuth 2.0 アクセストークンリクエスト ([RFC6749] の 4.1.3 節) で定義されたパラメーターに加えて、次のパラメーターを送る:

code_verifier REQUIRED. Code verifier

code_verifier 必須 (REQUIRED)。コードベリファイア

The "code_challenge_method" is bound to the Authorization Code when the Authorization Code is issued. That is the method that the token endpoint MUST use to verify the "code_verifier".

"code_challenge_method" は、認可コードが発行される際に認可コードに束縛される。それが、トークンエンドポイントが "code_verifier" の検証に使用しなければならない (MUST) 方式である。

4.6.Server Verifies code_verifier before Returning the Tokens

4.6.サーバーがトークンを返す前に code_verifier を検証する

Upon receipt of the request at the token endpoint, the server verifies it by calculating the code challenge from the received "code_verifier" and comparing it with the previously associated "code_challenge", after first transforming it according to the "code_challenge_method" method specified by the client.

トークンエンドポイントでリクエストを受け取ると、サーバーは、受け取った "code_verifier" をクライアントが指定した "code_challenge_method" の方式に従ってまず変換してコードチャレンジを計算し、それを以前に関連付けた "code_challenge" と比較することで、リクエストを検証する。

If the "code_challenge_method" from Section 4.3 was "S256", the received "code_verifier" is hashed by SHA-256, base64url-encoded, and then compared to the "code_challenge", i.e.:

4.3 節の "code_challenge_method" が "S256" であった場合、受け取った "code_verifier" を SHA-256 でハッシュし、base64url エンコードしてから、"code_challenge" と比較する。すなわち:

BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) == code_challenge

BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) == code_challenge

If the "code_challenge_method" from Section 4.3 was "plain", they are compared directly, i.e.:

4.3 節の "code_challenge_method" が "plain" であった場合、両者を直接比較する。すなわち:

code_verifier == code_challenge.

code_verifier == code_challenge.

If the values are equal, the token endpoint MUST continue processing as normal (as defined by OAuth 2.0 [RFC6749]). If the values are not equal, an error response indicating "invalid_grant" as described in Section 5.2 of [RFC6749] MUST be returned.

値が等しい場合、トークンエンドポイントは (OAuth 2.0 [RFC6749] で定義されたとおり) 通常どおり処理を継続しなければならない (MUST)。値が等しくない場合、[RFC6749] の 5.2 節に記述された "invalid_grant" を示すエラーレスポンスを返さなければならない (MUST)。

5.Compatibility

5.互換性

Server implementations of this specification MAY accept OAuth2.0 clients that do not implement this extension. If the "code_verifier" is not received from the client in the Authorization Request, servers supporting backwards compatibility revert to the OAuth 2.0 [RFC6749] protocol without this extension.

本仕様のサーバー実装は、本拡張を実装していない OAuth 2.0 クライアントを受け入れてもよい (MAY)。認可リクエストでクライアントから "code_verifier" を受け取らなかった場合、後方互換性をサポートするサーバーは本拡張なしの OAuth 2.0 [RFC6749] プロトコルに戻る。

As the OAuth 2.0 [RFC6749] server responses are unchanged by this specification, client implementations of this specification do not need to know if the server has implemented this specification or not and SHOULD send the additional parameters as defined in Section 4 to all servers.

OAuth 2.0 [RFC6749] のサーバーレスポンスは本仕様によって変更されないため、本仕様のクライアント実装はサーバーが本仕様を実装しているかどうかを知る必要はなく、4 節で定義された追加パラメーターをすべてのサーバーに送るべきである (SHOULD)。

6.IANA Considerations

6.IANA に関する考慮事項

IANA has made the following registrations per this document.

IANA は本文書に従って次の登録を行った。

6.1.OAuth Parameters Registry

6.1.OAuth パラメーターレジストリ

This specification registers the following parameters in the IANA "OAuth Parameters" registry defined in OAuth 2.0 [RFC6749].

本仕様は、OAuth 2.0 [RFC6749] で定義された IANA の "OAuth Parameters" レジストリに次のパラメーターを登録する。

o Parameter name: code_verifier

o パラメータ名: code_verifier

o Parameter usage location: token request

o パラメータの使用箇所: トークンリクエスト

o Change controller: IESG

o 変更管理者: IESG

o Specification document(s): RFC 7636 (this document)

o 仕様文書: RFC 7636 (本文書)

o Parameter name: code_challenge

o パラメータ名: code_challenge

o Parameter usage location: authorization request

o パラメータの使用箇所: 認可リクエスト

o Change controller: IESG

o 変更管理者: IESG

o Specification document(s): RFC 7636 (this document)

o 仕様文書: RFC 7636 (本文書)

o Parameter name: code_challenge_method

o パラメータ名: code_challenge_method

o Parameter usage location: authorization request

o パラメータの使用箇所: 認可リクエスト

o Change controller: IESG

o 変更管理者: IESG

o Specification document(s): RFC 7636 (this document)

o 仕様文書: RFC 7636 (本文書)

6.2.PKCE Code Challenge Method Registry

6.2.PKCE コードチャレンジメソッドレジストリ

This specification establishes the "PKCE Code Challenge Methods" registry. The new registry should be a sub-registry of the "OAuth Parameters" registry.

本仕様は "PKCE Code Challenge Methods" レジストリを創設する。この新しいレジストリは "OAuth Parameters" レジストリのサブレジストリとすべきである。

Additional "code_challenge_method" types for use with the authorization endpoint are registered using the Specification Required policy [RFC5226], which includes review of the request by one or more Designated Experts (DEs). The DEs will ensure that there is at least a two-week review of the request on the oauth-ext- review@ietf.org mailing list and that any discussion on that list converges before they respond to the request. To allow for the allocation of values prior to publication, the Designated Expert(s) may approve registration once they are satisfied that an acceptable specification will be published.

認可エンドポイントで使用する追加の "code_challenge_method" 種別は、Specification Required ポリシー [RFC5226] に従って登録される。このポリシーには、1 名以上の指名専門家 (Designated Expert、DE) による申請の審査が含まれる。DE は、oauth-ext-review@ietf.org メーリングリストで申請について少なくとも 2 週間の審査が行われること、およびそのリスト上の議論が収束してから申請に応答することを保証する。公開前に値を割り当てられるようにするため、指名専門家は、受け入れ可能な仕様が公開されると確信した時点で登録を承認してもよい。

Registration requests and discussion on the oauth-ext-review@ietf.org mailing list should use an appropriate subject, such as "Request for PKCE code_challenge_method: example").

oauth-ext-review@ietf.org メーリングリスト上での登録リクエストおよび議論には、"Request for PKCE code_challenge_method: example" のような適切な件名を用いるべきである。

The Designated Expert(s) should consider the discussion on the mailing list, as well as the overall security properties of the challenge method when evaluating registration requests. New methods should not disclose the value of the code_verifier in the request to the Authorization endpoint. Denials should include an explanation and, if applicable, suggestions as to how to make the request successful.

指定専門家は、登録リクエストを評価する際、メーリングリスト上の議論に加えて、そのチャレンジメソッドの全体的なセキュリティ特性を考慮すべきである。新しいメソッドは、認可エンドポイントへのリクエストにおいて code_verifier の値を漏らすべきではない。却下する場合は説明を含め、該当する場合はリクエストを成功させるための提案を含めるべきである。

6.2.1.Registration Template

6.2.1.登録テンプレート

Code Challenge Method Parameter Name: The name requested (e.g., "example"). Because a core goal of this specification is for the resulting representations to be compact, it is RECOMMENDED that the name be short -- not to exceed 8 characters without a compelling reason to do so. This name is case-sensitive. Names may not match other registered names in a case-insensitive manner unless the Designated Expert(s) states that there is a compelling reason to allow an exception in this particular case.

コードチャレンジメソッドパラメーター名: 要求する名前 (例: "example")。本仕様の中核的な目標の一つは結果として得られる表現をコンパクトにすることであるため、名前は短くすること、すなわち、そうすべき説得力のある理由がない限り 8 文字を超えないことが推奨される (RECOMMENDED)。この名前は大文字・小文字を区別する。指定専門家が、この特定のケースにおいて例外を認める説得力のある理由があると表明しない限り、名前は他の登録済みの名前と大文字・小文字を区別しない比較で一致してはならない。

Change Controller: For Standards Track RFCs, state "IESG". For others, give the name of the responsible party. Other details (e.g., postal address, email address, and home page URI) may also be included.

変更管理者: Standards Track の RFC については "IESG" と記す。それ以外については責任者の名前を記す。その他の詳細 (例: 郵便住所、メールアドレス、ホームページの URI) を含めてもよい。

Specification Document(s): Reference to the document(s) that specifies the parameter, preferably including URI(s) that can be used to retrieve copies of the document(s). An indication of the relevant sections may also be included but is not required.

仕様文書: パラメーターを規定する文書への参照。文書のコピーを取得するために使用できる URI を含めることが望ましい。関連する節の指示を含めてもよいが、必須ではない。

6.2.2.Initial Registry Contents

6.2.2.レジストリの初期内容

Per this document, IANA has registered the Code Challenge Method Parameter Names defined in Section 4.2 in this registry.

本文書に従い、IANA は 4.2 節で定義されたコードチャレンジメソッドパラメーター名をこのレジストリに登録した。

o Code Challenge Method Parameter Name: plain

o コードチャレンジメソッドのパラメータ名: plain

o Change Controller: IESG

o 変更管理者: IESG

o Specification Document(s): Section 4.2 of RFC 7636 (this document)

o 仕様文書: RFC 7636 (本文書) の 4.2 節

o Code Challenge Method Parameter Name: S256

o コードチャレンジメソッドのパラメータ名: S256

o Change Controller: IESG

o 変更管理者: IESG

o Specification Document(s): Section 4.2 of RFC 7636 (this document)

o 仕様文書: RFC 7636 (本文書) の 4.2 節

7.Security Considerations

7.セキュリティに関する考慮事項

7.1.Entropy of the code_verifier

7.1.code_verifier のエントロピー

The security model relies on the fact that the code verifier is not learned or guessed by the attacker. It is vitally important to adhere to this principle. As such, the code verifier has to be created in such a manner that it is cryptographically random and has high entropy that it is not practical for the attacker to guess.

このセキュリティモデルは、コードベリファイアが攻撃者に知られたり推測されたりしないという事実に依拠している。この原則を守ることは極めて重要である。したがって、コードベリファイアは、暗号学的にランダムであり、攻撃者による推測が現実的でないほど高いエントロピーを持つように生成しなければならない。

The client SHOULD create a "code_verifier" with a minimum of 256 bits of entropy. This can be done by having a suitable random number generator create a 32-octet sequence. The octet sequence can then be base64url-encoded to produce a 43-octet URL safe string to use as a "code_challenge" that has the required entropy.

クライアントは最低 256 ビットのエントロピーを持つ "code_verifier" を生成すべきである (SHOULD)。これは、適切な乱数生成器に 32 オクテットの列を生成させることで実現できる。そのオクテット列を base64url エンコードすれば、必要なエントロピーを持つ 43 オクテットの URL 安全な文字列が得られ、これを "code_challenge" として用いることができる。

7.2.Protection against Eavesdroppers

7.2.盗聴者に対する保護

Clients MUST NOT downgrade to "plain" after trying the "S256" method. Servers that support PKCE are required to support "S256", and servers that do not support PKCE will simply ignore the unknown "code_verifier". Because of this, an error when "S256" is presented can only mean that the server is faulty or that a MITM attacker is trying a downgrade attack.

クライアントは、"S256" メソッドを試みた後に "plain" へダウングレードしてはならない (MUST NOT)。PKCE をサポートするサーバーは "S256" のサポートを要求されており、PKCE をサポートしないサーバーは未知の "code_verifier" を単に無視する。このため、"S256" を提示した際のエラーは、サーバーに欠陥があるか、MITM 攻撃者がダウングレード攻撃を試みているかのいずれかしか意味し得ない。

The "S256" method protects against eavesdroppers observing or intercepting the "code_challenge", because the challenge cannot be used without the verifier. With the "plain" method, there is a chance that "code_challenge" will be observed by the attacker on the device or in the http request. Since the code challenge is the same as the code verifier in this case, the "plain" method does not protect against the eavesdropping of the initial request.

"S256" メソッドは、"code_challenge" を観測または横取りする盗聴者から保護する。チャレンジはベリファイアなしには使用できないからである。"plain" メソッドでは、"code_challenge" が端末上または HTTP リクエスト内で攻撃者に観測される可能性がある。この場合コードチャレンジはコードベリファイアと同一であるため、"plain" メソッドは最初のリクエストの盗聴に対して保護しない。

The use of "S256" protects against disclosure of the "code_verifier" value to an attacker.

"S256" の使用は、"code_verifier" の値の攻撃者への漏洩から保護する。

Because of this, "plain" SHOULD NOT be used and exists only for compatibility with deployed implementations where the request path is already protected. The "plain" method SHOULD NOT be used in new implementations, unless they cannot support "S256" for some technical reason.

このため、"plain" は使用すべきではなく (SHOULD NOT)、リクエスト経路がすでに保護されている既存の実装との互換性のためにのみ存在する。"plain" メソッドは、何らかの技術的理由で "S256" をサポートできない場合を除き、新しい実装では使用すべきではない (SHOULD NOT)。

The "S256" code challenge method or other cryptographically secure code challenge method extension SHOULD be used. The "plain" code challenge method relies on the operating system and transport security not to disclose the request to an attacker.

"S256" コードチャレンジメソッド、または他の暗号学的に安全なコードチャレンジメソッド拡張を使用すべきである (SHOULD)。"plain" コードチャレンジメソッドは、オペレーティングシステムおよびトランスポートのセキュリティがリクエストを攻撃者に漏らさないことに依存している。

If the code challenge method is "plain" and the code challenge is to be returned inside authorization "code" to achieve a stateless server, it MUST be encrypted in such a manner that only the server can decrypt and extract it.

コードチャレンジメソッドが "plain" であり、かつサーバーをステートレスにするためにコードチャレンジを認可 "code" の中に入れて返す場合、サーバーのみが復号して取り出せる方法で暗号化しなければならない (MUST)。

7.3.Salting the code_challenge

7.3.code_challenge へのソルト付加

To reduce implementation complexity, salting is not used in the production of the code challenge, as the code verifier contains sufficient entropy to prevent brute-force attacks. Concatenating a publicly known value to a code verifier (containing 256 bits of entropy) and then hashing it with SHA256 to produce a code challenge would not increase the number of attempts necessary to brute force a valid value for code verifier.

実装の複雑さを減らすため、コードチャレンジの生成にはソルトを用いない。コードベリファイアがブルートフォース攻撃を防ぐのに十分なエントロピーを含んでいるからである。(256 ビットのエントロピーを含む) コードベリファイアに公知の値を連結してから SHA256 でハッシュしてコードチャレンジを生成しても、有効なコードベリファイアの値をブルートフォースするのに必要な試行回数は増えない。

While the "S256" transformation is like hashing a password, there are important differences. Passwords tend to be relatively low-entropy words that can be hashed offline and the hash looked up in a dictionary. By concatenating a unique though public value to each password prior to hashing, the dictionary space that an attacker needs to search is greatly expanded.

"S256" 変換はパスワードのハッシュ化に似ているが、重要な違いがある。パスワードは比較的低エントロピーの語であることが多く、オフラインでハッシュ化して辞書から引くことができる。ハッシュ化の前に各パスワードに一意だが公開された値を連結することで、攻撃者が探索しなければならない辞書空間は大幅に拡大する。

Modern graphics processors now allow attackers to calculate hashes in real time faster than they could be looked up from a disk. This eliminates the value of the salt in increasing the complexity of a brute-force attack for even low-entropy passwords.

現代のグラフィックスプロセッサーにより、攻撃者はディスクから引くよりも速くリアルタイムでハッシュを計算できるようになった。これにより、低エントロピーのパスワードであっても、ブルートフォース攻撃の複雑さを増すというソルトの価値は失われている。

7.4.OAuth Security Considerations

7.4.OAuth のセキュリティに関する考慮事項

All the OAuth security analysis presented in [RFC6819] applies, so readers SHOULD carefully follow it.

[RFC6819] で提示されている OAuth のセキュリティ分析はすべて適用されるため、読者はそれを注意深く守るべきである (SHOULD)。

7.5.TLS Security Considerations

7.5.TLS のセキュリティに関する考慮事項

Current security considerations can be found in "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)" [BCP195]. This supersedes the TLS version recommendations in OAuth 2.0 [RFC6749].

現時点でのセキュリティに関する考慮事項は "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)" [BCP195] に記載されている。これは OAuth 2.0 [RFC6749] における TLS バージョンの推奨に取って代わる。

8.References

8.参考資料

8.1.Normative References

8.1.引用規格

8.2.Informative References

8.2.参考文献

A.Notes on Implementing Base64url Encoding without Padding

A.パディングなしの Base64url エンコーディング実装に関する注記

This appendix describes how to implement a base64url-encoding function without padding, based upon the standard base64-encoding function that uses padding.

本付録は、パディングを用いる標準の base64 エンコーディング関数に基づいて、パディングなしの base64url エンコーディング関数を実装する方法を記述する。

To be concrete, example C# code implementing these functions is shown below. Similar code could be used in other languages.

具体例として、これらの関数を実装した C# のサンプルコードを以下に示す。他の言語でも同様のコードが使用できる。

An example correspondence between unencoded and encoded values follows. The octet sequence below encodes into the string below, which when decoded, reproduces the octet sequence.

エンコード前の値とエンコード後の値の対応例を以下に示す。以下のオクテット列は以下の文字列にエンコードされ、その文字列をデコードするとそのオクテット列が再現される。

3 236 255 224 193

3 236 255 224 193

A-z_4ME

A-z_4ME

B.Example for the S256 code_challenge_method

B.S256 code_challenge_method の例

The client uses output of a suitable random number generator to create a 32-octet sequence. The octets representing the value in this example (using JSON array notation) are:

クライアントは適切な乱数生成器の出力を用いて 32 オクテットの列を生成する。この例における値を表すオクテット (JSON 配列表記を使用) は次のとおりである:

[116, 24, 223, 180, 151, 153, 224, 37, 79, 250, 96, 125, 216, 173, 187, 186, 22, 212, 37, 77, 105, 214, 191, 240, 91, 88, 5, 88, 83, 132, 141, 121]

[116, 24, 223, 180, 151, 153, 224, 37, 79, 250, 96, 125, 216, 173, 187, 186, 22, 212, 37, 77, 105, 214, 191, 240, 91, 88, 5, 88, 83, 132, 141, 121]

Encoding this octet sequence as base64url provides the value of the code_verifier:

このオクテット列を base64url でエンコードすると、code_verifier の値が得られる:

The code_verifier is then hashed via the SHA256 hash function to produce:

次に code_verifier を SHA256 ハッシュ関数でハッシュすると、次が得られる:

[19, 211, 30, 150, 26, 26, 216, 236, 47, 22, 177, 12, 76, 152, 46, 8, 118, 168, 120, 173, 109, 241, 68, 86, 110, 225, 137, 74, 203, 112, 249, 195]

[19, 211, 30, 150, 26, 26, 216, 236, 47, 22, 177, 12, 76, 152, 46, 8, 118, 168, 120, 173, 109, 241, 68, 86, 110, 225, 137, 74, 203, 112, 249, 195]

Encoding this octet sequence as base64url provides the value of the code_challenge:

このオクテット列を base64url でエンコードすると、code_challenge の値が得られる:

The authorization request includes:

認可リクエストには次が含まれる:

The authorization server then records the code_challenge and code_challenge_method along with the code that is granted to the client.

認可サーバーは次に、クライアントに付与するコードとともに code_challenge および code_challenge_method を記録する。

In the request to the token_endpoint, the client includes the code received in the authorization response as well as the additional parameter:

token_endpoint へのリクエストで、クライアントは認可レスポンスで受け取ったコードに加えて、次の追加パラメーターを含める:

The authorization server retrieves the information for the code grant. Based on the recorded code_challenge_method being S256, it then hashes and base64url-encodes the value of code_verifier:

認可サーバーはそのコードグラントの情報を取り出す。記録された code_challenge_method が S256 であることに基づき、code_verifier の値をハッシュして base64url エンコードする:

BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) == code_challenge

BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) == code_challenge

If the two values are equal, then the authorization server can provide the tokens as long as there are no other errors in the request. If the values are not equal, then the request must be rejected, and an error returned.

2 つの値が等しければ、リクエストに他のエラーがない限り、認可サーバーはトークンを提供できる。値が等しくなければ、リクエストは拒否され、エラーが返されなければならない。

Acknowledgements

謝辞

The initial draft version of this specification was created by the OpenID AB/Connect Working Group of the OpenID Foundation.

本仕様の最初のドラフト版は、OpenID Foundation の OpenID AB/Connect ワーキンググループによって作成された。

This specification is the work of the OAuth Working Group, which includes dozens of active and dedicated participants. In particular, the following individuals contributed ideas, feedback, and wording that shaped and formed the final specification:

本仕様は、数十名の活発かつ献身的な参加者を擁する OAuth ワーキンググループの成果である。特に、次の各氏が最終的な仕様を形作るアイデア、フィードバック、文言を提供した: