idnits 2.17.1 draft-jones-oauth-jwt-bearer-00.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (March 28, 2011) is 4771 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 (-31) exists of draft-ietf-oauth-v2-13 -- 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-03 Summary: 1 error (**), 0 flaws (~~), 4 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 March 28, 2011 5 Expires: September 29, 2011 7 JSON Web Token (JWT) Bearer Profile for OAuth 2.0 8 draft-jones-oauth-jwt-bearer-00 10 Abstract 12 This specification defines the use of a JSON Web Token (JWT) bearer 13 token as a means of requesting an OAuth 2.0 access token. 15 Status of this Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at http://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on September 29, 2011. 32 Copyright Notice 34 Copyright (c) 2011 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (http://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 50 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 51 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 3 52 2. JWT Access Token Request . . . . . . . . . . . . . . . . . . . 3 53 2.1. Client Requests Access Token . . . . . . . . . . . . . . . 4 54 2.2. JWT Content and Processing Requirements . . . . . . . . . . 4 55 2.3. Error Response . . . . . . . . . . . . . . . . . . . . . . 5 56 2.4. Example (non-normative) . . . . . . . . . . . . . . . . . . 6 57 3. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 58 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 59 4.1. OAuth Parameters Registration . . . . . . . . . . . . . . . 7 60 4.1.1. The "jwt" OAuth Parameter . . . . . . . . . . . . . . . 7 61 5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 62 5.1. Normative References . . . . . . . . . . . . . . . . . . . 7 63 5.2. Informative References . . . . . . . . . . . . . . . . . . 8 64 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 8 65 Appendix B. Document History . . . . . . . . . . . . . . . . . . . 8 66 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8 68 1. Introduction 70 JSON Web Token (JWT) [JWT] is a JSON-based security token encoding 71 that enables identity and security information to be shared across 72 security domains. JWTs utilize JSON data structures, as defined in 73 RFC 4627 [RFC4627]. 75 The OAuth 2.0 Authorization Protocol [I-D.ietf-oauth-v2] provides a 76 method for making authenticated HTTP requests to a resource using an 77 access token. Access tokens are issued to third-party clients by an 78 authorization server (AS) with the (sometimes implicit) approval of 79 the resource owner. In OAuth, an authorization grant is an abstract 80 term used to describe intermediate credentials that represent the 81 resource owner authorization. An authorization grant is used by the 82 client to obtain an access token. 84 Several authorization grant types are defined to support a wide range 85 of client types and user experiences. OAuth also allows for the 86 definition of new extension grant types to support additional clients 87 or to provide a bridge between OAuth and other trust frameworks. 89 This specification defines an extension grant type that profiles the 90 use of a JSON Web Token (JWT) in requesting an OAuth 2.0 access 91 token. 93 1.1. Notational Conventions 95 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 96 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 97 document are to be interpreted as described in [RFC2119]. 99 Unless otherwise noted, all the protocol parameter names and values 100 are case sensitive. 102 1.2. Terminology 104 All terms are as defined in [I-D.ietf-oauth-v2] and [JWT]. 106 2. JWT Access Token Request 108 A JSON Web Token (JWT) bearer token can be used to request an access 109 token when a client wishes to utilize an existing trust relationship, 110 expressed through the semantics of the JWT, without a direct user 111 approval step at the authorization server. 113 The process by which the client obtains the JWT, prior to exchanging 114 it with the authorization server, is out of scope. 116 +--------+ +---------------+ 117 | | | | 118 | |--(A)-- JSON Web Token (JWT) ->| Authorization | 119 | Client | | Server | 120 | |<-(B)----- Access Token -------| | 121 | | | | 122 +--------+ +---------------+ 124 Figure 1: Access Token Request using JWT Bearer Token 126 The request/response flow illustrated in Figure 1 includes the 127 following steps: 129 (A) The client sends an access token request to the authorization 130 server that includes a JWT bearer token and a grant_type of 131 "http://oauth.net/grant_type/jwt/1.0/bearer". 133 (B) The authorization server validates the JWT per the processing 134 rules defined in the JWT specification and in this specification 135 and issues an access token. 137 2.1. Client Requests Access Token 139 The client includes the JWT in the access token request, the core 140 details of which are defined in OAuth [I-D.ietf-oauth-v2], by 141 specifying "http://oauth.net/grant_type/jwt/1.0/bearer" as the 142 absolute URI value of the "grant_type" parameter and by adding the 143 following parameter: 145 jwt 146 REQUIRED. The value of the "jwt" parameter MUST be a single 147 JWT that is represented using the Compact Serialization. 149 scope 150 OPTIONAL. The scope of the access request expressed as a list 151 of space-delimited strings. The value is defined by the 152 authorization server. If the value contains multiple space- 153 delimited strings, their order does not matter, and each string 154 adds an additional access range to the requested scope. 156 2.2. JWT Content and Processing Requirements 158 Prior to issuing an access token response as described in 159 [I-D.ietf-oauth-v2], the authorization server MUST validate the JWT 160 according to the criteria below. If present, the authorization 161 server MUST also validate the client credentials. Application of 162 additional restrictions and policy are at the discretion of the 163 authorization server. 165 o The JWT MUST contain an "iss" (issuer) claim that contains a 166 unique identifier for the entity that issued the JWT. 168 o The JWT MUST contain a "prn" (principal) claim. The principal 169 MUST identify the resource owner for whom the access token is 170 being requested. 172 o The JWT MUST contain an "aud" (audience) claim containing a URI 173 reference that identifies the authorization server as the intended 174 audience. The authorization server MUST verify that it is an 175 intended audience for the JWT. 177 o The JWT MUST contain an "exp" (expiration) claim that limits the 178 time window during which the JWT can be used. The authorization 179 server MUST verify that the expiration time has not passed, 180 subject to allowable clock skew between systems. The 181 authorization server MAY reject JWTs with an "exp" claim value 182 that is unreasonably far in the future. 184 o The JWT MAY contain an "iat" (issued at) claim containing the UTC 185 time at which the JWT was issued. This time is represented as an 186 "IntDate", as defined by [JWT]. 188 o The JWT MAY contain other claims. 190 o The JWT MUST be digitally signed by the issuer in the manner 191 described in the JWT specification and the authorization server 192 MUST verify the signature. 194 o The authorization server MUST verify that the JWT is valid in all 195 other respects per [JWT]. 197 2.3. Error Response 199 If the JWT is not valid or has expired, the authorization server MUST 200 construct an error response as defined in [I-D.ietf-oauth-v2]. The 201 value of the error parameter MUST be the "invalid_grant" error code. 202 The authorization server MAY include additional information regarding 203 the reasons the JWT was considered invalid using the 204 "error_description" or "error_uri" parameters. 206 For example: 208 HTTP/1.1 400 Bad Request 209 Content-Type: application/json 210 Cache-Control: no-store 212 { 213 "error":"invalid_grant", 214 "error_description":"Audience validation failed" 215 } 217 2.4. Example (non-normative) 219 Though non-normative, the following examples illustrate what a 220 conforming JWT and access token request would look like. 222 Below is an example JSON object that could be encoded to produce the 223 JWT Claims Object for a JWT: 224 {"iss":"https://jwt-idp.example.com", 225 "prn":"mailto:mike@example.com", 226 "aud":"https://jwt-rp.example.net", 227 "iat":1300815780, 228 "exp":1300819380, 229 "http://claims.example.com/member":true} 231 Figure 2: Example JWT Claims Object 233 The following example JSON object, used as the header of a JWT, 234 declares that the JWT is signed with the ECDSA P-256 SHA-256 235 algorithm. 236 {"alg":"ES256"} 238 Figure 3: Example JWT Header Object 240 To present a JWT with the claims and header shown above as part of an 241 access token request, for example, the client might make the 242 following HTTPS request (line breaks are for display purposes only): 244 POST /token.oauth2 HTTP/1.1 245 Host: authz.example.net 246 Content-Type: application/x-www-form-urlencoded 248 grant_type=http%3A%2F%2Foauth.net%2Fgrant_type%2Fjwt%2F1.0%2Fbearer& 249 jwt=eyJhbGciOiJFUzI1NiJ9.eyJpc3Mi[...omitted for brevity...]. 250 J9l-ZhwP_2n[...omitted for brevity...] 252 Figure 4: Example Request 254 3. Security Considerations 256 Authorization servers SHOULD issue access tokens with a limited 257 lifetime and require clients to refresh them by requesting a new 258 access token using the same JWT, if it is still valid, or with a new 259 JWT. The authorization server SHOULD NOT issue a refresh token. 261 4. IANA Considerations 263 4.1. OAuth Parameters Registration 265 This specification registers the following parameters in the OAuth 266 Parameters Registry established by [I-D.ietf-oauth-v2]. 268 4.1.1. The "jwt" OAuth Parameter 270 Parameter name: jwt 272 Parameter usage location: token request 274 Change controller: IETF 276 Specification document(s): [[ this document ]] 278 Related information: None 280 5. References 282 5.1. Normative References 284 [I-D.ietf-oauth-v2] 285 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 286 2.0 Authorization Protocol", draft-ietf-oauth-v2-13 (work 287 in progress), February 2011. 289 [JWT] Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, 290 J., Sakimura, N., and P. Tarjan, "JSON Web Token (JWT)", 291 March 2011. 293 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 294 Requirement Levels", BCP 14, RFC 2119, March 1997. 296 [RFC4627] Crockford, D., "The application/json Media Type for 297 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 299 5.2. Informative References 301 [I-D.ietf-oauth-saml2-bearer] 302 Campbell, B. and C. Mortimore, "SAML 2.0 Bearer Assertion 303 Grant Type Profile for OAuth 2.0", 304 draft-ietf-oauth-saml2-bearer-03 (work in progress), 305 February 2011. 307 Appendix A. Acknowledgements 309 This profile was derived from the SAML2 Bearer Assertion Grant Type 310 Profile for OAuth 2.0 [I-D.ietf-oauth-saml2-bearer] by Brian Campbell 311 and Chuck Mortimore. 313 Appendix B. Document History 315 [[ to be removed by RFC editor before publication as an RFC ]] 317 -00 319 o Initial draft. 321 Author's Address 323 Michael B. Jones 324 Microsoft 326 Email: mbj@microsoft.com 327 URI: http://self-issued.info/