< draft-sheffer-oauth-jwt-bcp-00.txt		draft-sheffer-oauth-jwt-bcp-01.txt >
	OAuth Working Group Y. Sheffer		OAuth Working Group Y. Sheffer
	Internet-Draft Intuit		Internet-Draft Intuit
	Intended status: Best Current Practice D. Hardt		Intended status: Best Current Practice D. Hardt
	Expires: December 6, 2017 Amazon		Expires: January 4, 2018 Amazon
	M. Jones		M. Jones
	Microsoft		Microsoft
	June 04, 2017		July 03, 2017
	JSON Web Token Best Current Practices		JSON Web Token Best Current Practices
	draft-sheffer-oauth-jwt-bcp-00		draft-sheffer-oauth-jwt-bcp-01
	Abstract		Abstract
	JSON Web Tokens, also known as JWTs [RFC7519], are URL-safe JSON-		JSON Web Tokens, also known as JWTs [RFC7519], are URL-safe JSON-
	based security tokens that contain a set of claims that can be signed		based security tokens that contain a set of claims that can be signed
	and/or encrypted. JWTs are being widely used and deployed as a		and/or encrypted. JWTs are being widely used and deployed as a
	simple security token format in numerous protocols and applications,		simple security token format in numerous protocols and applications,
	both in the area of digital identity, and in other application areas.		both in the area of digital identity, and in other application areas.
	The goal of this Best Current Practices document is to provide		The goal of this Best Current Practices document is to provide
	actionable guidance leading to secure implementation and deployment		actionable guidance leading to secure implementation and deployment
	skipping to change at page 1, line 40 ¶		skipping to change at page 1, line 40 ¶
	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 December 6, 2017.		This Internet-Draft will expire on January 4, 2018.
	Copyright Notice		Copyright Notice
	Copyright (c) 2017 IETF Trust and the persons identified as the		Copyright (c) 2017 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
	skipping to change at page 2, line 25 ¶		skipping to change at page 2, line 25 ¶
	1.2. Conventions used in this document . . . . . . . . . . . . 4		1.2. Conventions used in this document . . . . . . . . . . . . 4
	2. Threats and Vulnerabilities . . . . . . . . . . . . . . . . . 4		2. Threats and Vulnerabilities . . . . . . . . . . . . . . . . . 4
	2.1. Weak Signatures and Insufficient Signature Validation . . 4		2.1. Weak Signatures and Insufficient Signature Validation . . 4
	2.2. Weak symmetric keys . . . . . . . . . . . . . . . . . . . 4		2.2. Weak symmetric keys . . . . . . . . . . . . . . . . . . . 4
	2.3. Multiplicity of JSON encodings . . . . . . . . . . . . . 4		2.3. Multiplicity of JSON encodings . . . . . . . . . . . . . 4
	2.4. Incorrect Composition of Encryption and Signature . . . . 5		2.4. Incorrect Composition of Encryption and Signature . . . . 5
	2.5. Insecure Use of Elliptic Curve Encryption . . . . . . . . 5		2.5. Insecure Use of Elliptic Curve Encryption . . . . . . . . 5
	2.6. Substitution Attacks . . . . . . . . . . . . . . . . . . 5		2.6. Substitution Attacks . . . . . . . . . . . . . . . . . . 5
	2.7. Cross-JWT Confusion . . . . . . . . . . . . . . . . . . . 5		2.7. Cross-JWT Confusion . . . . . . . . . . . . . . . . . . . 5
	3. Best Practices . . . . . . . . . . . . . . . . . . . . . . . 5		3. Best Practices . . . . . . . . . . . . . . . . . . . . . . . 5
	3.1. Perform Algorithm Verification . . . . . . . . . . . . . 5		3.1. Perform Algorithm Verification . . . . . . . . . . . . . 6
	3.2. Use Appropriate Algorithms . . . . . . . . . . . . . . . 6		3.2. Use Appropriate Algorithms . . . . . . . . . . . . . . . 6
	3.3. Validate All Cryptographic Operations . . . . . . . . . . 6		3.3. Validate All Cryptographic Operations . . . . . . . . . . 6
	3.4. Validate Cryptographic Inputs . . . . . . . . . . . . . . 6		3.4. Validate Cryptographic Inputs . . . . . . . . . . . . . . 6
	3.5. Ensure Cryptographic Keys have Sufficient Entropy . . . . 7		3.5. Ensure Cryptographic Keys have Sufficient Entropy . . . . 7
	3.6. Use UTF-8 . . . . . . . . . . . . . . . . . . . . . . . . 7		3.6. Use UTF-8 . . . . . . . . . . . . . . . . . . . . . . . . 7
	3.7. Validate Issuer and Subject . . . . . . . . . . . . . . . 7		3.7. Validate Issuer and Subject . . . . . . . . . . . . . . . 7
	3.8. Use and Validate Audience . . . . . . . . . . . . . . . . 7		3.8. Use and Validate Audience . . . . . . . . . . . . . . . . 7
	3.9. Use Mutually Exclusive Validation Rules for Different		3.9. Use Explicit Typing . . . . . . . . . . . . . . . . . . . 8
			3.10. Use Mutually Exclusive Validation Rules for Different
	Kinds of JWTs . . . . . . . . . . . . . . . . . . . . . . 8		Kinds of JWTs . . . . . . . . . . . . . . . . . . . . . . 8
	4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9		4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
	5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9		5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9
	6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9		6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
	6.1. Normative References . . . . . . . . . . . . . . . . . . 9		6.1. Normative References . . . . . . . . . . . . . . . . . . 9
	6.2. Informative References . . . . . . . . . . . . . . . . . 9		6.2. Informative References . . . . . . . . . . . . . . . . . 10
	Appendix A. Document History . . . . . . . . . . . . . . . . . . 11		Appendix A. Document History . . . . . . . . . . . . . . . . . . 11
	A.1. draft-sheffer-oauth-jwt-bcp-00 . . . . . . . . . . . . . 11		A.1. draft-sheffer-oauth-jwt-bcp-01 . . . . . . . . . . . . . 11
			A.2. draft-sheffer-oauth-jwt-bcp-00 . . . . . . . . . . . . . 11
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11
	1. Introduction		1. Introduction
	JSON Web Tokens, also known as JWTs [RFC7519], are URL-safe JSON-		JSON Web Tokens, also known as JWTs [RFC7519], are URL-safe JSON-
	based security tokens that contain a set of claims that can be signed		based security tokens that contain a set of claims that can be signed
	and/or encrypted. The JWT specification has seen rapid adoption		and/or encrypted. The JWT specification has seen rapid adoption
	because it encapsulates security-relevant information in one, easy to		because it encapsulates security-relevant information in one, easy to
	protect location, and because it is easy to implement using widely-		protect location, and because it is easy to implement using widely-
	available tools. One application area in which JWTs are commonly		available tools. One application area in which JWTs are commonly
	skipping to change at page 5, line 35 ¶		skipping to change at page 5, line 37 ¶
	There are attacks in which one recipient will have a JWT intended for		There are attacks in which one recipient will have a JWT intended for
	it and attempt to use it at a different recipient that it was not		it and attempt to use it at a different recipient that it was not
	intended for. If not caught, these attacks can result in the		intended for. If not caught, these attacks can result in the
	attacker gaining access to resources that it is not entitled to		attacker gaining access to resources that it is not entitled to
	access.		access.
	For mitigations, see Section 3.7 and Section 3.8.		For mitigations, see Section 3.7 and Section 3.8.
	2.7. Cross-JWT Confusion		2.7. Cross-JWT Confusion
	As JWTs are being used by more and more different protocols, it		As JWTs are being used by more different protocols in diverse
	becomes increasingly important to prevent cases of JWT tokens that		application areas, it becomes increasingly important to prevent cases
	have been issued for one purpose being subverted and used for		of JWT tokens that have been issued for one purpose being subverted
	another. Note that this is a specific type of substitution attacks.		and used for another. Note that this is a specific type of
			substitution attack. If the JWT could be used in an application
			context in which it could be confused with other kinds of JWTs, then
			mitigations MUST be employed to prevent these substitution attacks.
	For mitigations, see Section 3.7, Section 3.8, and Section 3.9.		For mitigations, see Section 3.7, Section 3.8, Section 3.9, and
			Section 3.10.
	3. Best Practices		3. Best Practices
	The best practices listed below should be applied by practitioners to		The best practices listed below should be applied by practitioners to
	mitigate the threats listed in the preceding section.		mitigate the threats listed in the preceding section.
	3.1. Perform Algorithm Verification		3.1. Perform Algorithm Verification
	Libraries MUST enable the caller to specify a supported set of		Libraries MUST enable the caller to specify a supported set of
	algorithms and MUST NOT use any other algorithms when performing		algorithms and MUST NOT use any other algorithms when performing
	skipping to change at page 7, line 31 ¶		skipping to change at page 7, line 34 ¶
	When a JWT contains an "iss" (issuer) claim, the application MUST		When a JWT contains an "iss" (issuer) claim, the application MUST
	validate that the cryptographic keys used for the cryptographic		validate that the cryptographic keys used for the cryptographic
	operations in the JWT belong to the issuer. If they do not, the		operations in the JWT belong to the issuer. If they do not, the
	application MUST reject the JWT.		application MUST reject the JWT.
	The means of determining the keys owned by an issuer is application-		The means of determining the keys owned by an issuer is application-
	specific. As one example, OpenID Connect [OpenID.Core] issuer values		specific. As one example, OpenID Connect [OpenID.Core] issuer values
	are "https" URLs that reference a JSON metadata document that		are "https" URLs that reference a JSON metadata document that
	contains a "jwks_uri" value that is an "https" URL from which the		contains a "jwks_uri" value that is an "https" URL from which the
	issuer's keys are retrieved as a JWK Set [RFC7517]. This same		issuer's keys are retrieved as a JWK Set [RFC7517]. This same
	mechanism is used by [OAuth.Metadata]. Other applications may use		mechanism is used by [I-D.ietf-oauth-discovery]. Other applications
	different means of binding keys to issuers.		may use different means of binding keys to issuers.
	Similarly, when the JWT contains a "sub" (subject) claim, the		Similarly, when the JWT contains a "sub" (subject) claim, the
	application MUST validate that the subject value corresponds to a		application MUST validate that the subject value corresponds to a
	valid subject and/or issuer/subject pair at the application. This		valid subject and/or issuer/subject pair at the application. This
	may include confirming that the issuer is trusted by the application.		may include confirming that the issuer is trusted by the application.
	If the issuer, subject, or the pair are invalid, the application MUST		If the issuer, subject, or the pair are invalid, the application MUST
	reject the JWT.		reject the JWT.
	3.8. Use and Validate Audience		3.8. Use and Validate Audience
	If the same issuer can issue JWTs that are intended for use by more		If the same issuer can issue JWTs that are intended for use by more
	than one relying party or application, the JWT MUST contain an "aud"		than one relying party or application, the JWT MUST contain an "aud"
	(audience) claim that can be used to determine whether the JWT is		(audience) claim that can be used to determine whether the JWT is
	being used by an intended party or was substituted by an attacker at		being used by an intended party or was substituted by an attacker at
	an unintended party. Furthermore, the relying party or application		an unintended party. Furthermore, the relying party or application
	MUST validate the audience value and if the audience value is not		MUST validate the audience value and if the audience value is not
	associated with the recipient, it MUST reject the JWT.		associated with the recipient, it MUST reject the JWT.
	3.9. Use Mutually Exclusive Validation Rules for Different Kinds of		3.9. Use Explicit Typing
	JWTs
	NOTE: A goal of this BCP is to recommend specific best practices for		Confusion of one kind of JWT for another can be prevented by having
	applications of JWTs to apply. The strategies listed below are some		all the kinds of JWTs that could otherwise potentially be confused
	of the options available to these applications. The authors request		include an explicit JWT type value and include checking the type
	input from the OAuth working group and other interested parties on		value in their validation rules. Explicit JWT typing is accomplished
	which of these strategies or which combinations should be considered		by using the "typ" header parameter. For instance, the
	to be best practices in which contexts. Descriptions of other		[I-D.ietf-secevent-token] specification uses the "application/
	practical strategies not listed below are also solicited.		secevent+jwt" media type to perform explicit typing of Security Event
			Tokens (SETs).
			Per the definition of "typ" in Section 4.1.9 of [RFC7515], it is
			RECOMMENDED that the "application/" prefix be omitted from the "typ"
			value. Therefore, for example, the "typ" value used to explicitly
			include a type for a SET SHOULD be "secevent+jwt". When explicit
			typing is employed for a JWT, it is RECOMMENDED that a media type
			name of the format "application/example+jwt" be used, where "example"
			is replaced by the identifier for the specific kind of JWT.
			Note that the use of explicit typing may not achieve disambiguation
			from existing kinds of JWTs, as the validation rules for existing
			kinds JWTs often do not use the "typ" header parameter value.
			Explicit typing is RECOMMENDED for new uses of JWTs.
			3.10. Use Mutually Exclusive Validation Rules for Different Kinds of
			JWTs
	Each application of JWTs defines a profile specifying the required		Each application of JWTs defines a profile specifying the required
	and optional JWT claims and the validation rules associated with		and optional JWT claims and the validation rules associated with
	them. If more than one kind of JWT can be issued by the same issuer,		them. If more than one kind of JWT can be issued by the same issuer,
	the validation rules for those JWTs MUST be written such that they		the validation rules for those JWTs MUST be written such that they
	are mutually exclusive, rejecting JWTs of the wrong kind. To prevent		are mutually exclusive, rejecting JWTs of the wrong kind. To prevent
	substitution of JWTs from one context into another, a number of		substitution of JWTs from one context into another, a number of
	strategies may be employed:		strategies may be employed:
			- Use explicit typing for different kinds of JWTs. Then the
			distinct "typ" values can be used to differentiate between the
			different kinds of JWTs.
	- Use different sets of required claims or different required claim		- Use different sets of required claims or different required claim
	values. Then the validation rules for one kind of JWT will reject		values. Then the validation rules for one kind of JWT will reject
	those with different claims or values.		those with different claims or values.
	- Use different sets of required header parameters or different		- Use different sets of required header parameters or different
	required header parameter values. Then the validation rules for		required header parameter values. Then the validation rules for
	one kind of JWT will reject those with different header parameters		one kind of JWT will reject those with different header parameters
	or values.		or values.
	- Use different keys for different kinds of JWTs. Then the keys		- Use different keys for different kinds of JWTs. Then the keys
	skipping to change at page 8, line 46 ¶		skipping to change at page 9, line 20 ¶
	- Use different "aud" values for different uses of JWTs from the		- Use different "aud" values for different uses of JWTs from the
	same issuer. Then audience validation will reject JWTs		same issuer. Then audience validation will reject JWTs
	substituted into inappropriate contexts.		substituted into inappropriate contexts.
	- Use different issuers for different kinds of JWTs. Then the		- Use different issuers for different kinds of JWTs. Then the
	distinct "iss" values can be used to segregate the different kinds		distinct "iss" values can be used to segregate the different kinds
	of JWTs.		of JWTs.
	Given the broad diversity of JWT usage and applications, the best		Given the broad diversity of JWT usage and applications, the best
	combination of required claims, values, header parameters, key		combination of types, required claims, values, header parameters, key
	usages, and issuers to differentiate among different kinds of JWTs		usages, and issuers to differentiate among different kinds of JWTs
	will, in general, be application specific.		will, in general, be application specific.
	4. IANA Considerations		4. IANA Considerations
	This document requires no IANA actions.		This document requires no IANA actions.
	5. Acknowledgements		5. Acknowledgements
	Thanks to Antonio Sanso for bringing the "ECDH-ES" invalid point		Thanks to Antonio Sanso for bringing the "ECDH-ES" invalid point
	attack to the attention of JWE and JWT implementers.		attack to the attention of JWE and JWT implementers. Thanks to Nat
			Sakimura for advocating the use of explicit typing.
	6. References		6. References
	6.1. Normative References		6.1. Normative References
	[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate		[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
	Requirement Levels", BCP 14, RFC 2119,		Requirement Levels", BCP 14, RFC 2119,
	DOI 10.17487/RFC2119, March 1997,		DOI 10.17487/RFC2119, March 1997,
	<http://www.rfc-editor.org/info/rfc2119>.		<http://www.rfc-editor.org/info/rfc2119>.
	skipping to change at page 9, line 45 ¶		skipping to change at page 10, line 19 ¶
	[RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,		[RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,
	DOI 10.17487/RFC7518, May 2015,		DOI 10.17487/RFC7518, May 2015,
	<http://www.rfc-editor.org/info/rfc7518>.		<http://www.rfc-editor.org/info/rfc7518>.
	[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token		[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
	(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,		(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
	<http://www.rfc-editor.org/info/rfc7519>.		<http://www.rfc-editor.org/info/rfc7519>.
	6.2. Informative References		6.2. Informative References
			[I-D.ietf-oauth-discovery]
			Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
			Authorization Server Metadata", draft-ietf-oauth-
			discovery-06 (work in progress), March 2017.
			[I-D.ietf-secevent-token]
			Hunt, P., Denniss, W., Ansari, M., and M. Jones, "Security
			Event Token (SET)", draft-ietf-secevent-token-02 (work in
			progress), June 2017.
	[Langkemper]		[Langkemper]
	Langkemper, S., "Attacking JWT Authentication", September		Langkemper, S., "Attacking JWT Authentication", September
	2016, <https://www.sjoerdlangkemper.nl/2016/09/28/		2016, <https://www.sjoerdlangkemper.nl/2016/09/28/
	attacking-jwt-authentication/>.		attacking-jwt-authentication/>.
	[OAuth.Metadata]
	Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
	Authorization Server Metadata", March 2017,
	<http://tools.ietf.org/html/
	draft-ietf-oauth-discovery-06>.
	[OpenID.Core]		[OpenID.Core]
	Sakimura, N., Bradley, J., Jones, M., Medeiros, B., and C.		Sakimura, N., Bradley, J., Jones, M., Medeiros, B., and C.
	Mortimore, "OpenID Connect Core 1.0", November 2014,		Mortimore, "OpenID Connect Core 1.0", November 2014,
	<http://openid.net/specs/openid-connect-core-1_0.html>.		<http://openid.net/specs/openid-connect-core-1_0.html>.
	[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",		[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
	RFC 6749, DOI 10.17487/RFC6749, October 2012,		RFC 6749, DOI 10.17487/RFC6749, October 2012,
	<http://www.rfc-editor.org/info/rfc6749>.		<http://www.rfc-editor.org/info/rfc6749>.
	[RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517,		[RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517,
	skipping to change at page 11, line 9 ¶		skipping to change at page 11, line 9 ¶
	[Sanso] Sanso, A., "Critical Vulnerability Uncovered in JSON		[Sanso] Sanso, A., "Critical Vulnerability Uncovered in JSON
	Encryption", March 2017,		Encryption", March 2017,
	<https://blogs.adobe.com/security/2017/03/critical-		<https://blogs.adobe.com/security/2017/03/critical-
	vulnerability-uncovered-in-json-encryption.html>.		vulnerability-uncovered-in-json-encryption.html>.
	Appendix A. Document History		Appendix A. 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 ]]
	A.1. draft-sheffer-oauth-jwt-bcp-00		A.1. draft-sheffer-oauth-jwt-bcp-01
			- Added explicit typing.
			A.2. draft-sheffer-oauth-jwt-bcp-00
	- Initial version.		- Initial version.
	Authors' Addresses		Authors' Addresses
	Yaron Sheffer		Yaron Sheffer
	Intuit		Intuit
	EMail: yaronf.ietf@gmail.com		EMail: yaronf.ietf@gmail.com
End of changes. 19 change blocks.
	33 lines changed or deleted		68 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/