idnits 2.17.1 draft-jones-oauth-jwt-bearer-04.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 (April 26, 2012) is 4380 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-02 == Outdated reference: A later version (-06) exists of draft-ietf-oauth-urn-sub-ns-02 ** 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-25 -- 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-11 Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track B. Campbell 5 Expires: October 28, 2012 Ping Identity 6 C. Mortimore 7 Salesforce 8 April 26, 2012 10 JSON Web Token (JWT) Bearer Token Profiles for OAuth 2.0 11 draft-jones-oauth-jwt-bearer-04 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 October 28, 2012. 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 . . . . . . . . . . . . . . . . . . . . . . . . 10 76 1. Introduction 78 JSON Web Token (JWT) [JWT] is a JSON-based security token encoding 79 that enables identity and security information to be shared across 80 security domains. JWTs utilize JSON data structures, as defined in 81 RFC 4627 [RFC4627]. A security token is generally issued by an 82 identity provider and consumed by a relying party that relies on its 83 content to identify the token's subject for security related 84 purposes. 86 The OAuth 2.0 Authorization Protocol [I-D.ietf-oauth-v2] provides a 87 method for making authenticated HTTP requests to a resource using an 88 access token. Access tokens are issued to third-party clients by an 89 authorization server (AS) with the (sometimes implicit) approval of 90 the resource owner. In OAuth, an authorization grant is an abstract 91 term used to describe intermediate credentials that represent the 92 resource owner authorization. An authorization grant is used by the 93 client to obtain an access token. Several authorization grant types 94 are defined to support a wide range of client types and user 95 experiences. OAuth also allows for the definition of new extension 96 grant types to support additional clients or to provide a bridge 97 between OAuth and other trust frameworks. Finally, OAuth allows the 98 definition of additional authentication mechanisms to be used by 99 clients when interacting with the authorization server. 101 The OAuth 2.0 Assertion Profile [I-D.ietf-oauth-assertions] is an 102 abstract extension to OAuth 2.0 that provides a general framework for 103 the use of Assertions (a.k.a. Security Tokens) as client credentials 104 and/or authorization grants with OAuth 2.0. This specification 105 profiles the OAuth 2.0 Assertion Profile [I-D.ietf-oauth-assertions] 106 to define an extension grant type that uses a JSON Web Token (JWT) 107 Bearer Token to request an OAuth 2.0 access token as well as for use 108 as client credentials. The format and processing rules for the JWT 109 defined in this specification are intentionally similar, though not 110 identical, to those in the closely related SAML 2.0 Bearer Assertion 111 Profiles for OAuth 2.0 [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 Protocol 139 [I-D.ietf-oauth-v2], OAuth 2.0 Assertion Profile 140 [I-D.ietf-oauth-assertions], and JSON Web Token (JWT) [JWT]. 142 2. HTTP Parameter Bindings for Transporting Assertions 144 The OAuth 2.0 Assertion Profile [I-D.ietf-oauth-assertions] defines 145 generic HTTP parameters for transporting Assertions (a.k.a. Security 146 Tokens) during interactions with a token endpoint. This section 147 defines the values of those parameters for use with JWT Bearer 148 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 Protocol [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 Protocol [I-D.ietf-oauth-v2], the 299 OAuth 2.0 Assertion Profile [I-D.ietf-oauth-assertions], and the JSON 300 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 is a request to IANA to please register the value 308 "grant-type:jwt-bearer" in the registry urn:ietf:params:oauth 309 established in An IETF URN Sub-Namespace for OAuth 310 [I-D.ietf-oauth-urn-sub-ns]. 312 o URN: urn:ietf:params:oauth:grant-type:jwt-bearer 314 o Common Name: JWT Bearer Token Grant Type Profile for OAuth 2.0 316 o Change controller: IETF 318 o Description: [[this document]] 320 6.2. Sub-Namespace Registration of 321 urn:ietf:params:oauth:client-assertion-type:jwt-bearer 323 This is a request to IANA to please register the value 324 "client-assertion-type:jwt-bearer" in the registry 325 urn:ietf:params:oauth established in An IETF URN Sub-Namespace for 326 OAuth [I-D.ietf-oauth-urn-sub-ns]. 328 o URN: urn:ietf:params:oauth:client-assertion-type:jwt-bearer 330 o Common Name: JWT Bearer Token Profile for OAuth 2.0 Client 331 Authentication 333 o Change controller: IETF 335 o Description: [[this document]] 337 7. References 339 7.1. Normative References 341 [I-D.ietf-oauth-assertions] 342 Mortimore, C., Ed., Jones, M., Campbell, B., and Y. 343 Goland, "OAuth 2.0 Assertion Profile", 344 draft-ietf-oauth-assertions-02 (work in progress), 345 April 2012. 347 [I-D.ietf-oauth-urn-sub-ns] 348 Tschofenig, H., "An IETF URN Sub-Namespace for OAuth", 349 draft-ietf-oauth-urn-sub-ns-02 (work in progress), 350 January 2012. 352 [I-D.ietf-oauth-v2] 353 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 354 2.0 Authorization Protocol", draft-ietf-oauth-v2-25 (work 355 in progress), March 2012. 357 [JWT] Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, 358 J., Sakimura, N., and P. Tarjan, "JSON Web Token (JWT)", 359 March 2012. 361 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 362 Requirement Levels", BCP 14, RFC 2119, March 1997. 364 [RFC4627] Crockford, D., "The application/json Media Type for 365 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 367 7.2. Informative References 369 [I-D.ietf-oauth-saml2-bearer] 370 Campbell, B., Ed. and C. Mortimore, "SAML 2.0 Bearer 371 Assertion Profiles for OAuth 2.0", 372 draft-ietf-oauth-saml2-bearer-11 (work in progress), 373 April 2012. 375 Appendix A. Acknowledgements 377 This profile was derived from SAML 2.0 Bearer Assertion Profiles for 378 OAuth 2.0 [I-D.ietf-oauth-saml2-bearer] by Brian Campbell and Chuck 379 Mortimore. 381 Appendix B. Document History 383 [[ to be removed by RFC editor before publication as an RFC ]] 385 -04 387 o Merged in changes between draft-ietf-oauth-saml2-bearer-09 and 388 draft-ietf-oauth-saml2-bearer-11. 390 o Added the optional "iat" (issued at) claim, which was already 391 present in the JWT spec. 393 -03 395 o Added the "jti" (JWT ID) claim to enable replay protection. 397 o Respect line length restrictions in examples. 399 -02 401 o Removed remaining vestiges of normative text talking about SAML 402 that remained from the SAML Profile draft. 404 o Replaced all references where the reference is used as if it were 405 part of the sentence (such as "defined by [I-D.whatever]") with 406 ones where the specification name is used, followed by the 407 reference (such as "defined by Whatever [I-D.whatever]"). 409 -01 411 o Merged in changes from draft-ietf-oauth-saml2-bearer-09. In 412 particular, this draft now uses draft-ietf-oauth-assertions, 413 rather than being standalone. It also now defines how to use JWT 414 bearer tokens both for Authorization Grants and for Client 415 Authentication. 417 -00 419 o Initial draft. 421 Authors' Addresses 423 Michael B. Jones 424 Microsoft 426 Email: mbj@microsoft.com 427 URI: http://self-issued.info/ 429 Brian Campbell 430 Ping Identity Corp. 432 Email: brian.d.campbell@gmail.com 434 Chuck Mortimore 435 Salesforce.com 437 Email: cmortimore@salesforce.com