draft-ietf-oauth-jwt-bearer-01.txt		draft-ietf-oauth-jwt-bearer-02.txt
	OAuth Working Group M. Jones		OAuth Working Group M. Jones
	Internet-Draft Microsoft		Internet-Draft Microsoft
	Intended status: Standards Track B. Campbell		Intended status: Standards Track B. Campbell
	Expires: January 7, 2013 Ping Identity		Expires: March 18, 2013 Ping Identity
	C. Mortimore		C. Mortimore
	Salesforce		Salesforce
	July 6, 2012		September 14, 2012
	JSON Web Token (JWT) Bearer Token Profiles for OAuth 2.0		JSON Web Token (JWT) Bearer Token Profiles for OAuth 2.0
	draft-ietf-oauth-jwt-bearer-01		draft-ietf-oauth-jwt-bearer-02
	Abstract		Abstract
	This specification defines the use of a JSON Web Token (JWT) Bearer		This specification defines the use of a JSON Web Token (JWT) Bearer
	Token as a means for requesting an OAuth 2.0 access token as well as		Token as a means for requesting an OAuth 2.0 access token as well as
	for use as a means of client authentication.		for use as a means of client authentication.
	Status of this Memo		Status of this Memo
	This Internet-Draft is submitted in full conformance with the		This Internet-Draft is submitted in full conformance with the
	skipping to change at page 1, line 35		skipping to change at page 1, line 35
	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 7, 2013.		This Internet-Draft will expire on March 18, 2013.
	Copyright Notice		Copyright Notice
	Copyright (c) 2012 IETF Trust and the persons identified as the		Copyright (c) 2012 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
	1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4		1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4
	1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 4		1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
	2. HTTP Parameter Bindings for Transporting Assertions . . . . . . 4		2. HTTP Parameter Bindings for Transporting Assertions . . . . . 4
	2.1. Using JWTs as Authorization Grants . . . . . . . . . . . . 4		2.1. Using JWTs as Authorization Grants . . . . . . . . . . . . 4
	2.2. Using JWTs for Client Authentication . . . . . . . . . . . 4		2.2. Using JWTs for Client Authentication . . . . . . . . . . . 5
	3. JWT Format and Processing Requirements . . . . . . . . . . . . 5		3. JWT Format and Processing Requirements . . . . . . . . . . . . 5
	3.1. Authorization Grant Processing . . . . . . . . . . . . . . 6		3.1. Authorization Grant Processing . . . . . . . . . . . . . . 7
	3.2. Client Authentication Processing . . . . . . . . . . . . . 6		3.2. Client Authentication Processing . . . . . . . . . . . . . 7
	4. Authorization Grant Example . . . . . . . . . . . . . . . . . . 6		4. Authorization Grant Example . . . . . . . . . . . . . . . . . 7
	5. Security Considerations . . . . . . . . . . . . . . . . . . . . 7		5. Security Considerations . . . . . . . . . . . . . . . . . . . 8
	6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7		6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
	6.1. Sub-Namespace Registration of		6.1. Sub-Namespace Registration of
	urn:ietf:params:oauth:grant-type:jwt-bearer . . . . . . . . 7		urn:ietf:params:oauth:grant-type:jwt-bearer . . . . . . . 8
	6.2. Sub-Namespace Registration of		6.2. Sub-Namespace Registration of
	urn:ietf:params:oauth:client-assertion-type:jwt-bearer . . 8		urn:ietf:params:oauth:client-assertion-type:jwt-bearer . . 9
	7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8		7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9
	7.1. Normative References . . . . . . . . . . . . . . . . . . . 8		7.1. Normative References . . . . . . . . . . . . . . . . . . . 9
	7.2. Informative References . . . . . . . . . . . . . . . . . . 9		7.2. Informative References . . . . . . . . . . . . . . . . . . 10
	Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 9		Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10
	Appendix B. Document History . . . . . . . . . . . . . . . . . . . 9		Appendix B. Document History . . . . . . . . . . . . . . . . . . 10
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11
	1. Introduction		1. Introduction
	JSON Web Token (JWT) [JWT] is a JavaScript Object Notation (JSON)		JSON Web Token (JWT) [JWT] is a JavaScript Object Notation (JSON)
	[RFC4627] based security token encoding that enables identity and		[RFC4627] based security token encoding that enables identity and
	security information to be shared across security domains. A		security information to be shared across security domains. A
	security token is generally issued by an identity provider and		security token is generally issued by an identity provider and
	consumed by a relying party that relies on its content to identify		consumed by a relying party that relies on its content to identify
	the token's subject for security related purposes.		the token's subject for security related purposes.
	skipping to change at page 3, line 48		skipping to change at page 3, line 48
	intentionally similar, though not identical, to those in the closely		intentionally similar, though not identical, to those in the closely
	related SAML 2.0 Bearer Assertion Profiles for OAuth 2.0		related SAML 2.0 Bearer Assertion Profiles for OAuth 2.0
	[I-D.ietf-oauth-saml2-bearer].		[I-D.ietf-oauth-saml2-bearer].
	This document defines how a JSON Web Token (JWT) Bearer Token can be		This document defines how a JSON Web Token (JWT) Bearer Token can be
	used to request an access token when a client wishes to utilize an		used to request an access token when a client wishes to utilize an
	existing trust relationship, expressed through the semantics of (and		existing trust relationship, expressed through the semantics of (and
	digital signature calculated over) the JWT, without a direct user		digital signature calculated over) the JWT, without a direct user
	approval step at the authorization server. It also defines how a JWT		approval step at the authorization server. It also defines how a JWT
	can be used as a client authentication mechanism. The use of a		can be used as a client authentication mechanism. The use of a
	security token for client authentication is orthogonal and separable		security token for client authentication is orthogonal to and
	from using a security token as an authorization grant and the two can		separable from using a security token as an authorization grant.
	be used either in combination or in isolation.		They can be used either in combination or separately. Client
			authentication using a JWT is nothing more than an alternative way
			for a client to authenticate to the token endpoint and must be used
			in conjunction with some grant type to form a complete and meaningful
			protocol request. JWT authorization grants may be used with or
			without client authentication or identification. Whether or not
			client authentication is needed in conjunction with a JWT
			authorization grant, as well as the supported types of client
			authentication, are policy decisions at the discretion of the
			authorization server.
	The process by which the client obtains the JWT, prior to exchanging		The process by which the client obtains the JWT, prior to exchanging
	it with the authorization server or using it for client		it with the authorization server or using it for client
	authentication, is out of scope.		authentication, is out of scope.
	1.1. Notational Conventions		1.1. Notational Conventions
	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",		The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
	"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this		"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
	document are to be interpreted as described in RFC 2119 [RFC2119].		document are to be interpreted as described in RFC 2119 [RFC2119].
	skipping to change at page 4, line 40		skipping to change at page 4, line 49
	2.1. Using JWTs as Authorization Grants		2.1. Using JWTs as Authorization Grants
	To use a JWT Bearer Token as an authorization grant, use the		To use a JWT Bearer Token as an authorization grant, use the
	following parameter values and encodings.		following parameter values and encodings.
	The value of the "grant_type" parameter MUST be		The value of the "grant_type" parameter MUST be
	"urn:ietf:params:oauth:grant-type:jwt-bearer".		"urn:ietf:params:oauth:grant-type:jwt-bearer".
	The value of the "assertion" parameter MUST contain a single JWT.		The value of the "assertion" parameter MUST contain a single JWT.
			The following non-normative example demonstrates an Access Token
			Request with a JWT as an authorization grant (with extra line breaks
			for display purposes only):
			POST /token.oauth2 HTTP/1.1
			Host: as.example.com
			Content-Type: application/x-www-form-urlencoded
			grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
			&assertion=eyJhbGciOiJFUzI1NiJ9.
			eyJpc3Mi[...omitted for brevity...].
			J9l-ZhwP[...omitted for brevity...]
	2.2. Using JWTs for Client Authentication		2.2. Using JWTs for Client Authentication
	To use a JWT Bearer Token for client authentication grant, use the		To use a JWT Bearer Token for client authentication grant, use the
	following parameter values and encodings.		following parameter values and encodings.
	The value of the "client_assertion_type" parameter MUST be		The value of the "client_assertion_type" parameter MUST be
	"urn:ietf:params:oauth:client-assertion-type:jwt-bearer".		"urn:ietf:params:oauth:client-assertion-type:jwt-bearer".
	The value of the "client_assertion" parameter MUST contain a single		The value of the "client_assertion" parameter MUST contain a single
	JWT.		JWT.
			The following non-normative example demonstrates client
			authentication using a JWT during the presentation of an
			authorization code grant in an Access Token Request (with extra line
			breaks for display purposes only):
			POST /token.oauth2 HTTP/1.1
			Host: as.example.com
			Content-Type: application/x-www-form-urlencoded
			grant_type=authorization_code&
			code=vAZEIHjQTHuGgaSvyW9hO0RpusLzkvTOww3trZBxZpo&
			client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3A
			client-assertion-type%3Ajwt-bearer&
			client_assertion=eyJhbGciOiJSUzI1NiJ9.
			eyJpc3Mi[...omitted for brevity...].
			cC4hiUPo[...omitted for brevity...]
	3. JWT Format and Processing Requirements		3. JWT Format and Processing Requirements
	In order to issue an access token response as described in The OAuth		In order to issue an access token response as described in The OAuth
	2.0 Authorization Framework [I-D.ietf-oauth-v2] or to rely on a JWT		2.0 Authorization Framework [I-D.ietf-oauth-v2] or to rely on a JWT
	for client authentication, the authorization server MUST validate the		for client authentication, the authorization server MUST validate the
	JWT according to the criteria below. Application of additional		JWT according to the criteria below. Application of additional
	restrictions and policy are at the discretion of the authorization		restrictions and policy are at the discretion of the authorization
	server.		server.
	o The JWT MUST contain an "iss" (issuer) claim that contains a		o The JWT MUST contain an "iss" (issuer) claim that contains a
	skipping to change at page 6, line 29		skipping to change at page 7, line 22
	If the JWT is not valid, or the current time is not within the		If the JWT is not valid, or the current time is not within the
	token's valid time window for use, the authorization server MUST		token's valid time window for use, the authorization server MUST
	construct an error response as defined in OAuth 2.0		construct an error response as defined in OAuth 2.0
	[I-D.ietf-oauth-v2]. The value of the "error" parameter MUST be the		[I-D.ietf-oauth-v2]. The value of the "error" parameter MUST be the
	"invalid_grant" error code. The authorization server MAY include		"invalid_grant" error code. The authorization server MAY include
	additional information regarding the reasons the JWT was considered		additional information regarding the reasons the JWT was considered
	invalid using the "error_description" or "error_uri" parameters.		invalid using the "error_description" or "error_uri" parameters.
	For example:		For example:
	HTTP/1.1 400 Bad Request
	Content-Type: application/json
	Cache-Control: no-store
	{		HTTP/1.1 400 Bad Request
	"error":"invalid_grant",		Content-Type: application/json
	"error_description":"Audience validation failed"		Cache-Control: no-store
	}
			{
			"error":"invalid_grant",
			"error_description":"Audience validation failed"
			}
	3.2. Client Authentication Processing		3.2. Client Authentication Processing
	If the client JWT is not valid, or its subject confirmation		If the client JWT is not valid, or its subject confirmation
	requirements cannot be met, the authorization server MUST construct		requirements cannot be met, the authorization server MUST construct
	an error response as defined in OAuth 2.0 [I-D.ietf-oauth-v2]. The		an error response as defined in OAuth 2.0 [I-D.ietf-oauth-v2]. The
	value of the "error" parameter MUST be the "invalid_client" error		value of the "error" parameter MUST be the "invalid_client" error
	code. The authorization server MAY include additional information		code. The authorization server MAY include additional information
	regarding the reasons the JWT was considered invalid using the		regarding the reasons the JWT was considered invalid using the
	"error_description" or "error_uri" parameters.		"error_description" or "error_uri" parameters.
	4. Authorization Grant Example		4. Authorization Grant Example
	Though non-normative, the following examples illustrate what a		Though non-normative, the following examples illustrate what a
	conforming JWT and access token request would look like.		conforming JWT and access token request would look like.
	Below is an example JSON object that could be encoded to produce the		Below is an example JSON object that could be encoded to produce the
	JWT Claims Object for a JWT:		JWT Claims Object for a JWT:
	{"iss":"https://jwt-idp.example.com",
	"prn":"mailto:mike@example.com",		{"iss":"https://jwt-idp.example.com",
	"aud":"https://jwt-rp.example.net",		"prn":"mailto:mike@example.com",
	"nbf":1300815780,		"aud":"https://jwt-rp.example.net",
	"exp":1300819380,		"nbf":1300815780,
	"http://claims.example.com/member":true}		"exp":1300819380,
			"http://claims.example.com/member":true}
	The following example JSON object, used as the header of a JWT,		The following example JSON object, used as the header of a JWT,
	declares that the JWT is signed with the ECDSA P-256 SHA-256		declares that the JWT is signed with the ECDSA P-256 SHA-256
	algorithm.		algorithm.
	{"alg":"ES256"}
			{"alg":"ES256"}
	To present the JWT with the claims and header shown in the previous		To present the JWT with the claims and header shown in the previous
	example as part of an access token request, for example, the client		example as part of an access token request, for example, the client
	might make the following HTTPS request (with line breaks for display		might make the following HTTPS request (with extra line breaks for
	purposes only):		display purposes only):
	POST /token.oauth2 HTTP/1.1
	Host: authz.example.net
	Content-Type: application/x-www-form-urlencoded
	grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer		POST /token.oauth2 HTTP/1.1
	&assertion=eyJhbGciOiJFUzI1NiJ9.		Host: authz.example.net
	eyJpc3Mi[...omitted for brevity...].		Content-Type: application/x-www-form-urlencoded
	J9l-ZhwP_2n[...omitted for brevity...]
			grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
			&assertion=eyJhbGciOiJFUzI1NiJ9.
			eyJpc3Mi[...omitted for brevity...].
			J9l-ZhwP[...omitted for brevity...]
	5. Security Considerations		5. Security Considerations
	No additional security considerations apply beyond those described		No additional security considerations apply beyond those described
	within The OAuth 2.0 Authorization Framework [I-D.ietf-oauth-v2], the		within The OAuth 2.0 Authorization Framework [I-D.ietf-oauth-v2], the
	Assertion Framework for OAuth 2.0 [I-D.ietf-oauth-assertions], and		Assertion Framework for OAuth 2.0 [I-D.ietf-oauth-assertions], and
	the JSON Web Token (JWT) [JWT] specification.		the JSON Web Token (JWT) [JWT] specification.
	6. IANA Considerations		6. IANA Considerations
	skipping to change at page 9, line 28		skipping to change at page 10, line 28
	Appendix A. Acknowledgements		Appendix A. Acknowledgements
	This profile was derived from SAML 2.0 Bearer Assertion Profiles for		This profile was derived from SAML 2.0 Bearer Assertion Profiles for
	OAuth 2.0 [I-D.ietf-oauth-saml2-bearer] by Brian Campbell and Chuck		OAuth 2.0 [I-D.ietf-oauth-saml2-bearer] by Brian Campbell and Chuck
	Mortimore.		Mortimore.
	Appendix B. Document History		Appendix B. 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 ]]
			-02
			o Add more text to intro explaining that an assertion/JWT grant type
			can be used with or without client authentication/identification
			and that client assertion/JWT authentication is nothing more than
			an alternative way for a client to authenticate to the token
			endpoint
			o Add examples to Sections 2.1 and 2.2
			o Update references
	-01		-01
	o Tracked specification name changes: "The OAuth 2.0 Authorization		o Tracked specification name changes: "The OAuth 2.0 Authorization
	Protocol" to "The OAuth 2.0 Authorization Framework" and "OAuth		Protocol" to "The OAuth 2.0 Authorization Framework" and "OAuth
	2.0 Assertion Profile" to "Assertion Framework for OAuth 2.0".		2.0 Assertion Profile" to "Assertion Framework for OAuth 2.0".
	o Merged in changes between draft-ietf-oauth-saml2-bearer-11 and		o Merged in changes between draft-ietf-oauth-saml2-bearer-11 and
	draft-ietf-oauth-saml2-bearer-13. All changes were strictly		draft-ietf-oauth-saml2-bearer-13. All changes were strictly
	editorial.		editorial.
End of changes. 17 change blocks.
	50 lines changed or deleted		105 lines changed or added
This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/