idnits 2.17.1 draft-ietf-oauth-jwt-bearer-06.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 14, 2013) is 3937 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) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Downref: Normative reference to an Informational RFC: RFC 6755 == Outdated reference: A later version (-30) exists of draft-ietf-oauth-dyn-reg-13 Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). 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 15, 2014 Ping Identity 6 C. Mortimore 7 Salesforce 8 July 14, 2013 10 JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and 11 Authorization Grants 12 draft-ietf-oauth-jwt-bearer-06 14 Abstract 16 This specification defines the use of a JSON Web Token (JWT) Bearer 17 Token as a means for requesting an OAuth 2.0 access token as well as 18 for use as a means of client authentication. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on January 15, 2014. 37 Copyright Notice 39 Copyright (c) 2013 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 56 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 57 2. HTTP Parameter Bindings for Transporting Assertions . . . . . 4 58 2.1. Using JWTs as Authorization Grants . . . . . . . . . . . . 4 59 2.2. Using JWTs for Client Authentication . . . . . . . . . . . 5 60 3. JWT Format and Processing Requirements . . . . . . . . . . . . 6 61 3.1. Authorization Grant Processing . . . . . . . . . . . . . . 7 62 3.2. Client Authentication Processing . . . . . . . . . . . . . 8 63 4. Authorization Grant Example . . . . . . . . . . . . . . . . . 8 64 5. Interoperability Considerations . . . . . . . . . . . . . . . 9 65 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 66 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 67 7.1. Sub-Namespace Registration of 68 urn:ietf:params:oauth:grant-type:jwt-bearer . . . . . . . 10 69 7.2. Sub-Namespace Registration of 70 urn:ietf:params:oauth:client-assertion-type:jwt-bearer . . 10 71 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 72 8.1. Normative References . . . . . . . . . . . . . . . . . . . 10 73 8.2. Informative References . . . . . . . . . . . . . . . . . . 11 74 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11 75 Appendix B. Document History . . . . . . . . . . . . . . . . . . 11 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13 78 1. Introduction 80 JSON Web Token (JWT) [JWT] is a JavaScript Object Notation (JSON) 81 [RFC4627] based security token encoding that enables identity and 82 security information to be shared across security domains. A 83 security token is generally issued by an identity provider and 84 consumed by a relying party that relies on its content to identify 85 the token's subject for security related purposes. 87 The OAuth 2.0 Authorization Framework [RFC6749] provides a method for 88 making authenticated HTTP requests to a resource using an access 89 token. Access tokens are issued to third-party clients by an 90 authorization server (AS) with the (sometimes implicit) approval of 91 the resource owner. In OAuth, an authorization grant is an abstract 92 term used to describe intermediate credentials that represent the 93 resource owner authorization. An authorization grant is used by the 94 client to obtain an access token. Several authorization grant types 95 are defined to support a wide range of client types and user 96 experiences. OAuth also allows for the definition of new extension 97 grant types to support additional clients or to provide a bridge 98 between OAuth and other trust frameworks. Finally, OAuth allows the 99 definition of additional authentication mechanisms to be used by 100 clients when interacting with the authorization server. 102 The Assertion Framework for OAuth 2.0 Client Authentication and 103 Authorization Grants [I-D.ietf-oauth-assertions] specification is an 104 abstract extension to OAuth 2.0 that provides a general framework for 105 the use of Assertions (a.k.a. Security Tokens) as client credentials 106 and/or authorization grants with OAuth 2.0. This specification 107 profiles the Assertion Framework for OAuth 2.0 Client Authentication 108 and Authorization Grants [I-D.ietf-oauth-assertions] specification to 109 define an extension grant type that uses a JSON Web Token (JWT) 110 Bearer Token to request an OAuth 2.0 access token as well as for use 111 as client credentials. The format and processing rules for the JWT 112 defined in this specification are intentionally similar, though not 113 identical, to those in the closely related SAML 2.0 Profile for OAuth 114 2.0 Client Authentication and Authorization Grants 115 [I-D.ietf-oauth-saml2-bearer] specification. 117 This document defines how a JSON Web Token (JWT) Bearer Token can be 118 used to request an access token when a client wishes to utilize an 119 existing trust relationship, expressed through the semantics of (and 120 digital signature or keyed message digest calculated over) the JWT, 121 without a direct user approval step at the authorization server. It 122 also defines how a JWT can be used as a client authentication 123 mechanism. The use of a security token for client authentication is 124 orthogonal to and separable from using a security token as an 125 authorization grant. They can be used either in combination or 126 separately. Client authentication using a JWT is nothing more than 127 an alternative way for a client to authenticate to the token endpoint 128 and must be used in conjunction with some grant type to form a 129 complete and meaningful protocol request. JWT authorization grants 130 may be used with or without client authentication or identification. 131 Whether or not client authentication is needed in conjunction with a 132 JWT authorization grant, as well as the supported types of client 133 authentication, are policy decisions at the discretion of the 134 authorization server. 136 The process by which the client obtains the JWT, prior to exchanging 137 it with the authorization server or using it for client 138 authentication, is out of scope. 140 1.1. Notational Conventions 142 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 143 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 144 document are to be interpreted as described in RFC 2119 [RFC2119]. 146 Unless otherwise noted, all the protocol parameter names and values 147 are case sensitive. 149 1.2. Terminology 151 All terms are as defined in The OAuth 2.0 Authorization Framework 152 [RFC6749], the Assertion Framework for OAuth 2.0 Client 153 Authentication and Authorization Grants [I-D.ietf-oauth-assertions], 154 and the JSON Web Token (JWT) [JWT] specifications. 156 2. HTTP Parameter Bindings for Transporting Assertions 158 The Assertion Framework for OAuth 2.0 Client Authentication and 159 Authorization Grants [I-D.ietf-oauth-assertions] specification 160 defines generic HTTP parameters for transporting Assertions (a.k.a. 161 Security Tokens) during interactions with a token endpoint. This 162 section defines specific parameters and treatments of those 163 parameters for use with JWT bearer tokens. 165 2.1. Using JWTs as Authorization Grants 167 To use a Bearer JWT as an authorization grant, use an access token 168 request as defined in Section 4 of the Assertion Framework for OAuth 169 2.0 Client Authentication and Authorization Grants 170 [I-D.ietf-oauth-assertions] specification with the following specific 171 parameter values and encodings. 173 The value of the "grant_type" parameter MUST be 174 "urn:ietf:params:oauth:grant-type:jwt-bearer". 176 The value of the "assertion" parameter MUST contain a single JWT. 178 The "scope" parameter may be used, as defined in the Assertion 179 Framework for OAuth 2.0 Client Authentication and Authorization 180 Grants [I-D.ietf-oauth-assertions] specification, to indicate the 181 requested scope. 183 Authentication of the client is optional, as described in Section 184 3.2.1 of OAuth 2.0 [RFC6749] and consequently, the "client_id" is 185 only needed when a form of client authentication that relies on the 186 parameter is used. 188 The following non-normative example demonstrates an Access Token 189 Request with a JWT as an authorization grant (with extra line breaks 190 for display purposes only): 192 POST /token.oauth2 HTTP/1.1 193 Host: as.example.com 194 Content-Type: application/x-www-form-urlencoded 196 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer 197 &assertion=eyJhbGciOiJFUzI1NiJ9. 198 eyJpc3Mi[...omitted for brevity...]. 199 J9l-ZhwP[...omitted for brevity...] 201 2.2. Using JWTs for Client Authentication 203 To use a JWT Bearer Token for client authentication, use the 204 following parameter values and encodings. 206 The value of the "client_assertion_type" parameter MUST be 207 "urn:ietf:params:oauth:client-assertion-type:jwt-bearer". 209 The value of the "client_assertion" parameter MUST contain a single 210 JWT. 212 The following non-normative example demonstrates client 213 authentication using a JWT during the presentation of an 214 authorization code grant in an Access Token Request (with extra line 215 breaks for display purposes only): 217 POST /token.oauth2 HTTP/1.1 218 Host: as.example.com 219 Content-Type: application/x-www-form-urlencoded 221 grant_type=authorization_code& 222 code=vAZEIHjQTHuGgaSvyW9hO0RpusLzkvTOww3trZBxZpo& 223 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3A 224 client-assertion-type%3Ajwt-bearer& 225 client_assertion=eyJhbGciOiJSUzI1NiJ9. 226 eyJpc3Mi[...omitted for brevity...]. 227 cC4hiUPo[...omitted for brevity...] 229 3. JWT Format and Processing Requirements 231 In order to issue an access token response as described in OAuth 2.0 232 [RFC6749] or to rely on a JWT for client authentication, the 233 authorization server MUST validate the JWT according to the criteria 234 below. Application of additional restrictions and policy are at the 235 discretion of the authorization server. 237 1. The JWT MUST contain an "iss" (issuer) claim that contains a 238 unique identifier for the entity that issued the JWT. Issuer 239 values SHOULD be compared using the Simple String Comparison 240 method defined in Section 6.2.1 of RFC 3986 [RFC3986], unless 241 otherwise specified by the application. 243 2. The JWT MUST contain a "sub" (subject) claim identifying the 244 subject of the transaction. The subject MAY identify the 245 resource owner for whom the access token is being requested. 247 A. When using a JWT as an authorization grant, the subject 248 SHOULD identify an authorized accessor for whom the access 249 token is being requested (typically the resource owner, or 250 an authorized delegate). 252 B. For client authentication, the subject MUST be the 253 "client_id" of the OAuth client. 255 3. The JWT MUST contain an "aud" (audience) claim containing a 256 value that identifies the authorization server as an intended 257 audience. The token endpoint URL of the authorization server 258 MAY be used as a value for an "aud" element to identify the 259 authorization server as an intended audience of the JWT. JWTs 260 that do not identify the authorization server as an intended 261 audience MUST be rejected. Audience values SHOULD be compared 262 using the Simple String Comparison method defined in Section 263 6.2.1 of RFC 3986 [RFC3986], unless otherwise specified by the 264 application. 266 4. The JWT MUST contain an "exp" (expiration) claim that limits the 267 time window during which the JWT can be used. The authorization 268 server MUST verify that the expiration time has not passed, 269 subject to allowable clock skew between systems, and reject 270 expired JWTs. The authorization server MAY reject JWTs with an 271 "exp" claim value that is unreasonably far in the future. 273 5. The JWT MAY contain an "nbf" (not before) claim that identifies 274 the time before which the token MUST NOT be accepted for 275 processing. 277 6. The JWT MAY contain an "iat" (issued at) claim that identifies 278 the time at which the JWT was issued. The authorization server 279 MAY reject JWTs with an "iat" claim value that is unreasonably 280 far in the past. 282 7. The JWT MAY contain a "jti" (JWT ID) claim that provides a 283 unique identifier for the token. The authorization server MAY 284 ensure that JWTs are not replayed by maintaining the set of used 285 "jti" values for the length of time for which the JWT would be 286 considered valid based on the applicable "exp" instant. 288 8. The JWT MAY contain other claims. 290 9. The JWT MUST be digitally signed or have a keyed message digest 291 applied by the issuer. The authorization server MUST reject 292 JWTs with an invalid signature or keyed message digest. 294 10. The authorization server MUST verify that the JWT is valid in 295 all other respects per JSON Web Token (JWT) [JWT]. 297 3.1. Authorization Grant Processing 299 JWT authorization grants may be used with or without client 300 authentication or identification. Whether or not client 301 authentication is needed in conjunction with a JWT authorization 302 grant, as well as the supported types of client authentication, are 303 policy decisions at the discretion of the authorization server. 304 However, if client credentials are present in the request, the 305 authorization server MUST validate them. 307 If the JWT is not valid, or the current time is not within the 308 token's valid time window for use, the authorization server MUST 309 construct an error response as defined in OAuth 2.0 [RFC6749]. The 310 value of the "error" parameter MUST be the "invalid_grant" error 311 code. The authorization server MAY include additional information 312 regarding the reasons the JWT was considered invalid using the 313 "error_description" or "error_uri" parameters. 315 For example: 317 HTTP/1.1 400 Bad Request 318 Content-Type: application/json 319 Cache-Control: no-store 321 { 322 "error":"invalid_grant", 323 "error_description":"Audience validation failed" 324 } 326 3.2. Client Authentication Processing 328 If the client JWT is not valid, or its subject confirmation 329 requirements cannot be met, the authorization server MUST construct 330 an error response as defined in OAuth 2.0 [RFC6749]. The value of 331 the "error" parameter MUST be the "invalid_client" error code. The 332 authorization server MAY include additional information regarding the 333 reasons the JWT was considered invalid using the "error_description" 334 or "error_uri" parameters. 336 4. Authorization Grant Example 338 Though non-normative, the following examples illustrate what a 339 conforming JWT and access token request would look like. 341 The example shows a JWT issued and signed by the system entity 342 identified as "https://jwt-idp.example.com". The subject of the JWT 343 is identified by email address as "mike@example.com". The intended 344 audience of the JWT is "https://jwt-rp.example.net", which is an 345 identifier with which the authorization server identifies itself. 346 The JWT is sent as part of an access token request to the 347 authorization server's token endpoint at 348 "https://authz.example.net/token.oauth2". 350 Below is an example JSON object that could be encoded to produce the 351 JWT Claims Object for a JWT: 353 {"iss":"https://jwt-idp.example.com", 354 "sub":"mailto:mike@example.com", 355 "aud":"https://jwt-rp.example.net", 356 "nbf":1300815780, 357 "exp":1300819380, 358 "http://claims.example.com/member":true} 360 The following example JSON object, used as the header of a JWT, 361 declares that the JWT is signed with the ECDSA P-256 SHA-256 362 algorithm. 364 {"alg":"ES256"} 366 To present the JWT with the claims and header shown in the previous 367 example as part of an access token request, for example, the client 368 might make the following HTTPS request (with extra line breaks for 369 display purposes only): 371 POST /token.oauth2 HTTP/1.1 372 Host: authz.example.net 373 Content-Type: application/x-www-form-urlencoded 375 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer 376 &assertion=eyJhbGciOiJFUzI1NiJ9. 377 eyJpc3Mi[...omitted for brevity...]. 378 J9l-ZhwP[...omitted for brevity...] 380 5. Interoperability Considerations 382 Agreement between system entities regarding identifiers, keys, and 383 endpoints is required in order to achieve interoperable deployments 384 of this profile. Specific items that require agreement are as 385 follows: values for the issuer and audience identifiers, the location 386 of the token endpoint, and the key used to apply and verify the 387 digital signature or keyed message digest over the JWT. The exchange 388 of such information is explicitly out of scope for this 389 specification. In some cases, additional profiles may be created 390 that constrain or prescribe these values or specify how they are to 391 be exchanged. Examples of such profiles include the OAuth 2.0 392 Dynamic Client Registration Protocol [I-D.ietf-oauth-dyn-reg], OpenID 393 Connect Dynamic Client Registration 1.0 [OpenID.Registration], and 394 OpenID Connect Discovery 1.0 [OpenID.Discovery]. 396 6. Security Considerations 398 No additional security considerations apply beyond those described 399 within The OAuth 2.0 Authorization Framework [RFC6749], the Assertion 400 Framework for OAuth 2.0 Client Authentication and Authorization 401 Grants [I-D.ietf-oauth-assertions], and the JSON Web Token (JWT) 402 [JWT] specifications. 404 7. IANA Considerations 406 7.1. Sub-Namespace Registration of 407 urn:ietf:params:oauth:grant-type:jwt-bearer 409 This specification registers the value "grant-type:jwt-bearer" in the 410 IANA urn:ietf:params:oauth registry established in An IETF URN Sub- 411 Namespace for OAuth [RFC6755]. 413 o URN: urn:ietf:params:oauth:grant-type:jwt-bearer 415 o Common Name: JWT Bearer Token Grant Type Profile for OAuth 2.0 417 o Change controller: IETF 419 o Specification Document: [[this document]] 421 7.2. Sub-Namespace Registration of 422 urn:ietf:params:oauth:client-assertion-type:jwt-bearer 424 This specification registers the value 425 "client-assertion-type:jwt-bearer" in the IANA urn:ietf:params:oauth 426 registry established in An IETF URN Sub-Namespace for OAuth 427 [RFC6755]. 429 o URN: urn:ietf:params:oauth:client-assertion-type:jwt-bearer 431 o Common Name: JWT Bearer Token Profile for OAuth 2.0 Client 432 Authentication 434 o Change controller: IETF 436 o Specification Document: [[this document]] 438 8. References 440 8.1. Normative References 442 [I-D.ietf-oauth-assertions] 443 Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 444 "Assertion Framework for OAuth 2.0 Client Authentication 445 and Authorization Grants", draft-ietf-oauth-assertions 446 (work in progress), July 2013. 448 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 449 (JWT)", draft-ietf-oauth-json-web-token (work in 450 progress), July 2013. 452 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 453 Requirement Levels", BCP 14, RFC 2119, March 1997. 455 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 456 Resource Identifier (URI): Generic Syntax", STD 66, 457 RFC 3986, January 2005. 459 [RFC4627] Crockford, D., "The application/json Media Type for 460 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 462 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 463 RFC 6749, October 2012. 465 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 466 for OAuth", RFC 6755, October 2012. 468 8.2. Informative References 470 [I-D.ietf-oauth-dyn-reg] 471 Richer, J., Bradley, J., Jones, M., and M. Machulak, 472 "OAuth 2.0 Dynamic Client Registration Protocol", 473 draft-ietf-oauth-dyn-reg-13 (work in progress), July 2013. 475 [I-D.ietf-oauth-saml2-bearer] 476 Campbell, B., Mortimore, C., and M. Jones, "SAML 2.0 477 Profile for OAuth 2.0 Client Authentication and 478 Authorization Grants", draft-ietf-oauth-saml2-bearer (work 479 in progress), July 2013. 481 [OpenID.Discovery] 482 Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID 483 Connect Discovery 1.0", July 2013. 485 [OpenID.Registration] 486 Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect 487 Dynamic Client Registration 1.0", July 2013. 489 Appendix A. Acknowledgements 491 This profile was derived from SAML 2.0 Profile for OAuth 2.0 Client 492 Authentication and Authorization Grants [I-D.ietf-oauth-saml2-bearer] 493 by Brian Campbell and Chuck Mortimore. 495 Appendix B. Document History 497 [[ to be removed by the RFC editor before publication as an RFC ]] 498 -06 500 o Stated that issuer and audience values SHOULD be compared using 501 the Simple String Comparison method defined in Section 6.2.1 of 502 RFC 3986 unless otherwise specified by the application. 504 -05 506 o Changed title from "JSON Web Token (JWT) Bearer Token Profiles for 507 OAuth 2.0" to "JSON Web Token (JWT) Profile for OAuth 2.0 Client 508 Authentication and Authorization Grants" to be more explicit about 509 the scope of the document per 510 http://www.ietf.org/mail-archive/web/oauth/current/msg11063.html. 512 o Numbered the list of processing rules. 514 o Smallish editorial cleanups to try and improve readability and 515 comprehensibility. 517 o Cleaner split out of the processing rules in cases where they 518 differ for client authentication and authorization grants. 520 o Clarified the parameters that are used/available for authorization 521 grants. 523 o Added Interoperability Considerations section. 525 o Added more explanatory context to the example in Section 4. 527 -04 529 o Changed the name of the "prn" claim to "sub" (subject) both to 530 more closely align with SAML name usage and to use a more 531 intuitive name. 533 o Added seriesInfo information to Internet Draft references. 535 -03 537 o Reference RFC 6749 and RFC 6755. 539 -02 541 o Add more text to intro explaining that an assertion/JWT grant type 542 can be used with or without client authentication/identification 543 and that client assertion/JWT authentication is nothing more than 544 an alternative way for a client to authenticate to the token 545 endpoint 547 o Add examples to Sections 2.1 and 2.2 549 o Update references 551 -01 553 o Tracked specification name changes: "The OAuth 2.0 Authorization 554 Protocol" to "The OAuth 2.0 Authorization Framework" and "OAuth 555 2.0 Assertion Profile" to "Assertion Framework for OAuth 2.0". 557 o Merged in changes between draft-ietf-oauth-saml2-bearer-11 and 558 draft-ietf-oauth-saml2-bearer-13. All changes were strictly 559 editorial. 561 -00 563 o Created the initial IETF draft based upon 564 draft-jones-oauth-jwt-bearer-04 with no normative changes. 566 Authors' Addresses 568 Michael B. Jones 569 Microsoft 571 Email: mbj@microsoft.com 572 URI: http://self-issued.info/ 574 Brian Campbell 575 Ping Identity 577 Email: brian.d.campbell@gmail.com 579 Chuck Mortimore 580 Salesforce 582 Email: cmortimore@salesforce.com