< draft-ietf-oauth-json-web-token-09.txt		draft-ietf-oauth-json-web-token-10.txt >
	OAuth Working Group M. Jones		OAuth Working Group M. Jones
	Internet-Draft Microsoft		Internet-Draft Microsoft
	Intended status: Standards Track J. Bradley		Intended status: Standards Track J. Bradley
	Expires: January 12, 2014 Ping Identity		Expires: January 15, 2014 Ping Identity
	N. Sakimura		N. Sakimura
	NRI		NRI
	July 11, 2013		July 14, 2013
	JSON Web Token (JWT)		JSON Web Token (JWT)
	draft-ietf-oauth-json-web-token-09		draft-ietf-oauth-json-web-token-10
	Abstract		Abstract
	JSON Web Token (JWT) is a compact URL-safe means of representing		JSON Web Token (JWT) is a compact URL-safe means of representing
	claims to be transferred between two parties. The claims in a JWT		claims to be transferred between two parties. The claims in a JWT
	are encoded as a JavaScript Object Notation (JSON) object that is		are encoded as a JavaScript Object Notation (JSON) object that is
	used as the payload of a JSON Web Signature (JWS) structure or as the		used as the payload of a JSON Web Signature (JWS) structure or as the
	plaintext of a JSON Web Encryption (JWE) structure, enabling the		plaintext of a JSON Web Encryption (JWE) structure, enabling the
	claims to be digitally signed or MACed and/or encrypted.		claims to be digitally signed or MACed and/or encrypted.
	skipping to change at page 1, line 41 ¶		skipping to change at page 1, line 41 ¶
	Internet-Drafts are working documents of the Internet Engineering		Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF). Note that other groups may also distribute		Task Force (IETF). Note that other groups may also distribute
	working documents as Internet-Drafts. The list of current Internet-		working documents as Internet-Drafts. The list of current Internet-
	Drafts is at http://datatracker.ietf.org/drafts/current/.		Drafts is at http://datatracker.ietf.org/drafts/current/.
	Internet-Drafts are draft documents valid for a maximum of six months		Internet-Drafts are draft documents valid for a maximum of six months
	and may be updated, replaced, or obsoleted by other documents at any		and may be updated, replaced, or obsoleted by other documents at any
	time. It is inappropriate to use Internet-Drafts as reference		time. It is inappropriate to use Internet-Drafts as reference
	material or to cite them other than as "work in progress."		material or to cite them other than as "work in progress."
	This Internet-Draft will expire on January 12, 2014.		This Internet-Draft will expire on January 15, 2014.
	Copyright Notice		Copyright Notice
	Copyright (c) 2013 IETF Trust and the persons identified as the		Copyright (c) 2013 IETF Trust and the persons identified as the
	document authors. All rights reserved.		document authors. All rights reserved.
	This document is subject to BCP 78 and the IETF Trust's Legal		This document is subject to BCP 78 and the IETF Trust's Legal
	Provisions Relating to IETF Documents		Provisions Relating to IETF Documents
	(http://trustee.ietf.org/license-info) in effect on the date of		(http://trustee.ietf.org/license-info) in effect on the date of
	publication of this document. Please review these documents		publication of this document. Please review these documents
	carefully, as they describe your rights and restrictions with respect		carefully, as they describe your rights and restrictions with respect
	to this document. Code Components extracted from this document must		to this document. Code Components extracted from this document must
	include Simplified BSD License text as described in Section 4.e of		include Simplified BSD License text as described in Section 4.e of
	the Trust Legal Provisions and are provided without warranty as		the Trust Legal Provisions and are provided without warranty as
	described in the Simplified BSD License.		described in the Simplified BSD License.
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
	1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5		1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4
	2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5		2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
	3. JSON Web Token (JWT) Overview . . . . . . . . . . . . . . . . 7		3. JSON Web Token (JWT) Overview . . . . . . . . . . . . . . . . 6
	3.1. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 7		3.1. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 6
	4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 8		4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 7
	4.1. Reserved Claim Names . . . . . . . . . . . . . . . . . . . 9		4.1. Reserved Claim Names . . . . . . . . . . . . . . . . . . . 8
	4.1.1. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . 9		4.1.1. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . 8
	4.1.2. "sub" (Subject) Claim . . . . . . . . . . . . . . . . 9		4.1.2. "sub" (Subject) Claim . . . . . . . . . . . . . . . . 8
	4.1.3. "aud" (Audience) Claim . . . . . . . . . . . . . . . . 9		4.1.3. "aud" (Audience) Claim . . . . . . . . . . . . . . . . 8
	4.1.4. "exp" (Expiration Time) Claim . . . . . . . . . . . . 10		4.1.4. "exp" (Expiration Time) Claim . . . . . . . . . . . . 9
	4.1.5. "nbf" (Not Before) Claim . . . . . . . . . . . . . . . 10		4.1.5. "nbf" (Not Before) Claim . . . . . . . . . . . . . . . 9
	4.1.6. "iat" (Issued At) Claim . . . . . . . . . . . . . . . 10		4.1.6. "iat" (Issued At) Claim . . . . . . . . . . . . . . . 9
	4.1.7. "jti" (JWT ID) Claim . . . . . . . . . . . . . . . . . 10		4.1.7. "jti" (JWT ID) Claim . . . . . . . . . . . . . . . . . 9
	4.1.8. "typ" (Type) Claim . . . . . . . . . . . . . . . . . . 10		4.1.8. "typ" (Type) Claim . . . . . . . . . . . . . . . . . . 9
	4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 11		4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 10
	4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 11		4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 10
	5. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 11		5. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 10
	5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 11		5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 10
	5.2. "cty" (Content Type) Header Parameter . . . . . . . . . . 12		5.2. "cty" (Content Type) Header Parameter . . . . . . . . . . 11
	6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 12		5.3. Replicating Claims as Header Parameters . . . . . . . . . 11
			6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 11
	6.1. Example Plaintext JWT . . . . . . . . . . . . . . . . . . 12		6.1. Example Plaintext JWT . . . . . . . . . . . . . . . . . . 12
	7. Rules for Creating and Validating a JWT . . . . . . . . . . . 13		7. Rules for Creating and Validating a JWT . . . . . . . . . . . 12
	7.1. String Comparison Rules . . . . . . . . . . . . . . . . . 15		7.1. String Comparison Rules . . . . . . . . . . . . . . . . . 14
	8. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 15		8. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 14
	9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15		9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
	9.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 16		9.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 15
	9.1.1. Registration Template . . . . . . . . . . . . . . . . 16		9.1.1. Registration Template . . . . . . . . . . . . . . . . 16
	9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 17		9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 16
	9.2. Sub-Namespace Registration of		9.2. Sub-Namespace Registration of
	urn:ietf:params:oauth:token-type:jwt . . . . . . . . . . . 17		urn:ietf:params:oauth:token-type:jwt . . . . . . . . . . . 17
	9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 17		9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
	9.3. JSON Web Signature and Encryption Type Values		9.3. JSON Web Signature and Encryption Type Values
	Registration . . . . . . . . . . . . . . . . . . . . . . . 18		Registration . . . . . . . . . . . . . . . . . . . . . . . 17
	9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 18		9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
	9.4. Media Type Registration . . . . . . . . . . . . . . . . . 18		9.4. Media Type Registration . . . . . . . . . . . . . . . . . 17
	9.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 18		9.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
	10. Security Considerations . . . . . . . . . . . . . . . . . . . 19		9.5. Registration of JWE Header Parameter Names . . . . . . . . 18
			9.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 18
			10. Security Considerations . . . . . . . . . . . . . . . . . . . 18
	11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19		11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19
	11.1. Normative References . . . . . . . . . . . . . . . . . . . 19		11.1. Normative References . . . . . . . . . . . . . . . . . . . 19
	11.2. Informative References . . . . . . . . . . . . . . . . . . 20		11.2. Informative References . . . . . . . . . . . . . . . . . . 20
	Appendix A. Example Encrypted JWT . . . . . . . . . . . . . . . . 21		Appendix A. Example Encrypted JWT . . . . . . . . . . . . . . . . 21
	Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 22		Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 22
	Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 23		Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 22
	Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 23		Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 23
	Appendix E. Document History . . . . . . . . . . . . . . . . . . 23		Appendix E. Document History . . . . . . . . . . . . . . . . . . 23
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 26		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 26
	1. Introduction		1. Introduction
	JSON Web Token (JWT) is a compact claims representation format		JSON Web Token (JWT) is a compact claims representation format
	intended for space constrained environments such as HTTP		intended for space constrained environments such as HTTP
	Authorization headers and URI query parameters. JWTs encode claims		Authorization headers and URI query parameters. JWTs encode claims
	to be transmitted as a JavaScript Object Notation (JSON) [RFC4627]		to be transmitted as a JavaScript Object Notation (JSON) [RFC4627]
	skipping to change at page 8, line 44 ¶		skipping to change at page 7, line 44 ¶
	.		.
	dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk		dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
	This computation is illustrated in more detail in Appendix A.1 of		This computation is illustrated in more detail in Appendix A.1 of
	[JWS]. See Appendix A for an example of an encrypted JWT.		[JWS]. See Appendix A for an example of an encrypted JWT.
	4. JWT Claims		4. JWT Claims
	The JWT Claims Set represents a JSON object whose members are the		The JWT Claims Set represents a JSON object whose members are the
	claims conveyed by the JWT. The Claim Names within a JWT Claims Set		claims conveyed by the JWT. The Claim Names within a JWT Claims Set
	MUST be unique; receipients MUST either reject JWTs with duplicate		MUST be unique; recipients MUST either reject JWTs with duplicate
	Claim Names or use a JSON parser that returns only the lexically last		Claim Names or use a JSON parser that returns only the lexically last
	duplicate member name, as specified in Section 15.12 (The JSON		duplicate member name, as specified in Section 15.12 (The JSON
	Object) of ECMAScript 5.1 [ECMAScript].		Object) of ECMAScript 5.1 [ECMAScript].
	The set of claims that a JWT must contain to be considered valid is		The set of claims that a JWT must contain to be considered valid is
	context-dependent and is outside the scope of this specification.		context-dependent and is outside the scope of this specification.
	Specific applications of JWTs will require implementations to		Specific applications of JWTs will require implementations to
	understand and process some claims in particular ways. However, in		understand and process some claims in particular ways. However, in
	the absence of such requirements, all claims that are not understood		the absence of such requirements, all claims that are not understood
	by implementations SHOULD be ignored.		by implementations SHOULD be ignored.
	skipping to change at page 11, line 28 ¶		skipping to change at page 10, line 28 ¶
	are Private Names: names that are not Reserved Names Section 4.1 or		are Private Names: names that are not Reserved Names Section 4.1 or
	Public Names Section 4.2. Unlike Public Names, Private Names are		Public Names Section 4.2. Unlike Public Names, Private Names are
	subject to collision and should be used with caution.		subject to collision and should be used with caution.
	5. JWT Header		5. JWT Header
	The members of the JSON object represented by the JWT Header describe		The members of the JSON object represented by the JWT Header describe
	the cryptographic operations applied to the JWT and optionally,		the cryptographic operations applied to the JWT and optionally,
	additional properties of the JWT. The member names within the JWT		additional properties of the JWT. The member names within the JWT
	Header are referred to as Header Parameter Names. These names MUST		Header are referred to as Header Parameter Names. These names MUST
	be unique; receipients MUST either reject JWTs with duplicate Header		be unique; recipients MUST either reject JWTs with duplicate Header
	Parameter Names or use a JSON parser that returns only the lexically		Parameter Names or use a JSON parser that returns only the lexically
	last duplicate member name, as specified in Section 15.12 (The JSON		last duplicate member name, as specified in Section 15.12 (The JSON
	Object) of ECMAScript 5.1 [ECMAScript]. The corresponding values are		Object) of ECMAScript 5.1 [ECMAScript]. The corresponding values are
	referred to as Header Parameter Values.		referred to as Header Parameter Values.
	JWS Header Parameters are defined by [JWS]. JWE Header Parameters		JWS Header Parameters are defined by [JWS]. JWE Header Parameters
	are defined by [JWE]. This specification further specifies the use		are defined by [JWE]. This specification further specifies the use
	of the following header parameter in both the cases where the JWT is		of the following header parameter in both the cases where the JWT is
	a JWS and where it is a JWE.		a JWS and where it is a JWE.
	skipping to change at page 12, line 20 ¶		skipping to change at page 11, line 20 ¶
	In the normal case where nested signing or encryption operations are		In the normal case where nested signing or encryption operations are
	not employed, the use of this header parameter is NOT RECOMMENDED.		not employed, the use of this header parameter is NOT RECOMMENDED.
	In the case that nested signing or encryption is employed, the use of		In the case that nested signing or encryption is employed, the use of
	this header parameter is REQUIRED; in this case, the value MUST be		this header parameter is REQUIRED; in this case, the value MUST be
	"JWT", to indicate that a Nested JWT is carried in this JWT.		"JWT", to indicate that a Nested JWT is carried in this JWT.
	The values used for the "cty" header parameter come from the same		The values used for the "cty" header parameter come from the same
	value space as the "typ" header parameter, with the same rules		value space as the "typ" header parameter, with the same rules
	applying.		applying.
			5.3. Replicating Claims as Header Parameters
			In some applications using encrypted JWTs, it is useful to have an
			unencrypted representation of some Claims. This might be used, for
			instance, in application processing rules to determine whether and
			how to process the JWT before it is decrypted.
			This specification allows Claims present in the JWT Claims Set to be
			replicated as Header Parameters in a JWT that is a JWE, as needed by
			the application. If such replicated Claims are present, the
			application receiving them SHOULD verify that their values are
			identical. It is the responsibility of the application to ensure
			that only claims that are safe to be transmitted in an unencrypted
			manner are replicated as Header Parameter values in the JWT.
			This specification reserves the "iss" (issuer) and "aud" (audience)
			Header Parameter Names for the purpose of providing unencrypted
			replicas of these Claims in encrypted JWTs for applications that need
			them. Other specifications MAY similarly reserve other names that
			are reserved Claim Names as Header Parameter Names, as needed.
	6. Plaintext JWTs		6. Plaintext JWTs
	To support use cases where the JWT content is secured by a means		To support use cases where the JWT content is secured by a means
	other than a signature and/or encryption contained within the JWT		other than a signature and/or encryption contained within the JWT
	(such as a signature on a data structure containing the JWT), JWTs		(such as a signature on a data structure containing the JWT), JWTs
	MAY also be created without a signature or encryption. A plaintext		MAY also be created without a signature or encryption. A plaintext
	JWT is a JWS using the "none" JWS "alg" header parameter value		JWT is a JWS using the "none" JWS "alg" header parameter value
	defined in JSON Web Algorithms (JWA) [JWA]; it is a JWS with the		defined in JSON Web Algorithms (JWA) [JWA]; it is a JWS with the
	empty string for its JWS Signature value.		empty string for its JWS Signature value.
	skipping to change at page 13, line 28 ¶		skipping to change at page 12, line 50 ¶
	.		.
	7. Rules for Creating and Validating a JWT		7. Rules for Creating and Validating a JWT
	To create a JWT, one MUST perform these steps. The order of the		To create a JWT, one MUST perform these steps. The order of the
	steps is not significant in cases where there are no dependencies		steps is not significant in cases where there are no dependencies
	between the inputs and outputs of the steps.		between the inputs and outputs of the steps.
	1. Create a JWT Claims Set containing the desired claims. Note that		1. Create a JWT Claims Set containing the desired claims. Note that
	white space is explicitly allowed in the representation and no		white space is explicitly allowed in the representation and no
	canonicalization is performed before encoding.		canonicalization need be performed before encoding.
	2. Let the Message be the octets of the UTF-8 representation of the		2. Let the Message be the octets of the UTF-8 representation of the
	JWT Claims Set.		JWT Claims Set.
	3. Create a JWT Header containing the desired set of header		3. Create a JWT Header containing the desired set of header
	parameters. The JWT MUST conform to either the [JWS] or [JWE]		parameters. The JWT MUST conform to either the [JWS] or [JWE]
	specifications. Note that white space is explicitly allowed in		specifications. Note that white space is explicitly allowed in
	the representation and no canonicalization is performed before		the representation and no canonicalization need be performed
	encoding.		before encoding.
	4. Base64url encode the octets of the UTF-8 representation of the		4. Base64url encode the octets of the UTF-8 representation of the
	JWT Header. Let this be the Encoded JWT Header.		JWT Header. Let this be the Encoded JWT Header.
	5. Depending upon whether the JWT is a JWS or JWE, there are two		5. Depending upon whether the JWT is a JWS or JWE, there are two
	cases:		cases:
	* If the JWT is a JWS, create a JWS using the JWT Header as the		* If the JWT is a JWS, create a JWS using the JWT Header as the
	JWS Header and the Message as the JWS Payload; all steps		JWS Header and the Message as the JWS Payload; all steps
	specified in [JWS] for creating a JWS MUST be followed.		specified in [JWS] for creating a JWS MUST be followed.
	skipping to change at page 19, line 5 ¶		skipping to change at page 18, line 25 ¶
	Persona, Salesforce, Google, numerous others		Persona, Salesforce, Google, numerous others
	o Additional Information: Magic number(s): n/a, File extension(s):		o Additional Information: Magic number(s): n/a, File extension(s):
	n/a, Macintosh file type code(s): n/a		n/a, Macintosh file type code(s): n/a
	o Person & email address to contact for further information: Michael		o Person & email address to contact for further information: Michael
	B. Jones, mbj@microsoft.com		B. Jones, mbj@microsoft.com
	o Intended Usage: COMMON		o Intended Usage: COMMON
	o Restrictions on Usage: none		o Restrictions on Usage: none
	o Author: Michael B. Jones, mbj@microsoft.com		o Author: Michael B. Jones, mbj@microsoft.com
	o Change Controller: IETF		o Change Controller: IETF
			9.5. Registration of JWE Header Parameter Names
			This specification registers specific reserved Claim Names defined in
			Section 4.1 in the IANA JSON Web Signature and Encryption Header
			Parameters registry [JWS] for use by Claims replicated as Header
			Parameters, per Section 5.3.
			9.5.1. Registry Contents
			o Header Parameter Name: "iss"
			o Header Parameter Usage Location(s): JWE
			o Change Controller: IETF
			o Specification Document(s): Section 4.1.1 of [[ this document ]]
			o Header Parameter Name: "aud"
			o Header Parameter Usage Location(s): JWE
			o Change Controller: IETF
			o Specification Document(s): Section 4.1.3 of [[ this document ]]
	10. Security Considerations		10. Security Considerations
	All of the security issues faced by any cryptographic application		All of the security issues faced by any cryptographic application
	must be faced by a JWT/JWS/JWE/JWK agent. Among these issues are		must be faced by a JWT/JWS/JWE/JWK agent. Among these issues are
	protecting the user's private and symmetric keys, preventing various		protecting the user's private and symmetric keys, preventing various
	attacks, and helping the user avoid mistakes such as inadvertently		attacks, and helping the user avoid mistakes such as inadvertently
	encrypting a message for the wrong recipient. The entire list of		encrypting a message for the wrong recipient. The entire list of
	security considerations is beyond the scope of this document.		security considerations is beyond the scope of this document.
	All the security considerations in the JWS specification also apply		All the security considerations in the JWS specification also apply
	skipping to change at page 23, line 45 ¶		skipping to change at page 23, line 40 ¶
	Schaad, Paul Tarjan, Hannes Tschofenig, and Sean Turner.		Schaad, Paul Tarjan, Hannes Tschofenig, and Sean Turner.
	Hannes Tschofenig and Derek Atkins chaired the OAuth working group		Hannes Tschofenig and Derek Atkins chaired the OAuth working group
	and Sean Turner and Stephen Farrell served as Security area directors		and Sean Turner and Stephen Farrell served as Security area directors
	during the creation of this specification.		during the creation of this specification.
	Appendix E. Document History		Appendix E. Document History
	[[ to be removed by the RFC editor before publication as an RFC ]]		[[ to be removed by the RFC editor before publication as an RFC ]]
			-10
			o Allowed Claims to be replicated as Header Parameters in encrypted
			JWTs as needed by applications that require an unencrypted
			representation of specific Claims.
	-09		-09
	o Clarified that the "typ" header parameter is used in an		o Clarified that the "typ" header parameter is used in an
	application-specific manner and has no effect upon the JWT		application-specific manner and has no effect upon the JWT
	processing.		processing.
	o Stated that receipients MUST either reject JWTs with duplicate		o Stated that recipients MUST either reject JWTs with duplicate
	Header Parameter Names or with duplicate Claim Names or use a JSON		Header Parameter Names or with duplicate Claim Names or use a JSON
	parser that returns only the lexically last duplicate member name.		parser that returns only the lexically last duplicate member name.
	-08		-08
	o Tracked a change to how JWEs are computed (which only affected the		o Tracked a change to how JWEs are computed (which only affected the
	example encrypted JWT value).		example encrypted JWT value).
	-07		-07
End of changes. 18 change blocks.
	42 lines changed or deleted		91 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/