Skip to content

JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants

Internet Engineering Task Force (IETF)                          M. Jones
Request for Comments: 7523                                     Microsoft
Category: Standards Track                                    B. Campbell
ISSN: 2070-1721                                            Ping Identity
                                                            C. Mortimore
                                                              Salesforce
                                                                May 2015

Abstract

本仕様は、OAuth 2.0のaccess tokenを要求する手段として、ならびにclient authenticationのために、JSON Web Token (JWT) Bearer Tokenを使用する方法を定義する。

Status of This Memo

本文書はInternet Standards Track文書である。

本文書はInternet Engineering Task Force (IETF) の成果物である。IETFコミュニティの合意を反映している。公開レビューを受け、Internet Engineering Steering Group (IESG) により公開が承認された。Internet Standardsに関する追加情報は、RFC 5741のSection 2に示されている。

本文書の現状、正誤表、フィードバックの提供方法については、以下から入手できる。\ http://www.rfc-editor.org/info/rfc7523

Copyright (c) 2015 IETF Trust および本文書の著者として特定された者。All rights reserved.

本文書は、公開日時点で有効なBCP 78およびIETF Trustの「IETF文書に関する法的規定」(http://trustee.ietf.org/license-info) の対象となる。これらの文書には、本文書に関する権利および制限が記載されているため、注意深く確認すること。本文書から抽出されたCode Componentsには、Trust Legal ProvisionsのSection 4.eで述べられているSimplified BSD Licenseの文言を含めなければならず、またSimplified BSD Licenseに記載のとおり、無保証で提供される。

Table of Contents

1. Introduction

JSON Web Token (JWT) [JWT] は、IDおよびセキュリティ情報をセキュリティドメイン間で共有できるようにする、JSONベースの [RFC7159] セキュリティトークンのエンコーディングである。セキュリティトークンは一般にIdentity Providerが発行し、その内容に基づいてセキュリティ関連の目的でトークンのsubjectを特定するために、Relying Partyがそれを利用する。

OAuth 2.0 Authorization Framework [RFC6749] は、access tokenを用いてリソースに対し認証済みのHTTPリクエストを行う方法を提供する。Access Tokenは、Resource Ownerの（しばしば暗黙的な）承認を得たうえで、authorization server (AS) によりサードパーティのクライアントへ発行される。OAuthにおいてauthorization grantとは、Resource Ownerの認可を表す中間的な資格情報を指す抽象的な用語である。authorization grantは、クライアントがAccess Tokenを取得するために使用される。幅広いclientの種類とユーザー体験を支えるため、複数のauthorization grant typeが定義されている。さらにOAuthでは、追加のクライアントを支援したり、OAuthと他の信頼フレームワークとの橋渡しを提供したりするために、新たな拡張grant typeを定義することができる。最後に、authorization serverとやり取りする際にクライアントが使用できる追加の認証メカニズムの定義も許容している。

「Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants」[RFC7521] は、OAuth 2.0に対する抽象的な拡張であり、OAuth 2.0においてassertion（別名: セキュリティトークン）をclient credentialsおよび／またはauthorization grantsとして用いるための一般的な枠組みを提供する。本仕様は、OAuth Assertion Framework [RFC7521] をプロファイルし、JWT Bearer Tokenを用いてOAuth 2.0のaccess tokenを要求するための拡張grant typeを定義するとともに、client credentialsとしての使用も定義する。本仕様で定義されるJWTの形式および処理規則は、密接に関連する仕様である「Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants」[RFC7522] のものと意図的に似せているが、同一ではない。相違は、JWTの構造と意味論がSAML Assertionと異なる点に起因する。例えばJWTには、SAML Assertionの <SubjectConfirmation> 要素や <AuthnStatement> 要素に直接対応するものが存在しない。

本文書は、authorization serverでの直接的なユーザー承認手順を経ることなく、JWTの意味論によって表現される既存の信頼関係を利用したい場合に、JWT Bearer Tokenを用いてaccess tokenを要求する方法を定義する。また、JWTをclient authenticationのメカニズムとして使用する方法も定義する。client authenticationにセキュリティトークンを用いることは、セキュリティトークンをauthorization grantとして用いることとは直交しており、分離可能である。両者は組み合わせても、別々に用いてもよい。JWTを用いたclient authenticationは、クライアントがtoken endpointに対して認証するための代替手段に過ぎず、完全で意味のあるプロトコルリクエストを構成するためには、何らかのgrant typeと併用しなければならない。JWT authorization grantsは、client authenticationまたは識別情報の有無にかかわらず使用できる。JWT authorization grantと併せてclient authenticationが必要かどうか、またどの種類のclient authenticationをサポートするかは、authorization serverの裁量に基づくポリシー判断である。

authorization serverとの交換に先立ってクライアントがJWTを取得する手順、またはclient authenticationのためにJWTを使用する前提となる取得手順は、本仕様の対象外である。

1.1. Notational Conventions

本文書におけるキーワード "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", "OPTIONAL" は、RFC 2119 [RFC2119] に記載のとおりに解釈される。

特に注記がない限り、すべてのプロトコルパラメータ名および値は大文字・小文字を区別する。

1.2. Terminology

すべての用語は、以下の仕様で定義されるとおりである: 「The OAuth 2.0 Authorization Framework」[RFC6749]、OAuth Assertion Framework [RFC7521]、および「JSON Web Token (JWT)」[JWT]。

2. HTTP Parameter Bindings for Transporting Assertions

OAuth Assertion Framework [RFC7521] は、token endpointとのやり取りの間にassertion（別名: セキュリティトークン）を運搬するための汎用的なHTTPパラメータを定義している。本セクションでは、JWT Bearer Tokensで使用するための、特定のパラメータおよびそれらの取り扱いを定義する。

2.1. Using JWTs as Authorization Grants

Bearer JWTをauthorization grantとして使用するために、クライアントはOAuth Assertion Framework [RFC7521] のSection 4で定義されるaccess token requestを、以下の特定のパラメータ値およびエンコーディングで使用する。

  • "grant_type" の値は "urn:ietf:params:oauth:grant-type:jwt-bearer" とする。
  • "assertion" パラメータの値は、単一のJWTを含まなければならない (MUST)。
  • "scope" パラメータは、要求するscopeを示すために、OAuth Assertion Framework [RFC7521] で定義されているとおり使用してよい (MAY)。
  • クライアントの認証は任意であり、OAuth 2.0 [RFC6749] のSection 3.2.1で述べられているとおりである。したがって、"client_id" は、当該パラメータに依存する形式のclient authenticationを使用する場合にのみ必要となる。

以下の例は、JWTをauthorization grantとして用いるaccess token requestを示す（表示の都合上、余分な改行を含む）:

POST /token.oauth2 HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.
eyJpc3Mi[...omitted for brevity...].
J9l-ZhwP[...omitted for brevity...]

2.2. Using JWTs for Client Authentication

JWT Bearer Tokenをclient authenticationに使用するために、クライアントは以下のパラメータ値およびエンコーディングを用いる。

  • "client_assertion_type" の値は "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" とする。
  • "client_assertion" パラメータの値は、単一のJWTを含む。複数のJWTを含んではならない (MUST NOT)。

以下の例は、access token requestにおいてauthorization code grantを提示する際に、JWTを用いてclient authenticationを行う例を示す（表示の都合上、余分な改行を含む）:

POST /token.oauth2 HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4&
client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3A
client-assertion-type%3Ajwt-bearer&
client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0.
eyJpc3Mi[...omitted for brevity...].
cC4hiUPo[...omitted for brevity...]

3. JWT Format and Processing Requirements

OAuth 2.0 [RFC6749] で記述されるaccess token responseを発行するため、またはclient authenticationのためにJWTに依拠するために、authorization serverは以下の基準に従ってJWTを検証しなければならない (MUST)。追加の制約およびポリシーの適用は、authorization serverの裁量による。

  1. JWTは "iss" (issuer) claimを含まなければならず (MUST)、それにはJWTを発行したエンティティの一意な識別子を含める。別段の指定を行うアプリケーションプロファイルがない限り、準拠するアプリケーションは、RFC 3986 [RFC3986] のSection 6.2.1で定義されるSimple String Comparisonの方法でissuer値を比較しなければならない (MUST)。

  2. JWTは "sub" (subject) claimを含まなければならず (MUST)、JWTのsubjectとなるprincipalを識別する。2つのケースを区別する必要がある:

    • A. authorization grantの場合、subjectは通常、access tokenが要求される認可済みアクセス主体（すなわちResource Ownerまたは認可済みの委任先）を識別するが、場合によっては、仮名化された識別子、または匿名ユーザーを示すその他の値であることもある。
    • B. client authenticationの場合、subjectはOAuthクライアントの "client_id" でなければならない (MUST)。

  3. JWTは "aud" (audience) claimを含まなければならず (MUST)、authorization serverを意図されたaudienceとして識別する値を含める。authorization serverのtoken endpoint URLを、JWTの意図されたaudienceとしてauthorization serverを識別するための "aud" 要素の値として用いてもよい (MAY)。authorization serverは、意図されたaudienceとして自らの識別子を含まないJWTを拒否しなければならない (MUST)。別段の指定を行うアプリケーションプロファイルがない限り、準拠するアプリケーションは、RFC 3986 [RFC3986] のSection 6.2.1で定義されるSimple String Comparisonの方法でaudience値を比較しなければならない (MUST)。Section 5で注記するとおり、特定のauthorization serverに対してaudienceとして用いるべき正確な文字列は、authorization serverとJWTのissuerにより、帯域外で設定されなければならない。

  4. JWTは "exp" (expiration time) claimを含まなければならず (MUST)、JWTが使用できる期間の時間窓を制限する。authorization serverは、有効期限が過ぎたJWTを拒否しなければならない (MUST)。ただし、システム間の許容されるクロックスキューの範囲内であることを条件とする。なおauthorization serverは、"exp" の値が不合理に遠い未来であるJWTを拒否してよい (MAY)。

  5. JWTは "nbf" (not before) claimを含めてもよく (MAY)、その時刻より前にはトークンを処理として受理してはならない (MUST NOT) ことを示す。

  6. JWTは "iat" (issued at) claimを含めてもよく (MAY)、JWTが発行された時刻を示す。なおauthorization serverは、"iat" の値が不合理に遠い過去であるJWTを拒否してよい (MAY)。

  7. JWTは "jti" (JWT ID) claimを含めてもよく (MAY)、トークンの一意な識別子を提供する。authorization serverは、適用される "exp" の時刻に基づいてJWTが有効と見なされる期間にわたり、使用済みの "jti" 値の集合を保持することで、JWTがリプレイされないことを保証してもよい (MAY)。

  8. JWTはその他のclaimを含めてもよい (MAY)。

  9. JWTは発行者によりデジタル署名されているか、またはMessage Authentication Code (MAC) が適用されていなければならない (MUST)。authorization serverは、署名またはMACが無効なJWTを拒否しなければならない (MUST)。

  10. authorization serverは、「JSON Web Token (JWT)」[JWT] に従ってその他すべての点で有効ではないJWTを拒否しなければならない (MUST)。

3.1. Authorization Grant Processing

JWT authorization grantsは、client authenticationまたは識別情報の有無にかかわらず使用できる。JWT authorization grantと併せてclient authenticationが必要かどうか、またどの種類のclient authenticationをサポートするかは、authorization serverの裁量に基づくポリシー判断である。しかし、リクエストにclient credentialsが含まれている場合、authorization serverはそれらを検証しなければならない (MUST)。

JWTが有効でない場合、または現在時刻がトークンの使用に対する有効時間窓の範囲内にない場合、authorization serverはOAuth 2.0 [RFC6749] で定義されるerror responseを構築する。"error" パラメータの値は "invalid_grant" error codeでなければならない (MUST)。authorization serverは、JWTが無効と判断された理由に関する追加情報を、"error_description" または "error_uri" パラメータを用いて含めてもよい (MAY)。

例:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store

{
  "error": "invalid_grant",
  "error_description": "Audience validation failed"
}

3.2. Client Authentication Processing

クライアントのJWTが有効でない場合、authorization serverはOAuth 2.0 [RFC6749] で定義されるerror responseを構築する。"error" パラメータの値は "invalid_client" error codeでなければなら prohibited by (MUST)。authorization serverは、JWTが無効と判断された理由に関する追加情報を、"error_description" または "error_uri" パラメータを用いて含めてもよい (MAY)。

4. Authorization Grant Example

以下の例は、準拠するJWTとaccess token requestがどのようなものになるかを示す。

例では、"https://jwt-idp.example.com" として識別されるシステムエンティティにより発行され署名されたJWTを示す。JWTのsubjectはメールアドレス "mike@example.com" として識別される。JWTの意図されたaudienceは "https://jwt-rp.example.net" であり、これはauthorization serverが自らを識別するために用いる識別子である。JWTは、authorization serverのtoken endpointである "https://authz.example.net/token.oauth2" に対するaccess token requestの一部として送信される。

以下は、JWTのJWT Claims Setを生成するためにエンコードされ得るJSONオブジェクトの例である:

{
  "iss": "https://jwt-idp.example.com",
  "sub": "mailto:mike@example.com",
  "aud": "https://jwt-rp.example.net",
  "nbf": 1300815780,
  "exp": 1300819380,
  "http://claims.example.com/member": true
}

次の例のJSONオブジェクトは、JWTのheaderとして使用されるもので、JWTがElliptic Curve Digital Signature Algorithm (ECDSA) P-256 SHA-256で署名され、"kid" の値 "16" により識別される鍵を使用することを宣言している。

{
  "alg": "ES256",
  "kid": "16"
}

前の例で示したclaimsとheaderを持つJWTを、access token requestの一部として提示するために、例えばクライアントは次のHTTPSリクエストを行い得る（表示の都合上、余分な改行を含む）:

POST /token.oauth2 HTTP/1.1
Host: authz.example.net
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.
eyJpc3Mi[...omitted for brevity...].
J9l-ZhwP[...omitted for brevity...]

5. Interoperability Considerations

本プロファイルの相互運用可能な展開を実現するためには、識別子、鍵、endpointに関してシステムエンティティ間の合意が必要である。合意が必要となる具体的な項目は以下のとおりである。

  • issuerおよびaudience識別子の値
  • token endpointの場所
  • JWTに対するデジタル署名またはMACを適用・検証するために使用する鍵
  • JWTの一回限り使用の制約
  • 許容されるJWTの最大有効期間
  • JWTのsubjectとclaimに関する具体的な要件

これらの情報交換は、本仕様の対象外である。場合によっては、これらの値を制限または規定したり、それらをどのように交換するかを規定したりする追加のプロファイルが作成されることがある。そのようなプロファイルの例として、OAuth 2.0 Dynamic Client Registration Core Protocol [OAUTH-DYN-REG]、OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration]、およびOpenID Connect Discovery 1.0 [OpenID.Discovery] がある。

[JWA] に由来する "RS256" アルゴリズムは、本プロファイルにおける実装必須のJSON Web Signatureアルゴリズムである。

6. Security Considerations

以下の仕様に記述されているセキュリティ上の考慮事項は、すべて本文書に適用される。

  • 「Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants」[RFC7521]
  • 「The OAuth 2.0 Authorization Framework」[RFC6749]
  • 「JSON Web Token (JWT)」[JWT]

本仕様は、authorization grantとしての利用とclient authenticationとしての利用のいずれについても、JWTの使用に対するリプレイ防止を必須とはしていない。これは任意の機能であり、実装はそれぞれの裁量で採用してよい。

7. Privacy Considerations

JWTにはプライバシー上機微な情報が含まれ得るため、そのような情報が意図しない当事者に開示されることを防ぐには、Transport Layer Security (TLS) のような暗号化されたチャネル上でのみ送信すべきである。クライアントに対して特定の情報の開示を防ぐことが望ましい場合には、JWTはauthorization serverに対して暗号化されるべきである。

展開環境では、交換を完了するために必要となる最小限の情報量を判断し、JWTにはそのようなclaimのみを含めるべきである。場合によっては、OAuth Assertion Framework [RFC7521] のSection 6.3.1で述べられているとおり、"sub" (subject) claimは匿名または仮名のユーザーを表す値であってもよい。

8. IANA Considerations

8.1. Sub-Namespace Registration of urn:ietf:params:oauth:grant-type:jwt-bearer

本セクションは、「An IETF URN Sub-Namespace for OAuth」[RFC6755] により確立されたIANAの "OAuth URI" レジストリに、"grant-type:jwt-bearer" の値を登録する。

  • URN: urn:ietf:params:oauth:grant-type:jwt-bearer
  • Common Name: OAuth 2.0向けJWT Bearer Token Grant Type Profile
  • Change Controller: IESG
  • Specification Document: RFC 7523

8.2. Sub-Namespace Registration of urn:ietf:params:oauth:client-assertion-type:jwt-bearer

本セクションは、「An IETF URN Sub-Namespace for OAuth」[RFC6755] により確立されたIANAの "OAuth URI" レジストリに、"client-assertion-type:jwt-bearer" の値を登録する。

  • URN: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
  • Common Name: OAuth 2.0 Client Authentication向けJWT Bearer Token Profile
  • Change Controller: IESG
  • Specification Document: RFC 7523

9. References

9.1. Normative References

9.2. Informative References

  • [OAUTH-DYN-REG] Richer, J., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", Work in Progress, draft-ietf-oauth-dyn-reg-29, May 2015.
  • [OpenID.Discovery] Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID Connect Discovery 1.0 incorporating errata set 1", November 2014, http://openid.net/specs/openid-connect-discovery-1_0.html.
  • [OpenID.Registration] Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect Dynamic Client Registration 1.0 incorporating errata set 1", November 2014, http://openid.net/specs/openid-connect-registration-1_0.html.
  • [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, http://www.rfc-editor.org/info/rfc6755.
  • [RFC7522] Campbell, B., Mortimore, C., and M. Jones, "Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7522, DOI 10.17487/RFC7522, May 2015, http://www.rfc-editor.org/info/rfc7522.

Acknowledgements

本プロファイルは、「Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants」[RFC7522] から派生したものであり、本文書と同じ著者を持つ。

Authors' Addresses

Michael B. Jones (Microsoft)

  • EMail: mbj@microsoft.com
  • URI: http://self-issued.info/

Brian Campbell (Ping Identity)

  • EMail: brian.d.campbell@gmail.com

Chuck Mortimore (Salesforce)

  • EMail: cmortimore@salesforce.com