idnits 2.17.1 draft-ietf-oauth-jwt-bearer-05.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 (March 29, 2013) is 4045 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-10 ** 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-08 == Outdated reference: A later version (-23) exists of draft-ietf-oauth-saml2-bearer-15 Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group M.B. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track B. Campbell 5 Expires: September 30, 2013 Ping Identity 6 C. Mortimore 7 Salesforce 8 March 29, 2013 10 JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and 11 Authorization Grants 12 draft-ietf-oauth-jwt-bearer-05 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 September 30, 2013. 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 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 . . . . . . . . . . . . 7 63 4. Authorization Grant Example . . . . . . . . . . . . . . . . . 8 64 5. Interoperability Considerations . . . . . . . . . . . . . . . 9 65 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 66 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 67 7.1. Sub-Namespace Registration of urn:ietf:params:oauth 68 :grant-type:jwt-bearer . . . . . . . . . . . . . . . . . 9 69 7.2. Sub-Namespace Registration of urn:ietf:params:oauth 70 :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 184 Section 3.2.1 of OAuth 2.0 [RFC6749] and consequently, the 185 "client_id" is only needed when a form of client authentication that 186 relies on the 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. 240 2. The JWT MUST contain a "sub" (subject) claim identifying the 241 subject of the transaction. The subject MAY identify the 242 resource owner for whom the access token is being requested. 244 a. When using a JWT as an authorization grant, the subject 245 SHOULD identify an authorized accessor for whom the access 246 token is being requested (typically the resource owner, or 247 an authorized delegate). 249 b. For client authentication, the subject MUST be the 250 "client_id" of the OAuth client. 252 3. The JWT MUST contain an "aud" (audience) claim containing a 253 value that identifies the authorization server as an intended 254 audience. The token endpoint URL of the authorization server 255 MAY be used as a value for an "aud" element to identify the 256 authorization server as an intended audience of the JWT. JWTs 257 that do not identify the authorization server as an intended 258 audience MUST be rejected. 260 4. The JWT MUST contain an "exp" (expiration) claim that limits the 261 time window during which the JWT can be used. The authorization 262 server MUST verify that the expiration time has not passed, 263 subject to allowable clock skew between systems, and reject 264 expired JWTs. The authorization server MAY reject JWTs with an 265 "exp" claim value that is unreasonably far in the future. 267 5. The JWT MAY contain an "nbf" (not before) claim that identifies 268 the time before which the token MUST NOT be accepted for 269 processing. 271 6. The JWT MAY contain an "iat" (issued at) claim that identifies 272 the time at which the JWT was issued. The authorization server 273 MAY reject JWTs with an "iat" claim value that is unreasonably 274 far in the past. 276 7. The JWT MAY contain a "jti" (JWT ID) claim that provides a 277 unique identifier for the token. The authorization server MAY 278 ensure that JWTs are not replayed by maintaining the set of used 279 "jti" values for the length of time for which the JWT would be 280 considered valid based on the applicable "exp" instant. 282 8. The JWT MAY contain other claims. 284 9. The JWT MUST be digitally signed or have a keyed message digest 285 applied by the issuer. The authorization server MUST reject 286 JWTs with an invalid signature or keyed message digest. 288 10. The authorization server MUST verify that the JWT is valid in 289 all other respects per JSON Web Token (JWT) [JWT]. 291 3.1. Authorization Grant Processing 293 JWT authorization grants may be used with or without client 294 authentication or identification. Whether or not client 295 authentication is needed in conjunction with a JWT authorization 296 grant, as well as the supported types of client authentication, are 297 policy decisions at the discretion of the authorization server. 298 However, if client credentials are present in the request, the 299 authorization server MUST validate them. 301 If the JWT is not valid, or the current time is not within the 302 token's valid time window for use, the authorization server MUST 303 construct an error response as defined in OAuth 2.0 [RFC6749]. The 304 value of the "error" parameter MUST be the "invalid_grant" error 305 code. The authorization server MAY include additional information 306 regarding the reasons the JWT was considered invalid using the 307 "error_description" or "error_uri" parameters. 309 For example: 311 HTTP/1.1 400 Bad Request 312 Content-Type: application/json 313 Cache-Control: no-store 315 { 316 "error":"invalid_grant", 317 "error_description":"Audience validation failed" 318 } 320 3.2. Client Authentication Processing 321 If the client JWT is not valid, or its subject confirmation 322 requirements cannot be met, the authorization server MUST construct 323 an error response as defined in OAuth 2.0 [RFC6749]. The value of 324 the "error" parameter MUST be the "invalid_client" error code. The 325 authorization server MAY include additional information regarding the 326 reasons the JWT was considered invalid using the "error_description" 327 or "error_uri" parameters. 329 4. Authorization Grant Example 331 Though non-normative, the following examples illustrate what a 332 conforming JWT and access token request would look like. 334 The example shows a JWT issued and signed by the system entity 335 identified as "https://jwt-idp.example.com". The subject of the JWT 336 is identified by email address as "mike@example.com". The intended 337 audience of the JWT is "https://jwt-rp.example.net", which is an 338 identifier with which the authorization server identifies itself. 339 The JWT is sent as part of an access token request to the 340 authorization server's token endpoint at "https://authz.example.net/ 341 token.oauth2". 343 Below is an example JSON object that could be encoded to produce the 344 JWT Claims Object for a JWT: 346 {"iss":"https://jwt-idp.example.com", 347 "sub":"mailto:mike@example.com", 348 "aud":"https://jwt-rp.example.net", 349 "nbf":1300815780, 350 "exp":1300819380, 351 "http://claims.example.com/member":true} 353 The following example JSON object, used as the header of a JWT, 354 declares that the JWT is signed with the ECDSA P-256 SHA-256 355 algorithm. 357 {"alg":"ES256"} 359 To present the JWT with the claims and header shown in the previous 360 example as part of an access token request, for example, the client 361 might make the following HTTPS request (with extra line breaks for 362 display purposes only): 364 POST /token.oauth2 HTTP/1.1 365 Host: authz.example.net 366 Content-Type: application/x-www-form-urlencoded 368 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer 369 &assertion=eyJhbGciOiJFUzI1NiJ9. 370 eyJpc3Mi[...omitted for brevity...]. 371 J9l-ZhwP[...omitted for brevity...] 373 5. Interoperability Considerations 375 Agreement between system entities regarding identifiers, keys, and 376 endpoints is required in order to achieve interoperable deployments 377 of this profile. Specific items that require agreement are as 378 follows: values for the issuer and audience identifiers, the location 379 of the token endpoint, and the key used to apply and verify the 380 digital signature or keyed message digest over the JWT. The exchange 381 of such information is explicitly out of scope for this 382 specification. In some cases, additional profiles may be created 383 that constrain or prescribe these values or specify how they are to 384 be exchanged. Examples of such profiles include the OAuth 2.0 385 Dynamic Client Registration Protocol [I-D.ietf-oauth-dyn-reg], OpenID 386 Connect Dynamic Client Registration 1.0 [OpenID.Registration], and 387 OpenID Connect Discovery 1.0 [OpenID.Discovery]. 389 6. Security Considerations 391 No additional security considerations apply beyond those described 392 within The OAuth 2.0 Authorization Framework [RFC6749], the Assertion 393 Framework for OAuth 2.0 Client Authentication and Authorization 394 Grants [I-D.ietf-oauth-assertions], and the JSON Web Token (JWT) 395 [JWT] specifications. 397 7. IANA Considerations 399 7.1. Sub-Namespace Registration of urn:ietf:params:oauth:grant-type 400 :jwt-bearer 402 This specification registers the value "grant-type:jwt-bearer" in the 403 IANA urn:ietf:params:oauth registry established in An IETF URN Sub- 404 Namespace for OAuth [RFC6755]. 406 o URN: urn:ietf:params:oauth:grant-type:jwt-bearer 408 o Common Name: JWT Bearer Token Grant Type Profile for OAuth 2.0 410 o Change controller: IETF 411 o Specification Document: [[this document]] 413 7.2. Sub-Namespace Registration of urn:ietf:params:oauth:client- 414 assertion-type:jwt-bearer 416 This specification registers the value "client-assertion-type:jwt- 417 bearer" in the IANA urn:ietf:params:oauth registry established in An 418 IETF URN Sub-Namespace for OAuth [RFC6755]. 420 o URN: urn:ietf:params:oauth:client-assertion-type:jwt-bearer 422 o Common Name: JWT Bearer Token Profile for OAuth 2.0 Client 423 Authentication 425 o Change controller: IETF 427 o Specification Document: [[this document]] 429 8. References 431 8.1. Normative References 433 [I-D.ietf-oauth-assertions] 434 Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 435 "Assertion Framework for OAuth 2.0", draft-ietf-oauth- 436 assertions-10 (work in progress), January 2013. 438 [JWT] Jones, M.B., Bradley, J., and N. Sakimura, "JSON Web Token 439 (JWT)", draft-ietf-oauth-json-web-token (work in 440 progress), December 2012. 442 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 443 Requirement Levels", BCP 14, RFC 2119, March 1997. 445 [RFC4627] Crockford, D., "The application/json Media Type for 446 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 448 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 449 6749, October 2012. 451 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 452 for OAuth", RFC 6755, October 2012. 454 8.2. Informative References 456 [I-D.ietf-oauth-dyn-reg] 457 Richer, J., Bradley, J., Jones, M., and M. Machulak, 458 "OAuth 2.0 Dynamic Client Registration Protocol", draft- 459 ietf-oauth-dyn-reg-08 (work in progress), March 2013. 461 [I-D.ietf-oauth-saml2-bearer] 462 Campbell, B. and C. Mortimore, "SAML 2.0 Bearer Assertion 463 Profiles for OAuth 2.0", draft-ietf-oauth-saml2-bearer-15 464 (work in progress), November 2012. 466 [OpenID.Discovery] 467 Sakimura, N., Bradley, J., Jones, M.B., and E. Jay, 468 "OpenID Connect Discovery 1.0", March 2013. 470 [OpenID.Registration] 471 Sakimura, N., Bradley, J., and M.B. Jones, "OpenID Connect 472 Dynamic Client Registration 1.0", March 2013. 474 Appendix A. Acknowledgements 476 This profile was derived from SAML 2.0 Profile for OAuth 2.0 Client 477 Authentication and Authorization Grants [I-D.ietf-oauth-saml2-bearer] 478 by Brian Campbell and Chuck Mortimore. 480 Appendix B. Document History 482 [[ to be removed by the RFC editor before publication as an RFC ]] 484 -05 486 o Changed title from "JSON Web Token (JWT) Bearer Token Profiles for 487 OAuth 2.0" to "JSON Web Token (JWT) Profile for OAuth 2.0 Client 488 Authentication and Authorization Grants" to be more explicit about 489 the scope of the document per http://www.ietf.org/mail-archive/web 490 /oauth/current/msg11063.html. 492 o Numbered the list of processing rules. 494 o Smallish editorial cleanups to try and improve readability and 495 comprehensibility. 497 o Cleaner split out of the processing rules in cases where they 498 differ for client authentication and authorization grants. 500 o Clarified the parameters that are used/available for authorization 501 grants. 503 o Added Interoperability Considerations section. 505 o Added more explanatory context to the example in Section 4. 507 -04 509 o Changed the name of the "prn" claim to "sub" (subject) both to 510 more closely align with SAML name usage and to use a more 511 intuitive name. 513 o Added seriesInfo information to Internet Draft references. 515 -03 517 o Reference RFC 6749 and RFC 6755. 519 -02 521 o Add more text to intro explaining that an assertion/JWT grant type 522 can be used with or without client authentication/identification 523 and that client assertion/JWT authentication is nothing more than 524 an alternative way for a client to authenticate to the token 525 endpoint 527 o Add examples to Sections 2.1 and 2.2 529 o Update references 531 -01 533 o Tracked specification name changes: "The OAuth 2.0 Authorization 534 Protocol" to "The OAuth 2.0 Authorization Framework" and "OAuth 535 2.0 Assertion Profile" to "Assertion Framework for OAuth 2.0". 537 o Merged in changes between draft-ietf-oauth-saml2-bearer-11 and 538 draft-ietf-oauth-saml2-bearer-13. All changes were strictly 539 editorial. 541 -00 543 o Created the initial IETF draft based upon draft-jones-oauth-jwt- 544 bearer-04 with no normative changes. 546 Authors' Addresses 548 Michael B. Jones 549 Microsoft 551 Email: mbj@microsoft.com 552 URI: http://self-issued.info/ 554 Brian Campbell 555 Ping Identity Corp. 557 Email: brian.d.campbell@gmail.com 559 Chuck Mortimore 560 Salesforce 562 Email: cmortimore@salesforce.com