idnits 2.17.1 draft-ietf-oauth-jwt-bearer-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 6, 2012) is 4302 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-18) exists of draft-ietf-oauth-assertions-04 == Outdated reference: A later version (-06) exists of draft-ietf-oauth-urn-sub-ns-05 ** Downref: Normative reference to an Informational draft: draft-ietf-oauth-urn-sub-ns (ref. 'I-D.ietf-oauth-urn-sub-ns') == Outdated reference: A later version (-31) exists of draft-ietf-oauth-v2-28 -- Possible downref: Non-RFC (?) normative reference: ref. 'JWT' ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) == Outdated reference: A later version (-23) exists of draft-ietf-oauth-saml2-bearer-13 Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track B. Campbell 5 Expires: January 7, 2013 Ping Identity 6 C. Mortimore 7 Salesforce 8 July 6, 2012 10 JSON Web Token (JWT) Bearer Token Profiles for OAuth 2.0 11 draft-ietf-oauth-jwt-bearer-01 13 Abstract 15 This specification defines the use of a JSON Web Token (JWT) Bearer 16 Token as a means for requesting an OAuth 2.0 access token as well as 17 for use as a means of client authentication. 19 Status of this Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on January 7, 2013. 36 Copyright Notice 38 Copyright (c) 2012 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 55 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 4 56 2. HTTP Parameter Bindings for Transporting Assertions . . . . . . 4 57 2.1. Using JWTs as Authorization Grants . . . . . . . . . . . . 4 58 2.2. Using JWTs for Client Authentication . . . . . . . . . . . 4 59 3. JWT Format and Processing Requirements . . . . . . . . . . . . 5 60 3.1. Authorization Grant Processing . . . . . . . . . . . . . . 6 61 3.2. Client Authentication Processing . . . . . . . . . . . . . 6 62 4. Authorization Grant Example . . . . . . . . . . . . . . . . . . 6 63 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 64 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 65 6.1. Sub-Namespace Registration of 66 urn:ietf:params:oauth:grant-type:jwt-bearer . . . . . . . . 7 67 6.2. Sub-Namespace Registration of 68 urn:ietf:params:oauth:client-assertion-type:jwt-bearer . . 8 69 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 70 7.1. Normative References . . . . . . . . . . . . . . . . . . . 8 71 7.2. Informative References . . . . . . . . . . . . . . . . . . 9 72 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 9 73 Appendix B. Document History . . . . . . . . . . . . . . . . . . . 9 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9 76 1. Introduction 78 JSON Web Token (JWT) [JWT] is a JavaScript Object Notation (JSON) 79 [RFC4627] based security token encoding that enables identity and 80 security information to be shared across security domains. A 81 security token is generally issued by an identity provider and 82 consumed by a relying party that relies on its content to identify 83 the token's subject for security related purposes. 85 The OAuth 2.0 Authorization Framework [I-D.ietf-oauth-v2] provides a 86 method for making authenticated HTTP requests to a resource using an 87 access token. Access tokens are issued to third-party clients by an 88 authorization server (AS) with the (sometimes implicit) approval of 89 the resource owner. In OAuth, an authorization grant is an abstract 90 term used to describe intermediate credentials that represent the 91 resource owner authorization. An authorization grant is used by the 92 client to obtain an access token. Several authorization grant types 93 are defined to support a wide range of client types and user 94 experiences. OAuth also allows for the definition of new extension 95 grant types to support additional clients or to provide a bridge 96 between OAuth and other trust frameworks. Finally, OAuth allows the 97 definition of additional authentication mechanisms to be used by 98 clients when interacting with the authorization server. 100 The Assertion Framework for OAuth 2.0 [I-D.ietf-oauth-assertions] is 101 an abstract extension to OAuth 2.0 that provides a general framework 102 for the use of Assertions (a.k.a. Security Tokens) as client 103 credentials and/or authorization grants with OAuth 2.0. This 104 specification profiles the Assertion Framework for OAuth 2.0 105 [I-D.ietf-oauth-assertions] to define an extension grant type that 106 uses a JSON Web Token (JWT) Bearer Token to request an OAuth 2.0 107 access token as well as for use as client credentials. The format 108 and processing rules for the JWT defined in this specification are 109 intentionally similar, though not identical, to those in the closely 110 related SAML 2.0 Bearer Assertion Profiles for OAuth 2.0 111 [I-D.ietf-oauth-saml2-bearer]. 113 This document defines how a JSON Web Token (JWT) Bearer Token can be 114 used to request an access token when a client wishes to utilize an 115 existing trust relationship, expressed through the semantics of (and 116 digital signature calculated over) the JWT, without a direct user 117 approval step at the authorization server. It also defines how a JWT 118 can be used as a client authentication mechanism. The use of a 119 security token for client authentication is orthogonal and separable 120 from using a security token as an authorization grant and the two can 121 be used either in combination or in isolation. 123 The process by which the client obtains the JWT, prior to exchanging 124 it with the authorization server or using it for client 125 authentication, is out of scope. 127 1.1. Notational Conventions 129 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 130 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 131 document are to be interpreted as described in RFC 2119 [RFC2119]. 133 Unless otherwise noted, all the protocol parameter names and values 134 are case sensitive. 136 1.2. Terminology 138 All terms are as defined in The OAuth 2.0 Authorization Framework 139 [I-D.ietf-oauth-v2], Assertion Framework for OAuth 2.0 140 [I-D.ietf-oauth-assertions], and JSON Web Token (JWT) [JWT]. 142 2. HTTP Parameter Bindings for Transporting Assertions 144 The Assertion Framework for OAuth 2.0 [I-D.ietf-oauth-assertions] 145 defines generic HTTP parameters for transporting Assertions (a.k.a. 146 Security Tokens) during interactions with a token endpoint. This 147 section defines the values of those parameters for use with JWT 148 Bearer Tokens. 150 2.1. Using JWTs as Authorization Grants 152 To use a JWT Bearer Token as an authorization grant, use the 153 following parameter values and encodings. 155 The value of the "grant_type" parameter MUST be 156 "urn:ietf:params:oauth:grant-type:jwt-bearer". 158 The value of the "assertion" parameter MUST contain a single JWT. 160 2.2. Using JWTs for Client Authentication 162 To use a JWT Bearer Token for client authentication grant, use the 163 following parameter values and encodings. 165 The value of the "client_assertion_type" parameter MUST be 166 "urn:ietf:params:oauth:client-assertion-type:jwt-bearer". 168 The value of the "client_assertion" parameter MUST contain a single 169 JWT. 171 3. JWT Format and Processing Requirements 173 In order to issue an access token response as described in The OAuth 174 2.0 Authorization Framework [I-D.ietf-oauth-v2] or to rely on a JWT 175 for client authentication, the authorization server MUST validate the 176 JWT according to the criteria below. Application of additional 177 restrictions and policy are at the discretion of the authorization 178 server. 180 o The JWT MUST contain an "iss" (issuer) claim that contains a 181 unique identifier for the entity that issued the JWT. 183 o The JWT MUST contain a "prn" (principal) claim identifying the 184 subject of the transaction. The principal MAY identify the 185 resource owner for whom the access token is being requested. For 186 client authentication, the principal MUST be the "client_id" of 187 the OAuth client. When using a JWT as an authorization grant, the 188 principal SHOULD identify an authorized accessor for whom the 189 access token is being requested (typically the resource owner, or 190 an authorized delegate). 192 o The JWT MUST contain an "aud" (audience) claim containing a URI 193 reference that identifies the authorization server, or the service 194 provider principal entity of its controlling domain, as an 195 intended audience. The token endpoint URL of the authorization 196 server MAY be used as an acceptable value for an "aud" element. 197 The authorization server MUST verify that it is an intended 198 audience for the JWT. 200 o The JWT MUST contain an "exp" (expiration) claim that limits the 201 time window during which the JWT can be used. The authorization 202 server MUST verify that the expiration time has not passed, 203 subject to allowable clock skew between systems. The 204 authorization server MAY reject JWTs with an "exp" claim value 205 that is unreasonably far in the future. 207 o The JWT MAY contain an "nbf" (not before) claim that identifies 208 the time before which the token MUST NOT be accepted for 209 processing. 211 o The JWT MAY contain an "iat" (issued at) claim that identifies the 212 time at which the JWT was issued. The authorization server MAY 213 reject JWTs with an "iat" claim value that is unreasonably far in 214 the past. 216 o The JWT MAY contain a "jti" (JWT ID) claim that provides a unique 217 identifier for the token. The authorization server MAY ensure 218 that JWTs are not replayed by maintaining the set of used "jti" 219 values for the length of time for which the JWT would be 220 considered valid based on the applicable "exp" instant. 222 o The JWT MAY contain other claims. 224 o The JWT MUST be digitally signed by the issuer and the 225 authorization server MUST verify the signature. 227 o The authorization server MUST verify that the JWT is valid in all 228 other respects per JSON Web Token (JWT) [JWT]. 230 3.1. Authorization Grant Processing 232 If present, the authorization server MUST also validate the client 233 credentials. 235 If the JWT is not valid, or the current time is not within the 236 token's valid time window for use, the authorization server MUST 237 construct an error response as defined in OAuth 2.0 238 [I-D.ietf-oauth-v2]. The value of the "error" parameter MUST be the 239 "invalid_grant" error code. The authorization server MAY include 240 additional information regarding the reasons the JWT was considered 241 invalid using the "error_description" or "error_uri" parameters. 243 For example: 244 HTTP/1.1 400 Bad Request 245 Content-Type: application/json 246 Cache-Control: no-store 248 { 249 "error":"invalid_grant", 250 "error_description":"Audience validation failed" 251 } 253 3.2. Client Authentication Processing 255 If the client JWT is not valid, or its subject confirmation 256 requirements cannot be met, the authorization server MUST construct 257 an error response as defined in OAuth 2.0 [I-D.ietf-oauth-v2]. The 258 value of the "error" parameter MUST be the "invalid_client" error 259 code. The authorization server MAY include additional information 260 regarding the reasons the JWT was considered invalid using the 261 "error_description" or "error_uri" parameters. 263 4. Authorization Grant Example 265 Though non-normative, the following examples illustrate what a 266 conforming JWT and access token request would look like. 268 Below is an example JSON object that could be encoded to produce the 269 JWT Claims Object for a JWT: 270 {"iss":"https://jwt-idp.example.com", 271 "prn":"mailto:mike@example.com", 272 "aud":"https://jwt-rp.example.net", 273 "nbf":1300815780, 274 "exp":1300819380, 275 "http://claims.example.com/member":true} 277 The following example JSON object, used as the header of a JWT, 278 declares that the JWT is signed with the ECDSA P-256 SHA-256 279 algorithm. 280 {"alg":"ES256"} 282 To present the JWT with the claims and header shown in the previous 283 example as part of an access token request, for example, the client 284 might make the following HTTPS request (with line breaks for display 285 purposes only): 286 POST /token.oauth2 HTTP/1.1 287 Host: authz.example.net 288 Content-Type: application/x-www-form-urlencoded 290 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer 291 &assertion=eyJhbGciOiJFUzI1NiJ9. 292 eyJpc3Mi[...omitted for brevity...]. 293 J9l-ZhwP_2n[...omitted for brevity...] 295 5. Security Considerations 297 No additional security considerations apply beyond those described 298 within The OAuth 2.0 Authorization Framework [I-D.ietf-oauth-v2], the 299 Assertion Framework for OAuth 2.0 [I-D.ietf-oauth-assertions], and 300 the JSON Web Token (JWT) [JWT] specification. 302 6. IANA Considerations 304 6.1. Sub-Namespace Registration of 305 urn:ietf:params:oauth:grant-type:jwt-bearer 307 This specification registers the value "grant-type:jwt-bearer" in the 308 IANA urn:ietf:params:oauth registry established in An IETF URN Sub- 309 Namespace for OAuth [I-D.ietf-oauth-urn-sub-ns]. 311 o URN: urn:ietf:params:oauth:grant-type:jwt-bearer 313 o Common Name: JWT Bearer Token Grant Type Profile for OAuth 2.0 315 o Change controller: IETF 317 o Specification Document: [[this document]] 319 6.2. Sub-Namespace Registration of 320 urn:ietf:params:oauth:client-assertion-type:jwt-bearer 322 This specification registers the value 323 "client-assertion-type:jwt-bearer" in the IANA urn:ietf:params:oauth 324 registry established in An IETF URN Sub-Namespace for OAuth 325 [I-D.ietf-oauth-urn-sub-ns]. 327 o URN: urn:ietf:params:oauth:client-assertion-type:jwt-bearer 329 o Common Name: JWT Bearer Token Profile for OAuth 2.0 Client 330 Authentication 332 o Change controller: IETF 334 o Specification Document: [[this document]] 336 7. References 338 7.1. Normative References 340 [I-D.ietf-oauth-assertions] 341 Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 342 "Assertion Framework for OAuth 2.0", 343 draft-ietf-oauth-assertions-04 (work in progress), 344 July 2012. 346 [I-D.ietf-oauth-urn-sub-ns] 347 Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 348 for OAuth", draft-ietf-oauth-urn-sub-ns-05 (work in 349 progress), June 2012. 351 [I-D.ietf-oauth-v2] 352 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 353 2.0 Authorization Framework", draft-ietf-oauth-v2-28 (work 354 in progress), June 2012. 356 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 357 (JWT)", July 2012. 359 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 360 Requirement Levels", BCP 14, RFC 2119, March 1997. 362 [RFC4627] Crockford, D., "The application/json Media Type for 363 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 365 7.2. Informative References 367 [I-D.ietf-oauth-saml2-bearer] 368 Campbell, B. and C. Mortimore, "SAML 2.0 Bearer Assertion 369 Profiles for OAuth 2.0", draft-ietf-oauth-saml2-bearer-13 370 (work in progress), July 2012. 372 Appendix A. Acknowledgements 374 This profile was derived from SAML 2.0 Bearer Assertion Profiles for 375 OAuth 2.0 [I-D.ietf-oauth-saml2-bearer] by Brian Campbell and Chuck 376 Mortimore. 378 Appendix B. Document History 380 [[ to be removed by the RFC editor before publication as an RFC ]] 382 -01 384 o Tracked specification name changes: "The OAuth 2.0 Authorization 385 Protocol" to "The OAuth 2.0 Authorization Framework" and "OAuth 386 2.0 Assertion Profile" to "Assertion Framework for OAuth 2.0". 388 o Merged in changes between draft-ietf-oauth-saml2-bearer-11 and 389 draft-ietf-oauth-saml2-bearer-13. All changes were strictly 390 editorial. 392 -00 394 o Created the initial IETF draft based upon 395 draft-jones-oauth-jwt-bearer-04 with no normative changes. 397 Authors' Addresses 399 Michael B. Jones 400 Microsoft 402 Email: mbj@microsoft.com 403 URI: http://self-issued.info/ 405 Brian Campbell 406 Ping Identity Corp. 408 Email: brian.d.campbell@gmail.com 410 Chuck Mortimore 411 Salesforce 413 Email: cmortimore@salesforce.com