JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens

Abstract

概要

This specification defines a profile for issuing OAuth 2.0 access tokens in JSON Web Token (JWT) format. Authorization servers and resource servers from different vendors can leverage this profile to issue and consume access tokens in an interoperable manner.

本仕様は、OAuth 2.0 アクセストークンを JSON Web Token (JWT) 形式で発行するためのプロファイルを定義する。異なるベンダーの認可サーバーとリソースサーバーは、このプロファイルを活用することで、相互運用可能な形でアクセストークンを発行し、消費することができる。

1.Introduction

1.はじめに

The original OAuth 2.0 Authorization Framework [RFC6749] specification does not mandate any specific format for access tokens. While that remains perfectly appropriate for many important scenarios, in-market use has shown that many commercial OAuth 2.0 implementations elected to issue access tokens using a format that can be parsed and validated by resource servers directly, without further authorization server involvement. The approach is particularly common in topologies where the authorization server and resource server are not co-located, are not run by the same entity, or are otherwise separated by some boundary. At the time of writing, many commercial implementations leverage the JSON Web Token (JWT) [RFC7519] format.

元の OAuth 2.0 認可フレームワーク [RFC6749] の仕様は、アクセストークンに特定の形式を義務付けていない。これは多くの重要なシナリオにおいて依然として完全に適切であるが、市場での利用を見ると、多くの商用 OAuth 2.0 実装が、認可サーバーのそれ以上の関与なしにリソースサーバーが直接パースして検証できる形式でアクセストークンを発行することを選択してきた。この手法は、認可サーバーとリソースサーバーが同じ場所に配置されていない、同じ主体によって運用されていない、あるいは何らかの境界で分離されているトポロジーで特によく見られる。本書の執筆時点で、多くの商用実装が JSON Web Token (JWT) [RFC7519] 形式を活用している。

Many vendor-specific JWT access tokens share the same functional layout, using JWT claims to convey the information needed to support a common set of use cases: token validation, transporting authorization information in the form of scopes and entitlements, carrying identity information about the subject, and so on. The differences are mostly confined to the claim names and syntax used to represent the same entities, suggesting that interoperability could be easily achieved by standardizing a common set of claims and validation rules.

ベンダー固有の JWT アクセストークンの多くは同じ機能的レイアウトを共有しており、トークンの検証、スコープや権利 (entitlement) の形での認可情報の伝達、主体に関するアイデンティティ情報の保持といった共通のユースケース群を支えるために必要な情報を JWT クレームで伝えている。違いは主に、同じ実体を表すために使われるクレーム名と構文に限られており、共通のクレーム集合と検証規則を標準化すれば相互運用性を容易に達成できることを示唆している。

The assumption that access tokens are associated with specific information doesn't appear only in commercial implementations. Various specifications in the OAuth 2.0 family (such as resource indicators [RFC8707], OAuth 2.0 bearer token usage [RFC6750], and others) postulate the presence of scoping mechanisms, such as an audience, in access tokens. The family of specifications associated with introspection also indirectly suggests a fundamental set of information that access tokens are expected to carry or at least be associated with.

アクセストークンが特定の情報と関連付けられているという前提は、商用実装にだけ現れるものではない。OAuth 2.0 ファミリーのさまざまな仕様 (リソースインジケーター [RFC8707]、OAuth 2.0 ベアラートークンの利用 [RFC6750] など) は、オーディエンスのようなスコープ付けの仕組みがアクセストークンに存在することを前提としている。イントロスペクションに関連する仕様群もまた、アクセストークンが保持する、あるいは少なくとも関連付けられていると期待される基本的な情報の集合を間接的に示唆している。

This specification aims to provide a standardized and interoperable profile as an alternative to the proprietary JWT access token layouts going forward. Besides defining a common set of mandatory and optional claims, the profile provides clear indications on how authorization request parameters determine the content of the issued JWT access token, how an authorization server can publish metadata relevant to the JWT access tokens it issues, and how a resource server should validate incoming JWT access tokens.

本仕様は、今後、独自仕様の JWT アクセストークンレイアウトに代わる、標準化された相互運用可能なプロファイルを提供することを目的とする。必須およびオプションのクレームの共通集合を定義するほか、このプロファイルは、認可リクエストのパラメーターが発行される JWT アクセストークンの内容をどのように決定するか、認可サーバーが自身の発行する JWT アクセストークンに関連するメタデータをどのように公開できるか、そしてリソースサーバーが受信した JWT アクセストークンをどのように検証すべきかについて明確な指針を提供する。

Finally, this specification provides security and privacy considerations meant to prevent common mistakes and anti-patterns that are likely to occur in naive use of the JWT format to represent access tokens.

最後に、本仕様は、アクセストークンを表現するために JWT 形式を素朴に用いた場合に起こりがちな、よくある誤りやアンチパターンを防ぐことを意図したセキュリティおよびプライバシーに関する考慮事項を提供する。

Please note: Although both this document and [RFC7523] use JSON Web Tokens in the context of the OAuth2 framework, the two specifications differ in both intent and mechanics. Whereas [RFC7523] defines how a JWT Bearer Token can be used to request an access token, this document describes how to encode access tokens in JWT format.

注意: 本書と [RFC7523] はいずれも OAuth2 フレームワークの文脈で JSON Web Token を用いるが、両仕様は意図と仕組みの両方において異なる。[RFC7523] が JWT ベアラートークンを用いてアクセストークンを要求する方法を定義するのに対し、本書はアクセストークンを JWT 形式でエンコードする方法を記述する。

1.1.Requirements Notation and Conventions

1.1.要件の表記と規約

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 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

本書におけるキーワード "MUST"、"MUST NOT"、"REQUIRED"、"SHALL"、"SHALL NOT"、"SHOULD"、"SHOULD NOT"、"RECOMMENDED"、"NOT RECOMMENDED"、"MAY"、"OPTIONAL" は、ここに示すようにすべて大文字で現れる場合に限り、BCP 14 [RFC2119] [RFC8174] に記述されるとおりに解釈される。

1.2.Terminology

1.2.用語

JWT access token: An OAuth 2.0 access token encoded in JWT format and complying with the requirements described in this specification.

JWT アクセストークン: JWT 形式でエンコードされ、本仕様に記述された要件に準拠する OAuth 2.0 アクセストークン。

This specification uses the terms "access token", "refresh token", "authorization server", "resource server", "authorization endpoint", "authorization request", "authorization response", "token endpoint", "grant type", "access token request", "access token response", and "client" defined by The OAuth 2.0 Authorization Framework [RFC6749].

本仕様は、OAuth 2.0 認可フレームワーク [RFC6749] で定義される用語「アクセストークン」「リフレッシュトークン」「認可サーバー」「リソースサーバー」「認可エンドポイント」「認可リクエスト」「認可レスポンス」「トークンエンドポイント」「グラントタイプ」「アクセストークンリクエスト」「アクセストークンレスポンス」「クライアント」を用いる。

2.JWT Access Token Header and Data Structure

2.JWT アクセストークンのヘッダーとデータ構造

2.1.Header

2.1.ヘッダー

JWT access tokens MUST be signed. Although JWT access tokens can use any signing algorithm, use of asymmetric cryptography is RECOMMENDED as it simplifies the process of acquiring validation information for resource servers (see Section 4). JWT access tokens MUST NOT use "none" as the signing algorithm. See Section 4 for more details.

JWT アクセストークンは署名されなければならない (MUST)。JWT アクセストークンはどの署名アルゴリズムでも使用できるが、リソースサーバーが検証情報を取得する手順を簡素化できるため、非対称暗号の使用が推奨される (RECOMMENDED) (4 節参照)。JWT アクセストークンは署名アルゴリズムとして "none" を使用してはならない (MUST NOT)。詳細は 4 節を参照のこと。

Authorization servers and resource servers conforming to this specification MUST include RS256 (as defined in [RFC7518]) among their supported signature algorithms.

本仕様に準拠する認可サーバーおよびリソースサーバーは、サポートする署名アルゴリズムに RS256 ([RFC7518] で定義) を含めなければならない (MUST)。

This specification registers the "application/at+jwt" media type, which can be used to indicate that the content is a JWT access token. JWT access tokens MUST include this media type in the "typ" header parameter to explicitly declare that the JWT represents an access token complying with this profile. Per the definition of "typ" in Section 4.1.9 of [RFC7515], it is RECOMMENDED that the "application/" prefix be omitted. Therefore, the "typ" value used SHOULD be "at+jwt". See the Security Considerations section for details on the importance of preventing OpenID Connect ID Tokens (as defined by Section 2 of [OpenID.Core]) from being accepted as access tokens by resource servers implementing this profile.

本仕様は "application/at+jwt" メディアタイプを登録する。これは、内容が JWT アクセストークンであることを示すために使用できる。JWT アクセストークンは、その JWT が本プロファイルに準拠するアクセストークンを表すことを明示的に宣言するために、このメディアタイプを "typ" ヘッダーパラメーターに含めなければならない (MUST)。[RFC7515] の 4.1.9 節における "typ" の定義に従い、"application/" プレフィックスは省略することが推奨される (RECOMMENDED)。したがって、使用する "typ" の値は "at+jwt" とすべきである (SHOULD)。本プロファイルを実装するリソースサーバーが OpenID Connect ID トークン ([OpenID.Core] の 2 節で定義) をアクセストークンとして受け入れてしまうことを防ぐことの重要性については、セキュリティに関する考慮事項の節を参照のこと。

2.2.Data Structure

2.2.データ構造

The following claims are used in the JWT access token data structure.

JWT アクセストークンのデータ構造では、以下のクレームが使用される。

iss REQUIRED - as defined in Section 4.1.1 of [RFC7519].

iss REQUIRED - [RFC7519] の 4.1.1 節で定義されるとおり。

exp REQUIRED - as defined in Section 4.1.4 of [RFC7519].

exp REQUIRED - [RFC7519] の 4.1.4 節で定義されるとおり。

aud REQUIRED - as defined in Section 4.1.3 of [RFC7519]. See Section 3 for indications on how an authorization server should determine the value of "aud" depending on the request.

aud REQUIRED - [RFC7519] の 4.1.3 節で定義されるとおり。認可サーバーがリクエストに応じて "aud" の値をどのように決定すべきかの指針については 3 節を参照のこと。

sub REQUIRED - as defined in Section 4.1.2 of [RFC7519]. In cases of access tokens obtained through grants where a resource owner is involved, such as the authorization code grant, the value of "sub" SHOULD correspond to the subject identifier of the resource owner. In cases of access tokens obtained through grants where no resource owner is involved, such as the client credentials grant, the value of "sub" SHOULD correspond to an identifier the authorization server uses to indicate the client application. See Section 5 for more details on this scenario. Also, see Section 6 for a discussion about how different choices in assigning "sub" values can impact privacy.

sub REQUIRED - [RFC7519] の 4.1.2 節で定義されるとおり。認可コードグラントのように、リソースオーナーが関与するグラントを通じて取得されたアクセストークンの場合、"sub" の値はリソースオーナーの主体識別子に対応すべきである (SHOULD)。クライアントクレデンシャルグラントのように、リソースオーナーが関与しないグラントを通じて取得されたアクセストークンの場合、"sub" の値は認可サーバーがクライアントアプリケーションを示すために用いる識別子に対応すべきである (SHOULD)。このシナリオの詳細については 5 節を参照のこと。また、"sub" の値の割り当て方の違いがプライバシーに与え得る影響についての議論は 6 節を参照のこと。

client_id REQUIRED - as defined in Section 4.3 of [RFC8693].

client_id REQUIRED - [RFC8693] の 4.3 節で定義されるとおり。

iat REQUIRED - as defined in Section 4.1.6 of [RFC7519]. This claim identifies the time at which the JWT access token was issued.

iat REQUIRED - [RFC7519] の 4.1.6 節で定義されるとおり。このクレームは JWT アクセストークンが発行された時刻を示す。

jti REQUIRED - as defined in Section 4.1.7 of [RFC7519].

jti REQUIRED - [RFC7519] の 4.1.7 節で定義されるとおり。

2.2.1.Authentication Information Claims

2.2.1.認証情報クレーム

The claims listed in this section MAY be issued in the context of authorization grants involving the resource owner and reflect the types and strength of authentication in the access token that the authentication server enforced prior to returning the authorization response to the client. Their values are fixed and remain the same across all access tokens that derive from a given authorization response, whether the access token was obtained directly in the response (e.g., via the implicit flow) or after one or more token exchanges (e.g., obtaining a fresh access token using a refresh token or exchanging one access token for another via [RFC8693] procedures).

本節に挙げるクレームは、リソースオーナーが関与する認可グラントの文脈で発行してもよく (MAY)、認証サーバーがクライアントに認可レスポンスを返す前に実施した認証の種類と強度をアクセストークンの中に反映する。これらの値は固定であり、アクセストークンがレスポンス内で直接取得されたか (例: インプリシットフロー経由)、1 回以上のトークン交換の後に取得されたか (例: リフレッシュトークンを用いて新しいアクセストークンを取得する、あるいは [RFC8693] の手順であるアクセストークンを別のアクセストークンと交換する) にかかわらず、ある認可レスポンスから派生するすべてのアクセストークンにわたって同じままである。

auth_time OPTIONAL - as defined in Section 2 of [OpenID.Core].

auth_time OPTIONAL - [OpenID.Core] の 2 節で定義されるとおり。

acr OPTIONAL - as defined in Section 2 of [OpenID.Core].

acr OPTIONAL - [OpenID.Core] の 2 節で定義されるとおり。

amr OPTIONAL - as defined in Section 2 of [OpenID.Core].

amr OPTIONAL - [OpenID.Core] の 2 節で定義されるとおり。

2.2.2.Identity Claims

2.2.2.アイデンティティクレーム

In the context of authorization grants involving the resource owner, commercial authorization servers will often include resource owner attributes directly in access tokens so that resource servers can consume them directly for authorization or other purposes without any further round trips to introspection ([RFC7662]) or UserInfo ([OpenID.Core]) endpoints. This is particularly common in scenarios where the client and the resource server belong to the same entity and are part of the same solution, as is the case for first-party clients invoking their own backend API.

リソースオーナーが関与する認可グラントの文脈では、商用の認可サーバーはしばしばリソースオーナーの属性をアクセストークンに直接含め、リソースサーバーがイントロスペクション ([RFC7662]) や UserInfo ([OpenID.Core]) エンドポイントへのさらなるラウンドトリップなしに、認可やその他の目的のためにそれらを直接消費できるようにしている。これは、ファーストパーティのクライアントが自身のバックエンド API を呼び出す場合のように、クライアントとリソースサーバーが同じ主体に属し、同じソリューションの一部であるシナリオで特によく見られる。

This profile does not introduce any mechanism for a client to directly request the presence of specific claims in JWT access tokens, as the authorization server can determine what additional claims are required by a particular resource server by taking the client_id of the client and the "scope" and the "resource" parameters included in the request into consideration.

本プロファイルは、クライアントが JWT アクセストークンに特定のクレームの存在を直接要求するための仕組みを導入しない。認可サーバーは、クライアントの client_id と、リクエストに含まれる "scope" および "resource" パラメーターを考慮することで、特定のリソースサーバーがどの追加クレームを必要とするかを判断できるためである。

Any additional identity attribute whose semantic is well described by an entry in the "JSON Web Token (JWT)" IANA registry introduced in [RFC7519] SHOULD be encoded using the corresponding claim name, if that attribute is to be included in the JWT access token. Note that the JWT IANA registry includes the claims found in Section 5.1 of [OpenID.Core].

[RFC7519] で導入された "JSON Web Token (JWT)" IANA レジストリのエントリによってその意味がよく記述されている追加のアイデンティティ属性は、その属性を JWT アクセストークンに含める場合、対応するクレーム名を用いてエンコードすべきである (SHOULD)。JWT IANA レジストリには [OpenID.Core] の 5.1 節にあるクレームが含まれていることに注意すること。

Authorization servers MAY return arbitrary attributes not defined in any existing specification, as long as the corresponding claim names are collision resistant or the access tokens are meant to be used only within a private subsystem. Please refer to Sections 4.2 and 4.3 of [RFC7519] for details.

認可サーバーは、対応するクレーム名が衝突耐性を持つか、またはそのアクセストークンが私的なサブシステム内でのみ使用されることを意図している限り、既存のどの仕様でも定義されていない任意の属性を返してもよい (MAY)。詳細は [RFC7519] の 4.2 節および 4.3 節を参照のこと。

Authorization servers including resource owner attributes in JWT access tokens need to exercise care and verify that all privacy requirements are met, as discussed in Section 6.

JWT アクセストークンにリソースオーナーの属性を含める認可サーバーは、6 節で論じるように、注意を払い、すべてのプライバシー要件が満たされていることを確認する必要がある。

2.2.3.Authorization Claims

2.2.3.認可クレーム

If an authorization request includes a scope parameter, the corresponding issued JWT access token SHOULD include a "scope" claim as defined in Section 4.2 of [RFC8693].

認可リクエストに scope パラメーターが含まれる場合、それに対応して発行される JWT アクセストークンは、[RFC8693] の 4.2 節で定義される "scope" クレームを含むべきである (SHOULD)。

All the individual scope strings in the "scope" claim MUST have meaning for the resources indicated in the "aud" claim. See Section 5 for more considerations about the relationship between scope strings and resources indicated by the "aud" claim.

"scope" クレーム内の個々のスコープ文字列はすべて、"aud" クレームで示されるリソースに対して意味を持たなければならない (MUST)。スコープ文字列と "aud" クレームで示されるリソースの関係についてのさらなる考慮事項は 5 節を参照のこと。

2.2.3.1.Claims for Authorization Outside of Delegation Scenarios

2.2.3.1.委譲シナリオ以外の認可のためのクレーム

Many authorization servers embed authorization attributes that go beyond the delegated scenarios described by [RFC7519] in the access tokens they issue. Typical examples include resource owner memberships in roles and groups that are relevant to the resource being accessed, entitlements assigned to the resource owner for the targeted resource that the authorization server knows about, and so on.

多くの認可サーバーは、[RFC7519] に記述される委譲シナリオを超える認可属性を、発行するアクセストークンに埋め込んでいる。典型的な例としては、アクセス対象のリソースに関連するロールやグループへのリソースオーナーの所属、対象リソースについて認可サーバーが把握しているリソースオーナーに割り当てられた権利 (entitlement) などがある。

An authorization server wanting to include such attributes in a JWT access token SHOULD use the "groups", "roles", and "entitlements" attributes of the "User" resource schema defined by Section 4.1.2 of [RFC7643]) as claim types.

そのような属性を JWT アクセストークンに含めたい認可サーバーは、[RFC7643] の 4.1.2 節で定義される "User" リソーススキーマの "groups"、"roles"、"entitlements" 属性をクレームタイプとして使用すべきである (SHOULD)。

Authorization servers SHOULD encode the corresponding claim values according to the guidance defined in [RFC7643]. In particular, a non-normative example of a "groups" attribute can be found in Section 8.2 of [RFC7643]. No specific vocabulary is provided for "roles" and "entitlements".

認可サーバーは、対応するクレーム値を [RFC7643] で定義される指針に従ってエンコードすべきである (SHOULD)。特に、"groups" 属性の非規範的な例は [RFC7643] の 8.2 節にある。"roles" および "entitlements" については特定の語彙は提供されていない。

Section 7.2.1 of this document provides entries for registering "groups", "roles", and "entitlements" attributes from [RFC7643] as claim types to be used in this profile.

本書の 7.2.1 節は、[RFC7643] の "groups"、"roles"、"entitlements" 属性を本プロファイルで使用するクレームタイプとして登録するためのエントリを提供する。

3.Requesting a JWT Access Token

3.JWT アクセストークンの要求

An authorization server can issue a JWT access token in response to any authorization grant defined by [RFC6749] and subsequent extensions meant to result in an access token.

認可サーバーは、[RFC6749] で定義される任意の認可グラント、およびアクセストークンの発行をもたらすことを意図したその後続の拡張に応答して、JWT アクセストークンを発行できる。

If the request includes a "resource" parameter (as defined in [RFC8707]), the resulting JWT access token "aud" claim SHOULD have the same value as the "resource" parameter in the request.

リクエストに "resource" パラメーター ([RFC8707] で定義) が含まれる場合、結果として得られる JWT アクセストークンの "aud" クレームは、リクエストの "resource" パラメーターと同じ値を持つべきである (SHOULD)。

Example request below:

以下にリクエストの例を示す:

Once redeemed, the code obtained from the request above will result in a JWT access token in the form shown below:

上記のリクエストで取得したコードを引き換えると、以下に示す形の JWT アクセストークンが得られる:

Header:

ヘッダー:

Claims:

クレーム:

The authorization server MUST NOT issue a JWT access token if the authorization granted by the token would be ambiguous. See Section 5 for more details about common cases that might lead to ambiguity and strategies an authorization server can enact to prevent them.

認可サーバーは、トークンによって付与される認可が曖昧になる場合には JWT アクセストークンを発行してはならない (MUST NOT)。曖昧さにつながり得る一般的なケースと、認可サーバーがそれを防ぐために講じることのできる戦略の詳細については 5 節を参照のこと。

If the request does not include a "resource" parameter, the authorization server MUST use a default resource indicator in the "aud" claim. If a "scope" parameter is present in the request, the authorization server SHOULD use it to infer the value of the default resource indicator to be used in the "aud" claim. The mechanism through which scopes are associated with default resource indicator values is outside the scope of this specification. If the values in the "scope" parameter refer to different default resource indicator values, the authorization server SHOULD reject the request with "invalid_scope" as described in Section 4.1.2.1 of [RFC6749].

リクエストに "resource" パラメーターが含まれない場合、認可サーバーは "aud" クレームにデフォルトのリソースインジケーターを使用しなければならない (MUST)。リクエストに "scope" パラメーターが存在する場合、認可サーバーはそれを用いて "aud" クレームに使用するデフォルトのリソースインジケーターの値を推定すべきである (SHOULD)。スコープをデフォルトのリソースインジケーターの値に関連付ける仕組みは本仕様の範囲外である。"scope" パラメーターの値が異なるデフォルトのリソースインジケーター値を参照する場合、認可サーバーは [RFC6749] の 4.1.2.1 節に記述されるとおり "invalid_scope" でリクエストを拒否すべきである (SHOULD)。

4.Validating JWT Access Tokens

4.JWT アクセストークンの検証

For the purpose of facilitating validation data retrieval, it is RECOMMENDED here that authorization servers sign JWT access tokens with an asymmetric algorithm.

検証データの取得を容易にするため、ここでは認可サーバーが JWT アクセストークンを非対称アルゴリズムで署名することを推奨する (RECOMMENDED)。

Authorization servers SHOULD use OAuth 2.0 Authorization Server Metadata [RFC8414] to advertise to resource servers their signing keys via "jwks_uri" and what "iss" claim value to expect via the "issuer" metadata value. Alternatively, authorization servers implementing OpenID Connect MAY use the OpenID Connect discovery [OpenID.Discovery] document for the same purpose. If an authorization server supports both OAuth 2.0 Authorization Server Metadata and OpenID Connect discovery, the values provided MUST be consistent across the two publication methods.

認可サーバーは、OAuth 2.0 認可サーバーメタデータ [RFC8414] を用いて、署名鍵を "jwks_uri" で、期待すべき "iss" クレームの値を "issuer" メタデータ値でリソースサーバーに通知すべきである (SHOULD)。あるいは、OpenID Connect を実装する認可サーバーは、同じ目的で OpenID Connect ディスカバリー [OpenID.Discovery] ドキュメントを使用してもよい (MAY)。認可サーバーが OAuth 2.0 認可サーバーメタデータと OpenID Connect ディスカバリーの両方をサポートする場合、提供される値は 2 つの公開方法の間で一貫していなければならない (MUST)。

An authorization server MAY elect to use different keys to sign OpenID Connect ID Tokens and JWT access tokens. This specification does not provide a mechanism for identifying a specific key as the one used to sign JWT access tokens. An authorization server can sign JWT access tokens with any of the keys advertised via authorization server (AS) metadata or OpenID Connect discovery. See Section 5 for further guidance on security implications.

認可サーバーは、OpenID Connect ID トークンと JWT アクセストークンの署名に異なる鍵を使用することを選択してもよい (MAY)。本仕様は、JWT アクセストークンの署名に使用される鍵として特定の鍵を識別する仕組みを提供しない。認可サーバーは、認可サーバー (AS) メタデータまたは OpenID Connect ディスカバリーを通じて公開した鍵のいずれでも JWT アクセストークンに署名できる。セキュリティ上の影響に関するさらなる指針は 5 節を参照のこと。

Resource servers receiving a JWT access token MUST validate it in the following manner.

JWT アクセストークンを受け取るリソースサーバーは、以下の方法でそれを検証しなければならない (MUST)。

* The resource server MUST verify that the "typ" header value is "at+jwt" or "application/at+jwt" and reject tokens carrying any other value.

* リソースサーバーは、"typ" ヘッダーの値が "at+jwt" または "application/at+jwt" であることを確認し、それ以外の値を持つトークンを拒否しなければならない (MUST)。

* If the JWT access token is encrypted, decrypt it using the keys and algorithms that the resource server specified during registration. If encryption was negotiated with the authorization server at registration time and the incoming JWT access token is not encrypted, the resource server SHOULD reject it.

* JWT アクセストークンが暗号化されている場合、リソースサーバーが登録時に指定した鍵とアルゴリズムを用いて復号する。登録時に認可サーバーと暗号化を取り決めたにもかかわらず受信した JWT アクセストークンが暗号化されていない場合、リソースサーバーはそれを拒否すべきである (SHOULD)。

* The issuer identifier for the authorization server (which is typically obtained during discovery) MUST exactly match the value of the "iss" claim.

* 認可サーバーの発行者識別子 (通常はディスカバリー時に取得する) は、"iss" クレームの値と完全に一致しなければならない (MUST)。

* The resource server MUST validate that the "aud" claim contains a resource indicator value corresponding to an identifier the resource server expects for itself. The JWT access token MUST be rejected if "aud" does not contain a resource indicator of the current resource server as a valid audience.

* リソースサーバーは、"aud" クレームがリソースサーバー自身を表すものとして期待する識別子に対応するリソースインジケーター値を含んでいることを検証しなければならない (MUST)。"aud" が現在のリソースサーバーのリソースインジケーターを有効なオーディエンスとして含んでいない場合、JWT アクセストークンは拒否されなければならない (MUST)。

* The resource server MUST validate the signature of all incoming JWT access tokens according to [RFC7515] using the algorithm specified in the JWT "alg" Header Parameter. The resource server MUST reject any JWT in which the value of "alg" is "none". The resource server MUST use the keys provided by the authorization server.

* リソースサーバーは、受信したすべての JWT アクセストークンの署名を、JWT の "alg" ヘッダーパラメーターで指定されたアルゴリズムを用いて [RFC7515] に従って検証しなければならない (MUST)。リソースサーバーは、"alg" の値が "none" である JWT をすべて拒否しなければならない (MUST)。リソースサーバーは認可サーバーが提供した鍵を使用しなければならない (MUST)。

* The current time MUST be before the time represented by the "exp" claim. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew.

* 現在時刻は "exp" クレームが表す時刻より前でなければならない (MUST)。実装者はクロックスキューを考慮して、通常は数分を超えない程度の小さな猶予を設けてもよい (MAY)。

The resource server MUST handle errors as described in Section 3.1 of [RFC6750]. In particular, in case of any failure in the validation checks listed above, the authorization server response MUST include the error code "invalid_token". Please note that this requirement does not prevent JWT access tokens from using authentication schemes other than "Bearer".

リソースサーバーは、[RFC6750] の 3.1 節に記述されるとおりにエラーを処理しなければならない (MUST)。特に、上記の検証チェックのいずれかに失敗した場合、認可サーバーのレスポンスはエラーコード "invalid_token" を含まなければならない (MUST)。この要件は、JWT アクセストークンが "Bearer" 以外の認証スキームを使用することを妨げるものではないことに注意すること。

If the JWT access token includes authorization claims as described in Section 2.2.3, the resource server SHOULD use them in combination with any other contextual information available to determine whether the current call should be authorized or rejected. Details about how a resource server performs those checks is beyond the scope of this profile specification.

JWT アクセストークンが 2.2.3 節に記述される認可クレームを含む場合、リソースサーバーは、利用可能な他のあらゆるコンテキスト情報と組み合わせてそれらを用い、現在の呼び出しを認可すべきか拒否すべきかを判断すべきである (SHOULD)。リソースサーバーがそれらのチェックをどのように行うかの詳細は、本プロファイル仕様の範囲外である。

5.Security Considerations

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

The JWT access token data layout described here is very similar to that of the id_token as defined by [OpenID.Core]. The explicit typing required in this profile, in line with the recommendations in [RFC8725], helps the resource server to distinguish between JWT access tokens and OpenID Connect ID Tokens.

ここに記述する JWT アクセストークンのデータレイアウトは、[OpenID.Core] で定義される id_token のものと非常によく似ている。本プロファイルで要求される明示的な型付けは、[RFC8725] の推奨に沿ったものであり、リソースサーバーが JWT アクセストークンと OpenID Connect ID トークンを区別するのに役立つ。

Authorization servers should prevent scenarios where clients can affect the value of the "sub" claim in ways that could confuse resource servers. For example, if the authorization server elects to use the client_id as the "sub" value for access tokens issued using the client credentials grant, the authorization server should prevent clients from registering an arbitrary client_id value, as this would allow malicious clients to select the sub of a high-privilege resource owner and confuse any authorization logic on the resource server relying on the "sub" value. For more details, please refer to Section 4.14 of [OAuth2.Security.BestPractices].

認可サーバーは、クライアントがリソースサーバーを混乱させるような形で "sub" クレームの値に影響を与えられるシナリオを防ぐべきである。たとえば、認可サーバーがクライアントクレデンシャルグラントで発行するアクセストークンの "sub" 値として client_id を使用することを選択する場合、認可サーバーはクライアントが任意の client_id 値を登録できないようにすべきである。さもなければ、悪意のあるクライアントが高い権限を持つリソースオーナーの sub を選択でき、"sub" 値に依存するリソースサーバー上のあらゆる認可ロジックを混乱させることができてしまう。詳細は [OAuth2.Security.BestPractices] の 4.14 節を参照のこと。

To prevent cross-JWT confusion, authorization servers MUST use a distinct identifier as an "aud" claim value to uniquely identify access tokens issued by the same issuer for distinct resources. For more details on cross-JWT confusion, please refer to Section 2.8 of [RFC8725].

JWT 間の混同 (cross-JWT confusion) を防ぐため、認可サーバーは、同じ発行者が異なるリソース向けに発行するアクセストークンを一意に識別するために、"aud" クレームの値として異なる識別子を使用しなければならない (MUST)。JWT 間の混同の詳細については [RFC8725] の 2.8 節を参照のこと。

Authorization servers should use particular care when handling requests that might lead to ambiguous authorization grants. For example, if a request includes multiple resource indicators, the authorization server should ensure that each scope string included in the resulting JWT access token, if any, can be unambiguously correlated to a specific resource among the ones listed in the "aud" claim. The details on how to recognize and mitigate this and other ambiguous situations is highly scenario dependent and hence is out of scope for this profile.

認可サーバーは、曖昧な認可グラントにつながり得るリクエストを処理する際には特に注意を払うべきである。たとえば、リクエストに複数のリソースインジケーターが含まれる場合、認可サーバーは、結果として得られる JWT アクセストークンに含まれる各スコープ文字列 (もしあれば) が、"aud" クレームに列挙されたリソースのうちの特定の 1 つに曖昧さなく対応付けられることを保証すべきである。これやその他の曖昧な状況をどのように認識し緩和するかの詳細はシナリオに大きく依存するため、本プロファイルの範囲外である。

Authorization servers cannot rely on the use of different keys for signing OpenID Connect ID Tokens and JWT tokens as a method to safeguard against the consequences of leaking specific keys. Given that resource servers have no way of knowing what key should be used to validate JWT access tokens in particular, they have to accept signatures performed with any of the keys published in AS metadata or OpenID Connect discovery; consequently, an attacker just needs to compromise any key among the ones published to be able to generate and sign JWTs that will be accepted as valid by the resource server.

認可サーバーは、特定の鍵の漏洩の影響を防ぐ方法として、OpenID Connect ID トークンと JWT トークンの署名に異なる鍵を使用することに頼ることはできない。リソースサーバーには特に JWT アクセストークンの検証にどの鍵を使うべきかを知る方法がないため、AS メタデータまたは OpenID Connect ディスカバリーで公開されている鍵のいずれかで行われた署名を受け入れなければならない。その結果、攻撃者は公開されている鍵のうちいずれか 1 つを侵害するだけで、リソースサーバーに有効として受け入れられる JWT を生成し署名できるようになる。

6.Privacy Considerations

6.プライバシーに関する考慮事項

As JWT access tokens carry information by value, it now becomes possible for clients and potentially even end users to directly peek inside the token claims collection of unencrypted tokens.

JWT アクセストークンは情報を値として保持するため、クライアント、さらには場合によってはエンドユーザーまでもが、暗号化されていないトークンのクレーム集合の中身を直接覗き見ることが可能になる。

The client MUST NOT inspect the content of the access token: the authorization server and the resource server might decide to change the token format at any time (for example, by switching from this profile to opaque tokens); hence, any logic in the client relying on the ability to read the access token content would break without recourse. The OAuth 2.0 framework assumes that access tokens are treated as opaque by clients. Administrators of authorization servers should also take into account that the content of an access token is visible to the client. Whenever client access to the access token content presents privacy issues for a given scenario, the authorization server needs to take explicit steps to prevent them.

クライアントはアクセストークンの内容を検査してはならない (MUST NOT)。認可サーバーとリソースサーバーはいつでもトークン形式を変更する (たとえば本プロファイルから不透明トークンに切り替える) と決めるかもしれず、したがって、アクセストークンの内容を読めることに依存するクライアント内のあらゆるロジックは、救済の余地なく壊れることになる。OAuth 2.0 フレームワークは、アクセストークンがクライアントによって不透明なものとして扱われることを前提としている。認可サーバーの管理者もまた、アクセストークンの内容がクライアントに見えることを考慮に入れるべきである。クライアントがアクセストークンの内容にアクセスできることが、あるシナリオにおいてプライバシー上の問題をもたらす場合には常に、認可サーバーはそれを防ぐための明示的な措置を講じる必要がある。

In scenarios in which JWT access tokens are accessible to the end user, it should be evaluated whether the information can be accessed without privacy violations (for example, if an end user would simply access his or her own personal information) or if steps must be taken to enforce confidentiality.

JWT アクセストークンがエンドユーザーからアクセス可能なシナリオでは、その情報にプライバシー侵害なしにアクセスできるのか (たとえば、エンドユーザーが単に自分自身の個人情報にアクセスするだけの場合)、それとも機密性を確保するための措置を講じなければならないのかを評価すべきである。

Possible measures to prevent leakage of information to clients and end users include: encrypting the access token, encrypting the sensitive claims, omitting the sensitive claims or not using this profile, and falling back on opaque access tokens.

クライアントやエンドユーザーへの情報漏洩を防ぐために考えられる措置には、アクセストークンの暗号化、機微なクレームの暗号化、機微なクレームの省略または本プロファイルの不使用、そして不透明なアクセストークンへのフォールバックが含まれる。

In every scenario, the content of the JWT access token will eventually be accessible to the resource server. It's important to evaluate whether the resource server gained the proper entitlement to have access to any content received in the form of claims, for example, through user consent in some form, policies and agreements with the organization running the authorization servers, and so on. For example, a user might not wish to consent to granting given resource server information about any of the non-mandatory claims enumerated in Section 2 (and its subsections).

あらゆるシナリオにおいて、JWT アクセストークンの内容は最終的にリソースサーバーからアクセス可能となる。リソースサーバーが、クレームの形で受け取るあらゆる内容にアクセスするための適切な権利を、たとえば何らかの形でのユーザーの同意、認可サーバーを運用する組織とのポリシーや合意などを通じて獲得しているかどうかを評価することが重要である。たとえば、ユーザーは、2 節 (およびその下位節) に列挙された必須でないクレームのいずれかに関する情報を特定のリソースサーバーに与えることに同意したくないかもしれない。

This profile mandates the presence of the "sub" claim in every JWT access token, making it possible for resource servers to rely on that information for correlating incoming requests with data stored locally for the authenticated principal. Although the ability to correlate requests might be required by design in many scenarios, there are scenarios where the authorization server might want to prevent correlation. The "sub" claim should be populated by the authorization servers according to a privacy impact assessment. For instance, if a solution requires preventing tracking of principal activities across multiple resource servers, the authorization server should ensure that JWT access tokens meant for different resource servers have distinct "sub" values that cannot be correlated in the event of resource server collusion. Similarly, if a solution requires preventing a resource server from correlating the principal's activity within the resource itself, the authorization server should assign different "sub" values for every JWT access token issued. In turn, the client should obtain a new JWT access token for every call to the resource server to ensure that the resource server receives different "sub" and "jti" values at every call, thus preventing correlation between distinct requests.

本プロファイルはすべての JWT アクセストークンに "sub" クレームの存在を義務付けており、リソースサーバーがその情報に依拠して、受信したリクエストを認証済みプリンシパルについてローカルに保存されたデータと相関させることを可能にしている。リクエストを相関させる能力は多くのシナリオで設計上必要とされるかもしれないが、認可サーバーが相関を防ぎたいシナリオも存在する。"sub" クレームは、プライバシー影響評価に従って認可サーバーが設定すべきである。たとえば、あるソリューションが複数のリソースサーバーにまたがるプリンシパルの活動の追跡を防ぐことを要求する場合、認可サーバーは、異なるリソースサーバー向けの JWT アクセストークンが、リソースサーバーが共謀した場合でも相関できない異なる "sub" 値を持つことを保証すべきである。同様に、あるソリューションがリソースサーバーによるそのリソース内でのプリンシパルの活動の相関を防ぐことを要求する場合、認可サーバーは発行するすべての JWT アクセストークンに異なる "sub" 値を割り当てるべきである。それに応じて、クライアントはリソースサーバーへの呼び出しごとに新しい JWT アクセストークンを取得し、リソースサーバーが呼び出しごとに異なる "sub" および "jti" 値を受け取るようにして、個別のリクエスト間の相関を防ぐべきである。

7.IANA Considerations

7.IANA に関する考慮事項

7.1.Media Type Registration

7.1.メディアタイプの登録

7.1.1.Registry Content

7.1.1.レジストリの内容

This section registers "application/at+jwt", a new media type [RFC2046] in the "Media Types" registry [IANA.MediaTypes] in the manner described in [RFC6838]. It can be used to indicate that the content is an access token encoded in JWT format.

本節は、[RFC6838] に記述される方法で、新しいメディアタイプ [RFC2046] "application/at+jwt" を "Media Types" レジストリ [IANA.MediaTypes] に登録する。これは、内容が JWT 形式でエンコードされたアクセストークンであることを示すために使用できる。

Type name: Application

Type name: Application

Subtype name: at+jwt

Subtype name: at+jwt

Required parameters: N/A

Required parameters: N/A

Optional parameters: N/A

Optional parameters: N/A

Encoding considerations: Binary; JWT values are encoded as a series of base64url-encoded values (with trailing '=' characters removed), some of which may be the empty string, separated by period ('.') characters.

Encoding considerations: バイナリ。JWT の値は、ピリオド ('.') 文字で区切られた一連の base64url エンコード値 (末尾の '=' 文字は除去される) としてエンコードされ、そのうちのいくつかは空文字列であってもよい。

Security considerations: See the Security Considerations section of RFC 9068.

Security considerations: RFC 9068 のセキュリティに関する考慮事項の節を参照のこと。

Interoperability considerations: N/A

Interoperability considerations: N/A

Published specification: RFC 9068

Published specification: RFC 9068

Applications that use this media type: Applications that access resource servers using OAuth 2.0 access tokens encoded in JWT format

Applications that use this media type: JWT 形式でエンコードされた OAuth 2.0 アクセストークンを用いてリソースサーバーにアクセスするアプリケーション

Fragment identifier considerations: N/A

Fragment identifier considerations: N/A

Additional information:

Additional information:

Person & email address to contact for further information: Vittorio Bertocci <vittorio@auth0.com>

Person & email address to contact for further information: Vittorio Bertocci <vittorio@auth0.com>

Intended usage: COMMON

Intended usage: COMMON

Restrictions on usage: None

Restrictions on usage: None

Author: Vittorio Bertocci <vittorio@auth0.com>

Author: Vittorio Bertocci <vittorio@auth0.com>

Change controller: IETF

Change controller: IETF

Provisional registration? No

Provisional registration? No

7.2.Claims Registration

7.2.クレームの登録

Section 2.2.3.1 of this specification refers to the attributes "roles", "groups", "entitlements" defined in [RFC7643] to express authorization information in JWT access tokens. This section registers those attributes as claims in the "JSON Web Token (JWT)" IANA registry introduced in [RFC7519].

本仕様の 2.2.3.1 節は、JWT アクセストークンで認可情報を表現するために、[RFC7643] で定義される属性 "roles"、"groups"、"entitlements" を参照している。本節は、これらの属性を [RFC7519] で導入された "JSON Web Token (JWT)" IANA レジストリにクレームとして登録する。

7.2.1.Registry Content

7.2.1.レジストリの内容

7.2.1.1.Roles

7.2.1.1.Roles

Claim Name: roles Claim Description: Roles Change Controller: IETF Specification Document(s): Section 4.1.2 of [RFC7643] and Section 2.2.3.1 of RFC 9068

Claim Name: roles Claim Description: Roles Change Controller: IETF Specification Document(s): [RFC7643] の 4.1.2 節および RFC 9068 の 2.2.3.1 節

7.2.1.2.Groups

7.2.1.2.Groups

Claim Name: groups Claim Description: Groups Change Controller: IETF Specification Document(s): Section 4.1.2 of [RFC7643] and Section 2.2.3.1 of RFC 9068

Claim Name: groups Claim Description: Groups Change Controller: IETF Specification Document(s): [RFC7643] の 4.1.2 節および RFC 9068 の 2.2.3.1 節

7.2.1.3.Entitlements

7.2.1.3.Entitlements

Claim Name: entitlements Claim Description: Entitlements Change Controller: IETF Specification Document(s): Section 4.1.2 of [RFC7643] and Section 2.2.3.1 of RFC 9068

Claim Name: entitlements Claim Description: Entitlements Change Controller: IETF Specification Document(s): [RFC7643] の 4.1.2 節および RFC 9068 の 2.2.3.1 節

8.References

8.参考資料

8.1.Normative References

8.1.引用規格

8.2.Informative References

8.2.参考文献

Acknowledgements

謝辞

The initial set of requirements informing this specification was extracted by numerous examples of access tokens issued in JWT format by production systems. Thanks to Dominick Baier (IdentityServer), Brian Campbell (Ping Identity), Daniel Dobalian (Microsoft), and Karl Guinness (Okta) for providing sample tokens issued by their products and services. Brian Campbell and Filip Skokan provided early feedback that shaped the direction of the specification. This profile was discussed at length during the OAuth Security Workshop 2019, with several individuals contributing ideas and feedback. The author would like to acknowledge the contributions of:

本仕様の基礎となった最初の要件群は、本番システムが JWT 形式で発行する多数のアクセストークンの例から抽出された。各社の製品やサービスが発行するサンプルトークンを提供してくれた Dominick Baier (IdentityServer)、Brian Campbell (Ping Identity)、Daniel Dobalian (Microsoft)、Karl Guinness (Okta) に感謝する。Brian Campbell と Filip Skokan は、本仕様の方向性を形作る初期のフィードバックを提供してくれた。本プロファイルは OAuth Security Workshop 2019 で長時間にわたって議論され、多くの人がアイデアとフィードバックを寄せてくれた。著者は以下の方々の貢献に謝意を表する:

John Bradley, Brian Campbell, Vladimir Dzhuvinov, Torsten Lodderstedt, Nat Sakimura, Hannes Tschofenig, and everyone who actively participated in the unconference discussions.

John Bradley、Brian Campbell、Vladimir Dzhuvinov、Torsten Lodderstedt、Nat Sakimura、Hannes Tschofenig、そしてアンカンファレンスの議論に積極的に参加したすべての方々。

The following individuals contributed useful feedback and insights on the drafts, both at the IETF OAuth 2.0 WG mailing list and during the 28th Internet Identity Workshop (IIW 28):

以下の方々は、IETF OAuth 2.0 WG のメーリングリストおよび第 28 回 Internet Identity Workshop (IIW 28) において、ドラフトに対する有益なフィードバックと洞察を寄せてくれた:

Dale Olds, George Fletcher, David Waite, Michael Engan, Mike Jones, Hans Zandbelt, Vladimir Dzhuvinov, Martin Schanzenbach, Aaron Parecki, Annabelle Richard Backman, Dick Hardt, Denis Pinkas, Benjamin Kaduk, Dominick Baier, Andrii Deinega, Mike Jones, and everyone who actively participated in the IIW 28 unconference discussions and the IETF OAuth 2.0 WG mailing list discussions. Thanks to Roman Danyliw for the AD review; Joseph Salowey and Roni Even for the SECDIR and GENART reviews; and Francesca Palomini, Lars Eggert, Murray Kucherawy, Roberto Polli, Martin Duke, Benjamin Kaduk for the IESG reviews.

Dale Olds、George Fletcher、David Waite、Michael Engan、Mike Jones、Hans Zandbelt、Vladimir Dzhuvinov、Martin Schanzenbach、Aaron Parecki、Annabelle Richard Backman、Dick Hardt、Denis Pinkas、Benjamin Kaduk、Dominick Baier、Andrii Deinega、Mike Jones、そして IIW 28 のアンカンファレンスの議論および IETF OAuth 2.0 WG メーリングリストの議論に積極的に参加したすべての方々。AD レビューを行った Roman Danyliw、SECDIR および GENART レビューを行った Joseph Salowey と Roni Even、IESG レビューを行った Francesca Palomini、Lars Eggert、Murray Kucherawy、Roberto Polli、Martin Duke、Benjamin Kaduk に感謝する。