< draft-ietf-oauth-json-web-token-22.txt		draft-ietf-oauth-json-web-token-23.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: December 22, 2014 Ping Identity		Expires: December 22, 2014 Ping Identity
	N. Sakimura		N. Sakimura
	NRI		NRI
	June 20, 2014		June 20, 2014
	JSON Web Token (JWT)		JSON Web Token (JWT)
	draft-ietf-oauth-json-web-token-22		draft-ietf-oauth-json-web-token-23
	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 2, line 21 ¶		skipping to change at page 2, line 21 ¶
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
	1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4		1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4
	2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4		2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
	3. JSON Web Token (JWT) Overview . . . . . . . . . . . . . . . . 6		3. JSON Web Token (JWT) Overview . . . . . . . . . . . . . . . . 6
	3.1. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 6		3.1. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 6
	4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 8		4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 8
	4.1. Registered Claim Names . . . . . . . . . . . . . . . . . . 8		4.1. Registered 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 . . . . . . . . . . . . . . . . 9
	4.1.3. "aud" (Audience) Claim . . . . . . . . . . . . . . . . 9		4.1.3. "aud" (Audience) Claim . . . . . . . . . . . . . . . . 9
	4.1.4. "exp" (Expiration Time) Claim . . . . . . . . . . . . 9		4.1.4. "exp" (Expiration Time) Claim . . . . . . . . . . . . 9
	4.1.5. "nbf" (Not Before) Claim . . . . . . . . . . . . . . . 9		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 . . . . . . . . . . . . . . . . . 10
	4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 10		4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 10
	4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 10		4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 10
	5. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 10		5. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . . 10
	5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 11		5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 10
	5.2. "cty" (Content Type) Header Parameter . . . . . . . . . . 11		5.2. "cty" (Content Type) Header Parameter . . . . . . . . . . 11
	5.3. Replicating Claims as Header Parameters . . . . . . . . . 11		5.3. Replicating Claims as Header Parameters . . . . . . . . . 11
	6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 12		6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 12
	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 . . . . . . . . . . . 13
	7.1. String Comparison Rules . . . . . . . . . . . . . . . . . 15		7.1. String Comparison Rules . . . . . . . . . . . . . . . . . 14
	8. Implementation Requirements . . . . . . . . . . . . . . . . . 15		8. Implementation Requirements . . . . . . . . . . . . . . . . . 15
	9. URI for Declaring that Content is a JWT . . . . . . . . . . . 16		9. URI for Declaring that Content is a JWT . . . . . . . . . . . 15
	10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16		10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
	10.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 16		10.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 16
	10.1.1. Registration Template . . . . . . . . . . . . . . . . 17		10.1.1. Registration Template . . . . . . . . . . . . . . . . 17
	10.1.2. Initial Registry Contents . . . . . . . . . . . . . . 17		10.1.2. Initial Registry Contents . . . . . . . . . . . . . . 17
	10.2. Sub-Namespace Registration of		10.2. Sub-Namespace Registration of
	urn:ietf:params:oauth:token-type:jwt . . . . . . . . . . . 18		urn:ietf:params:oauth:token-type:jwt . . . . . . . . . . . 18
	10.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 18		10.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 18
	10.3. Media Type Registration . . . . . . . . . . . . . . . . . 18		10.3. Media Type Registration . . . . . . . . . . . . . . . . . 18
	10.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 19		10.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 18
	10.4. Registration of JWE Header Parameter Names . . . . . . . . 19		10.4. Header Parameter Names Registration . . . . . . . . . . . 19
	10.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 19		10.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 19
	11. Security Considerations . . . . . . . . . . . . . . . . . . . 20		11. Security Considerations . . . . . . . . . . . . . . . . . . . 19
	11.1. Trust Decisions . . . . . . . . . . . . . . . . . . . . . 20		11.1. Trust Decisions . . . . . . . . . . . . . . . . . . . . . 20
	11.2. Signing and Encryption Order . . . . . . . . . . . . . . . 20		11.2. Signing and Encryption Order . . . . . . . . . . . . . . . 20
	12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21		12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20
	12.1. Normative References . . . . . . . . . . . . . . . . . . . 21		12.1. Normative References . . . . . . . . . . . . . . . . . . . 20
	12.2. Informative References . . . . . . . . . . . . . . . . . . 22		12.2. Informative References . . . . . . . . . . . . . . . . . . 21
	Appendix A. JWT Examples . . . . . . . . . . . . . . . . . . . . 23		Appendix A. JWT Examples . . . . . . . . . . . . . . . . . . . . 22
	A.1. Example Encrypted JWT . . . . . . . . . . . . . . . . . . 23		A.1. Example Encrypted JWT . . . . . . . . . . . . . . . . . . 22
	A.2. Example Nested JWT . . . . . . . . . . . . . . . . . . . . 23		A.2. Example Nested JWT . . . . . . . . . . . . . . . . . . . . 23
	Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 25		Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 25
	Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 26		Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 26
	Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 26		Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 26
	Appendix E. Document History . . . . . . . . . . . . . . . . . . 26		Appendix E. Document History . . . . . . . . . . . . . . . . . . 26
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 31		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 32
	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) [RFC7159]		to be transmitted as a JavaScript Object Notation (JSON) [RFC7159]
	object that is used as the payload of a JSON Web Signature (JWS)		object that is used as the payload of a JSON Web Signature (JWS)
	[JWS] structure or as the plaintext of a JSON Web Encryption (JWE)		[JWS] structure or as the plaintext of a JSON Web Encryption (JWE)
	[JWE] structure, enabling the claims to be digitally signed or MACed		[JWE] structure, enabling the claims to be digitally signed or MACed
	skipping to change at page 4, line 31 ¶		skipping to change at page 4, line 31 ¶
	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",		The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
	"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and		"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
	"OPTIONAL" in this document are to be interpreted as described in Key		"OPTIONAL" in this document are to be interpreted as described in Key
	words for use in RFCs to Indicate Requirement Levels [RFC2119]. If		words for use in RFCs to Indicate Requirement Levels [RFC2119]. If
	these words are used without being spelled in uppercase then they are		these words are used without being spelled in uppercase then they are
	to be interpreted with their normal natural language meanings.		to be interpreted with their normal natural language meanings.
	2. Terminology		2. Terminology
			These terms defined by the JSON Web Signature (JWS) [JWS]
			specification are incorporated into this specification: "JSON Web
			Signature (JWS)", "Base64url Encoding", "Header Parameter", "JOSE
			Header", "JWS Compact Serialization", "JWS Payload", "JWS Signature",
			and "Plaintext JWS".
			These terms defined by the JSON Web Encryption (JWE) [JWE]
			specification are incorporated into this specification: "JSON Web
			Encryption (JWE)", "Content Encryption Key (CEK)", "JWE Compact
			Serialization", "JWE Encrypted Key", "JWE Initialization Vector",
			"JWE Plaintext".
			These terms are defined by this specification:
	JSON Web Token (JWT)		JSON Web Token (JWT)
	A string representing a set of claims as a JSON object that is		A string representing a set of claims as a JSON object that is
	encoded in a JWS or JWE, enabling the claims to be digitally		encoded in a JWS or JWE, enabling the claims to be digitally
	signed or MACed and/or encrypted.		signed or MACed and/or encrypted.
	Base64url Encoding
	Base64 encoding using the URL- and filename-safe character set
	defined in Section 5 of RFC 4648 [RFC4648], with all trailing '='
	characters omitted (as permitted by Section 3.2) and without the
	inclusion of any line breaks, white space, or other additional
	characters. (See Appendix C of [JWS] for notes on implementing
	base64url encoding without padding.)
	JWT Header
	A JSON object that describes the cryptographic operations applied
	to the JWT. When the JWT is digitally signed or MACed, the JWT
	Header is a JWS Header. When the JWT is encrypted, the JWT Header
	is a JWE Header.
	Header Parameter
	A name/value pair that is member of the JWT Header.
	Header Parameter Name
	The name of a member of the JWT Header.
	Header Parameter Value
	The value of a member of the JWT Header.
	JWT Claims Set		JWT Claims Set
	A JSON object that contains the Claims conveyed by the JWT.		A JSON object that contains the Claims conveyed by the JWT.
	Claim		Claim
	A piece of information asserted about a subject. A Claim is		A piece of information asserted about a subject. A Claim is
	represented as a name/value pair consisting of a Claim Name and a		represented as a name/value pair consisting of a Claim Name and a
	Claim Value.		Claim Value.
	Claim Name		Claim Name
	The name portion of a Claim representation. A Claim Name is		The name portion of a Claim representation. A Claim Name is
	always a string.		always a string.
	Claim Value		Claim Value
	The value portion of a Claim representation. A Claim Value can be		The value portion of a Claim representation. A Claim Value can be
	any JSON value.		any JSON value.
	Encoded JWT Header		Encoded JOSE Header
	Base64url encoding of the JWT Header.		Base64url encoding of the JOSE Header.
	Nested JWT		Nested JWT
	A JWT in which nested signing and/or encryption are employed. In		A JWT in which nested signing and/or encryption are employed. In
	nested JWTs, a JWT is used as the payload or plaintext value of an		nested JWTs, a JWT is used as the payload or plaintext value of an
	enclosing JWS or JWE structure, respectively.		enclosing JWS or JWE structure, respectively.
	Plaintext JWT		Plaintext JWT
	A JWT whose Claims are not integrity protected or encrypted.		A JWT whose Claims are not integrity protected or encrypted.
	Collision-Resistant Name		Collision-Resistant Name
	skipping to change at page 6, line 30 ¶		skipping to change at page 6, line 23 ¶
	JWTs represent a set of claims as a JSON object that is encoded in a		JWTs represent a set of claims as a JSON object that is encoded in a
	JWS and/or JWE structure. This JSON object is the JWT Claims Set. As		JWS and/or JWE structure. This JSON object is the JWT Claims Set. As
	per Section 4 of [RFC7159], the JSON object consists of zero or more		per Section 4 of [RFC7159], the JSON object consists of zero or more
	name/value pairs (or members), where the names are strings and the		name/value pairs (or members), where the names are strings and the
	values are arbitrary JSON values. These members are the claims		values are arbitrary JSON values. These members are the claims
	represented by the JWT.		represented by the JWT.
	The member names within the JWT Claims Set are referred to as Claim		The member names within the JWT Claims Set are referred to as Claim
	Names. The corresponding values are referred to as Claim Values.		Names. The corresponding values are referred to as Claim Values.
	The contents of the JWT Header describe the cryptographic operations		The contents of the JOSE Header describe the cryptographic operations
	applied to the JWT Claims Set. If the JWT Header is a JWS Header, the		applied to the JWT Claims Set. If the JOSE Header is for a JWS
	JWT is represented as a JWS, and the claims are digitally signed or		object, the JWT is represented as a JWS, and the claims are digitally
	MACed, with the JWT Claims Set being the JWS Payload. If the JWT		signed or MACed, with the JWT Claims Set being the JWS Payload. If
	Header is a JWE Header, the JWT is represented as a JWE, and the		the JOSE Header is for a JWE object, the JWT is represented as a JWE,
	claims are encrypted, with the JWT Claims Set being the input		and the claims are encrypted, with the JWT Claims Set being the JWE
	Plaintext. A JWT may be enclosed in another JWE or JWS structure to		Plaintext. A JWT may be enclosed in another JWE or JWS structure to
	create a Nested JWT, enabling nested signing and encryption to be		create a Nested JWT, enabling nested signing and encryption to be
	performed.		performed.
	A JWT is represented as a sequence of URL-safe parts separated by		A JWT is represented as a sequence of URL-safe parts separated by
	period ('.') characters. Each part contains a base64url encoded		period ('.') characters. Each part contains a base64url encoded
	value. The number of parts in the JWT is dependent upon the		value. The number of parts in the JWT is dependent upon the
	representation of the resulting JWS or JWE object using the JWS		representation of the resulting JWS or JWE object using the JWS
	Compact Serialization or the JWE Compact Serialization.		Compact Serialization or the JWE Compact Serialization.
	3.1. Example JWT		3.1. Example JWT
	The following example JWT Header declares that the encoded object is		The following example JOSE Header declares that the encoded object is
	a JSON Web Token (JWT) and the JWT is a JWS that is MACed using the		a JSON Web Token (JWT) and the JWT is a JWS that is MACed using the
	HMAC SHA-256 algorithm:		HMAC SHA-256 algorithm:
	{"typ":"JWT",		{"typ":"JWT",
	"alg":"HS256"}		"alg":"HS256"}
	To remove potential ambiguities in the representation of the JSON		To remove potential ambiguities in the representation of the JSON
	object above, the octet sequence for the actual UTF-8 representation		object above, the octet sequence for the actual UTF-8 representation
	used in this example for the JWT Header/JWS Header above is also		used in this example for the JOSE Header above is also included
	included below. (Note that ambiguities can arise due to differing		below. (Note that ambiguities can arise due to differing platform
	platform representations of line breaks (CRLF versus LF), differing		representations of line breaks (CRLF versus LF), differing spacing at
	spacing at the beginning and ends of lines, whether the last line has		the beginning and ends of lines, whether the last line has a
	a terminating line break or not, and other causes. In the		terminating line break or not, and other causes. In the
	representation used in this example, the first line has no leading or		representation used in this example, the first line has no leading or
	trailing spaces, a CRLF line break (13, 10) occurs between the first		trailing spaces, a CRLF line break (13, 10) occurs between the first
	and second lines, the second line has one leading space (32) and no		and second lines, the second line has one leading space (32) and no
	trailing spaces, and the last line does not have a terminating line		trailing spaces, and the last line does not have a terminating line
	break.) The octets representing the UTF-8 representation of the JWS		break.) The octets representing the UTF-8 representation of the JOSE
	Header in this example (using JSON array notation) are:		Header in this example (using JSON array notation) are:
	[123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32,		[123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32,
	34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125]		34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125]
	Base64url encoding the octets of the UTF-8 representation of the JWT		Base64url encoding the octets of the UTF-8 representation of the JOSE
	Header yields this Encoded JWT Header value (which is also the		Header yields this Encoded JOSE Header value:
	underlying encoded JWS Header value):
	eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9		eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
	The following is an example of a JWT Claims Set:		The following is an example of a JWT Claims Set:
	{"iss":"joe",		{"iss":"joe",
	"exp":1300819380,		"exp":1300819380,
	"http://example.com/is_root":true}		"http://example.com/is_root":true}
	The following octet sequence, which is the UTF-8 representation used		The following octet sequence, which is the UTF-8 representation used
	skipping to change at page 7, line 52 ¶		skipping to change at page 7, line 43 ¶
	48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97,		48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97,
	109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111,		109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111,
	111, 116, 34, 58, 116, 114, 117, 101, 125]		111, 116, 34, 58, 116, 114, 117, 101, 125]
	Base64url encoding the JWS Payload yields this encoded JWS Payload		Base64url encoding the JWS Payload yields this encoded JWS Payload
	(with line breaks for display purposes only):		(with line breaks for display purposes only):
	eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly		eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly
	9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ		9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
	Computing the MAC of the encoded JWS Header and encoded JWS Payload		Computing the MAC of the encoded JOSE Header and encoded JWS Payload
	with the HMAC SHA-256 algorithm and base64url encoding the HMAC value		with the HMAC SHA-256 algorithm and base64url encoding the HMAC value
	in the manner specified in [JWS], yields this encoded JWS Signature:		in the manner specified in [JWS], yields this encoded JWS Signature:
	dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk		dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
	Concatenating these encoded parts in this order with period ('.')		Concatenating these encoded parts in this order with period ('.')
	characters between the parts yields this complete JWT (with line		characters between the parts yields this complete JWT (with line
	breaks for display purposes only):		breaks for display purposes only):
	eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9		eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
	skipping to change at page 10, line 43 ¶		skipping to change at page 10, line 34 ¶
	the part of the namespace they use to define the Claim Name.		the part of the namespace they use to define the Claim Name.
	4.3. Private Claim Names		4.3. Private Claim Names
	A producer and consumer of a JWT MAY agree to use Claim Names that		A producer and consumer of a JWT MAY agree to use Claim Names that
	are Private Names: names that are not Registered Claim Names		are Private Names: names that are not Registered Claim Names
	Section 4.1 or Public Claim Names Section 4.2. Unlike Public Claim		Section 4.1 or Public Claim Names Section 4.2. Unlike Public Claim
	Names, Private Claim Names are subject to collision and should be		Names, Private Claim Names are subject to collision and should be
	used with caution.		used with caution.
	5. JWT Header		5. JOSE Header
	The members of the JSON object represented by the JWT Header describe		For a JWT object, the members of the JSON object represented by the
	the cryptographic operations applied to the JWT and optionally,		JOSE Header describe the cryptographic operations applied to the JWT
	additional properties of the JWT. The member names within the JWT		and optionally, additional properties of the JWT. Depending upon
	Header are referred to as Header Parameter Names. These names MUST		whether the JWT is a JWS or JWE, the corresponding rules for the JOSE
	be unique; recipients MUST either reject JWTs with duplicate Header		Header values apply.
	Parameter Names or use a JSON parser that returns only the lexically
	last duplicate member name, as specified in Section 15.12 (The JSON
	Object) of ECMAScript 5.1 [ECMAScript]. The corresponding values are
	referred to as Header Parameter Values.
	JWS Header Parameters are defined by [JWS]. JWE Header Parameters		This specification further specifies the use of the following Header
	are defined by [JWE]. This specification further specifies the use		Parameters in both the cases where the JWT is a JWS and where it is a
	of the following Header Parameters in both the cases where the JWT is		JWE.
	a JWS and where it is a JWE.
	5.1. "typ" (Type) Header Parameter		5.1. "typ" (Type) Header Parameter
	The "typ" (type) Header Parameter defined by [JWS] and [JWE] is used		The "typ" (type) Header Parameter defined by [JWS] and [JWE] is used
	by JWT applications to declare the MIME Media Type [IANA.MediaTypes]		by JWT applications to declare the MIME Media Type [IANA.MediaTypes]
	of this complete JWT. This is intended for use by the JWT		of this complete JWT. This is intended for use by the JWT
	application when values that are not JWTs could also be present in an		application when values that are not JWTs could also be present in an
	application data structure that can contain a JWT object; the		application data structure that can contain a JWT object; the
	application can use this value to disambiguate among the different		application can use this value to disambiguate among the different
	kinds of objects that might be present. It will typically not be		kinds of objects that might be present. It will typically not be
	skipping to change at page 12, line 12 ¶		skipping to change at page 11, line 46 ¶
	instance, in application processing rules to determine whether and		instance, in application processing rules to determine whether and
	how to process the JWT before it is decrypted.		how to process the JWT before it is decrypted.
	This specification allows Claims present in the JWT Claims Set to be		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		replicated as Header Parameters in a JWT that is a JWE, as needed by
	the application. If such replicated Claims are present, the		the application. If such replicated Claims are present, the
	application receiving them SHOULD verify that their values are		application receiving them SHOULD verify that their values are
	identical, unless the application defines other specific processing		identical, unless the application defines other specific processing
	rules for these Claims. It is the responsibility of the application		rules for these Claims. It is the responsibility of the application
	to ensure that only claims that are safe to be transmitted in an		to ensure that only claims that are safe to be transmitted in an
	unencrypted manner are replicated as Header Parameter Values in the		unencrypted manner are replicated as Header Parameter values in the
	JWT.		JWT.
	Section 10.4.1 of this specification registers the "iss" (issuer),		Section 10.4.1 of this specification registers the "iss" (issuer),
	"sub" (subject), and "aud" (audience) Header Parameter Names for the		"sub" (subject), and "aud" (audience) Header Parameter names for the
	purpose of providing unencrypted replicas of these Claims in		purpose of providing unencrypted replicas of these Claims in
	encrypted JWTs for applications that need them. Other specifications		encrypted JWTs for applications that need them. Other specifications
	MAY similarly register other names that are registered Claim Names as		MAY similarly register other names that are registered Claim Names as
	Header Parameter Names, as needed.		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 "alg" Header Parameter value "none" and with
	defined in JSON Web Algorithms (JWA) [JWA]; it is a JWS with the		the empty string for its JWS Signature value, as defined in JSON Web
	empty string for its JWS Signature value.		Algorithms (JWA) [JWA]; it is a Plaintext JWS with the JWT Claims Set
			as its JWS Payload.
	6.1. Example Plaintext JWT		6.1. Example Plaintext JWT
	The following example JWT Header declares that the encoded object is		The following example JOSE Header declares that the encoded object is
	a Plaintext JWT:		a Plaintext JWT:
	{"alg":"none"}		{"alg":"none"}
	Base64url encoding the octets of the UTF-8 representation of the JWT		Base64url encoding the octets of the UTF-8 representation of the JOSE
	Header yields this Encoded JWT Header:		Header yields this Encoded JOSE Header:
	eyJhbGciOiJub25lIn0		eyJhbGciOiJub25lIn0
	The following is an example of a JWT Claims Set:		The following is an example of a JWT Claims Set:
	{"iss":"joe",		{"iss":"joe",
	"exp":1300819380,		"exp":1300819380,
	"http://example.com/is_root":true}		"http://example.com/is_root":true}
	Base64url encoding the octets of the UTF-8 representation of the JWT		Base64url encoding the octets of the UTF-8 representation of the JWT
	skipping to change at page 13, line 34 ¶		skipping to change at page 13, line 24 ¶
	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 need be 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 JOSE 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 need be performed		the representation and no canonicalization need be performed
	before encoding.		before encoding.
	4. Depending upon whether the JWT is a JWS or JWE, there are two		4. 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 Message as the JWS
	JWS Header and the Message as the JWS Payload; all steps		Payload; all steps specified in [JWS] for creating a JWS MUST
	specified in [JWS] for creating a JWS MUST be followed.		be followed.
	* Else, if the JWT is a JWE, create a JWE using the JWT Header		* Else, if the JWT is a JWE, create a JWE using the Message as
	as the JWE Header and the Message as the JWE Plaintext; all		the JWE Plaintext; all steps specified in [JWE] for creating a
	steps specified in [JWE] for creating a JWE MUST be followed.		JWE MUST be followed.
	5. If a nested signing or encryption operation will be performed,		5. If a nested signing or encryption operation will be performed,
	let the Message be the JWS or JWE, and return to Step 3, using a		let the Message be the JWS or JWE, and return to Step 3, using a
	"cty" (content type) value of "JWT" in the new JWT Header created		"cty" (content type) value of "JWT" in the new JOSE Header
	in that step.		created in that step.
	6. Otherwise, let the resulting JWT be the JWS or JWE.		6. Otherwise, let the resulting JWT be the JWS or JWE.
	When validating a JWT, the following steps MUST be taken. The order		When validating a JWT, the following steps MUST be taken. The order
	of the steps is not significant in cases where there are no		of the steps is not significant in cases where there are no
	dependencies between the inputs and outputs of the steps. If any of		dependencies between the inputs and outputs of the steps. If any of
	the listed steps fails then the JWT MUST be rejected for processing.		the listed steps fails then the JWT MUST be rejected for processing.
	1. The JWT MUST contain at least one period ('.') character.		1. The JWT MUST contain at least one period ('.') character.
	2. Let the Encoded JWT Header be the portion of the JWT before the		2. Let the Encoded JOSE Header be the portion of the JWT before the
	first period ('.') character.		first period ('.') character.
	3. The Encoded JWT Header MUST be successfully base64url decoded		3. The Encoded JOSE Header MUST be successfully base64url decoded
	following the restriction given in this specification that no		following the restriction given in this specification that no
	padding characters have been used.		padding characters have been used.
	4. The resulting JWT Header MUST be completely valid JSON syntax		4. The resulting JOSE Header MUST be completely valid JSON syntax
	conforming to [RFC7159].		conforming to [RFC7159].
	5. The resulting JWT Header MUST be validated to only include		5. The resulting JOSE Header MUST be validated to only include
	parameters and values whose syntax and semantics are both		parameters and values whose syntax and semantics are both
	understood and supported or that are specified as being ignored		understood and supported or that are specified as being ignored
	when not understood.		when not understood.
	6. Determine whether the JWT is a JWS or a JWE using any of the		6. Determine whether the JWT is a JWS or a JWE using any of the
	methods described in Section 9 of [JWE].		methods described in Section 9 of [JWE].
	7. Depending upon whether the JWT is a JWS or JWE, there are two		7. Depending upon whether the JWT is a JWS or JWE, there are two
	cases:		cases:
	* If the JWT is a JWS, all steps specified in [JWS] for		* If the JWT is a JWS, all steps specified in [JWS] for
	validating a JWS MUST be followed. Let the Message be the		validating a JWS MUST be followed. Let the Message be the
	result of base64url decoding the JWS Payload.		result of base64url decoding the JWS Payload.
	* Else, if the JWT is a JWE, all steps specified in [JWE] for		* Else, if the JWT is a JWE, all steps specified in [JWE] for
	validating a JWE MUST be followed. Let the Message be the		validating a JWE MUST be followed. Let the Message be the
	JWE Plaintext.		JWE Plaintext.
	8. If the JWT Header contains a "cty" (content type) value of		8. If the JOSE Header contains a "cty" (content type) value of
	"JWT", then the Message is a JWT that was the subject of nested		"JWT", then the Message is a JWT that was the subject of nested
	signing or encryption operations. In this case, return to Step		signing or encryption operations. In this case, return to Step
	1, using the Message as the JWT.		1, using the Message as the JWT.
	9. Otherwise, let the JWT Claims Set be the Message.		9. Otherwise, let the JWT Claims Set be the Message.
	10. The JWT Claims Set MUST be completely valid JSON syntax		10. The JWT Claims Set MUST be completely valid JSON syntax
	conforming to [RFC7159].		conforming to [RFC7159].
	7.1. String Comparison Rules		7.1. String Comparison Rules
	Processing a JWT inevitably requires comparing known strings to		Processing a JWT inevitably requires comparing known strings to
	values in JSON objects. For example, in checking what the algorithm		values in JSON objects. For example, in checking what the algorithm
	is, the Unicode string encoding "alg" will be checked against the		is, the Unicode string encoding "alg" will be checked against the
	member names in the JWT Header to see if there is a matching Header		member names in the JOSE Header to see if there is a matching Header
	Parameter Name.		Parameter name.
	Comparisons between JSON strings and other Unicode strings MUST be		Comparisons between JSON strings and other Unicode strings MUST be
	performed by comparing Unicode code points without normalization, as		performed by comparing Unicode code points without normalization, as
	specified in the String Comparison Rules in Section 5.3 of [JWS].		specified in the String Comparison Rules in Section 5.3 of [JWS].
	8. Implementation Requirements		8. Implementation Requirements
	This section defines which algorithms and features of this		This section defines which algorithms and features of this
	specification are mandatory to implement. Applications using this		specification are mandatory to implement. Applications using this
	specification can impose additional requirements upon implementations		specification can impose additional requirements upon implementations
	skipping to change at page 19, line 17 ¶		skipping to change at page 19, line 4 ¶
	[RFC2046] in the MIME Media Types registry [IANA.MediaTypes], which		[RFC2046] in the MIME Media Types registry [IANA.MediaTypes], which
	can be used to indicate that the content is a JWT.		can be used to indicate that the content is a JWT.
	o Type Name: application		o Type Name: application
	o Subtype Name: jwt		o Subtype Name: jwt
	o Required Parameters: n/a		o Required Parameters: n/a
	o Optional Parameters: n/a		o Optional Parameters: n/a
	o Encoding considerations: 8bit; JWT values are encoded as a series		o Encoding considerations: 8bit; JWT values are encoded as a series
	of base64url encoded values (some of which may be the empty		of base64url encoded values (some of which may be the empty
	string) separated by period ('.') characters.		string) separated by period ('.') characters.
	o Security Considerations: See the Security Considerations section		o Security Considerations: See the Security Considerations section
	of [[ this document ]]		of [[ this document ]]
	o Interoperability Considerations: n/a		o Interoperability Considerations: n/a
	o Published Specification: [[ this document ]]		o Published Specification: [[ this document ]]
	o Applications that use this media type: OpenID Connect, Mozilla		o Applications that use this media type: OpenID Connect, Mozilla
	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: IESG		o Change Controller: IESG
	10.4. Registration of JWE Header Parameter Names		10.4. Header Parameter Names Registration
	This specification registers specific Claim Names defined in		This specification registers specific Claim Names defined in
	Section 4.1 in the IANA JSON Web Signature and Encryption Header		Section 4.1 in the IANA JSON Web Signature and Encryption Header
	Parameters registry defined in [JWS] for use by Claims replicated as		Parameters registry defined in [JWS] for use by Claims replicated as
	Header Parameters, per Section 5.3.		Header Parameters in JWE objects, per Section 5.3.
	10.4.1. Registry Contents		10.4.1. Registry Contents
	o Header Parameter Name: "iss"		o Header Parameter Name: "iss"
	o Header Parameter Description: Issuer		o Header Parameter Description: Issuer
	o Header Parameter Usage Location(s): JWE		o Header Parameter Usage Location(s): JWE
	o Change Controller: IESG		o Change Controller: IESG
	o Specification Document(s): Section 4.1.1 of [[ this document ]]		o Specification Document(s): Section 4.1.1 of [[ this document ]]
	o Header Parameter Name: "sub"		o Header Parameter Name: "sub"
	skipping to change at page 20, line 27 ¶		skipping to change at page 20, line 13 ¶
	protecting the user's asymmetric private and symmetric secret keys,		protecting the user's asymmetric private and symmetric secret keys,
	preventing various attacks, and helping avoid mistakes such as		preventing various attacks, and helping avoid mistakes such as
	inadvertently encrypting a message to the wrong recipient. The		inadvertently encrypting a message to the wrong recipient. The
	entire list of security considerations is beyond the scope of this		entire list of security considerations is beyond the scope of this
	document.		document.
	All the security considerations in the JWS specification also apply		All the security considerations in the JWS specification also apply
	to JWT, as do the JWE security considerations when encryption is		to JWT, as do the JWE security considerations when encryption is
	employed. In particular, the JWS JSON Security Considerations and		employed. In particular, the JWS JSON Security Considerations and
	Unicode Comparison Security Considerations apply equally to the JWT		Unicode Comparison Security Considerations apply equally to the JWT
	Claims Set in the same manner that they do to the JWS Header.		Claims Set in the same manner that they do to the JOSE Header.
	11.1. Trust Decisions		11.1. Trust Decisions
	The contents of a JWT cannot be relied upon in a trust decision		The contents of a JWT cannot be relied upon in a trust decision
	unless its contents have been cryptographically secured and bound to		unless its contents have been cryptographically secured and bound to
	the context necessary for the trust decision. In particular, the		the context necessary for the trust decision. In particular, the
	key(s) used to sign and/or encrypt the JWT will typically need to		key(s) used to sign and/or encrypt the JWT will typically need to
	verifiably be under the control of the party identified as the issuer		verifiably be under the control of the party identified as the issuer
	of the JWT.		of the JWT.
	skipping to change at page 23, line 15 ¶		skipping to change at page 22, line 47 ¶
	Appendix A. JWT Examples		Appendix A. JWT Examples
	This section contains examples of JWTs. For other example JWTs, see		This section contains examples of JWTs. For other example JWTs, see
	Section 6.1 and Appendices A.1, A.2, and A.3 of [JWS].		Section 6.1 and Appendices A.1, A.2, and A.3 of [JWS].
	A.1. Example Encrypted JWT		A.1. Example Encrypted JWT
	This example encrypts the same claims as used in Section 3.1 to the		This example encrypts the same claims as used in Section 3.1 to the
	recipient using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256.		recipient using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256.
	The following example JWE Header (with line breaks for display		The following example JOSE Header declares that:
	purposes only) declares that:
	o the Content Encryption Key is encrypted to the recipient using the		o the Content Encryption Key is encrypted to the recipient using the
	RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and		RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and
	o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256		o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256
	algorithm to produce the Ciphertext.		algorithm to produce the JWE Ciphertext.
	{"alg":"RSA1_5","enc":"A128CBC-HS256"}		{"alg":"RSA1_5","enc":"A128CBC-HS256"}
	Other than using the octets of the UTF-8 representation of the JWT		Other than using the octets of the UTF-8 representation of the JWT
	Claims Set from Section 3.1 as the plaintext value, the computation		Claims Set from Section 3.1 as the plaintext value, the computation
	of this JWT is identical to the computation of the JWE in Appendix		of this JWT is identical to the computation of the JWE in Appendix
	A.2 of [JWE], including the keys used.		A.2 of [JWE], including the keys used.
	The final result in this example (with line breaks for display		The final result in this example (with line breaks for display
	purposes only) is:		purposes only) is:
	skipping to change at page 24, line 10 ¶		skipping to change at page 23, line 41 ¶
	This example shows how a JWT can be used as the payload of a JWE or		This example shows how a JWT can be used as the payload of a JWE or
	JWS to create a Nested JWT. In this case, the JWT Claims Set is		JWS to create a Nested JWT. In this case, the JWT Claims Set is
	first signed, and then encrypted.		first signed, and then encrypted.
	The inner signed JWT is identical to the example in Appendix A.2 of		The inner signed JWT is identical to the example in Appendix A.2 of
	[JWS]. Therefore, its computation is not repeated here. This		[JWS]. Therefore, its computation is not repeated here. This
	example then encrypts this inner JWT to the recipient using RSAES-		example then encrypts this inner JWT to the recipient using RSAES-
	PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256.		PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256.
	The following example JWE Header (with line breaks for display		The following example JOSE Header declares that:
	purposes only) declares that:
	o the Content Encryption Key is encrypted to the recipient using the		o the Content Encryption Key is encrypted to the recipient using the
	RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key,		RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key,
	o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256		o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256
	algorithm to produce the Ciphertext, and		algorithm to produce the JWE Ciphertext, and
	o the Plaintext is itself a JWT.		o the Plaintext is itself a JWT.
	{"alg":"RSA1_5","enc":"A128CBC-HS256","cty":"JWT"}		{"alg":"RSA1_5","enc":"A128CBC-HS256","cty":"JWT"}
	Base64url encoding the octets of the UTF-8 representation of the JWE		Base64url encoding the octets of the UTF-8 representation of the JOSE
	Header yields this encoded JWE Header value:		Header yields this encoded JOSE Header value:
	eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiY3R5IjoiSldUIn0		eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiY3R5IjoiSldUIn0
	The computation of this JWT is identical to the computation of the		The computation of this JWT is identical to the computation of the
	JWE in Appendix A.2 of [JWE], other than that different JWE Header,		JWE in Appendix A.2 of [JWE], other than that different JOSE Header,
	Plaintext, Initialization Vector, and Content Encryption Key values		Plaintext, JWE Initialization Vector, and Content Encryption Key
	are used. (The RSA key used is the same.)		values are used. (The RSA key used is the same.)
	The Payload used is the octets of the ASCII representation of the JWT		The Payload used is the octets of the ASCII representation of the JWT
	at the end of Appendix A.2.1 of [JWS] (with all whitespace and line		at the end of Appendix A.2.1 of [JWS] (with all whitespace and line
	breaks removed), which is a sequence of 458 octets.		breaks removed), which is a sequence of 458 octets.
	The Initialization Vector value used (using JSON array notation) is:		The JWE Initialization Vector value used (using JSON array notation)
			is:
	[82, 101, 100, 109, 111, 110, 100, 32, 87, 65, 32, 57, 56, 48, 53,		[82, 101, 100, 109, 111, 110, 100, 32, 87, 65, 32, 57, 56, 48, 53,
	50]		50]
	This example uses the Content Encryption Key represented by the		This example uses the Content Encryption Key represented by the
	base64url encoded value below:		base64url encoded value below:
	GawgguFyGrWKav7AX4VKUg		GawgguFyGrWKav7AX4VKUg
	The final result for this Nested JWT (with line breaks for display		The final result for this Nested JWT (with line breaks for display
	skipping to change at page 26, line 48 ¶		skipping to change at page 26, line 48 ¶
	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, Stephen Farrell, and Kathleen Moriarty served as		and Sean Turner, Stephen Farrell, and Kathleen Moriarty served as
	Security area directors during the creation of this specification.		Security area directors 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 ]]
			-23
			o Replaced the terms JWS Header, JWE Header, and JWT Header with a
			single JOSE Header term defined in the JWS specification. This
			also enabled a single Header Parameter definition to be used and
			reduced other areas of duplication between specifications.
	-22		-22
	o Revised the introduction to the Security Considerations section.		o Revised the introduction to the Security Considerations section.
	Also introduced subsection headings for security considerations		Also introduced subsection headings for security considerations
	items.		items.
	o Added text about when applications typically would and would not		o Added text about when applications typically would and would not
	use the "typ" header parameter.		use the "typ" header parameter.
	-21		-21
	o Removed unnecessary informative JWK spec reference.		o Removed unnecessary informative JWK spec reference.
End of changes. 51 change blocks.
	112 lines changed or deleted		105 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/