idnits 2.17.1 draft-reddy-tram-token-metadata-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 : ---------------------------------------------------------------------------- ** There are 41 instances of too long lines in the document, the longest one being 6 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 16, 2015) is 3144 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 5389 (Obsoleted by RFC 8489) ** Obsolete normative reference: RFC 5766 (Obsoleted by RFC 8656) -- Obsolete informational reference (is this intentional?): RFC 5785 (Obsoleted by RFC 8615) -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 TRAM T. Reddy 3 Internet-Draft S. Nandakumar 4 Intended status: Standards Track D. Wing 5 Expires: March 19, 2016 Cisco 6 B. Williams 7 Akamai, Inc. 8 September 16, 2015 10 Metadata discovery for third party authorized TURN session 11 draft-reddy-tram-token-metadata-01 13 Abstract 15 The operator of the TURN server might want to have fine grained 16 control on the clients usage of the server resources for providing 17 features such as limiting the bandwidth usage, number of allocations 18 and so on. This document proposes a generic mechanism for the 19 operator to introspect the access token to retrieve any policy 20 restrictions imposed by the authorization server on the TURN server 21 resources assigned to the client. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on March 19, 2016. 40 Copyright Notice 42 Copyright (c) 2015 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 59 3. Introspection Request . . . . . . . . . . . . . . . . . . . . 3 60 4. Introspection Response . . . . . . . . . . . . . . . . . . . 4 61 5. INTROSPECTION_ENDPOINT Attribute . . . . . . . . . . . . . . 5 62 6. Notifications from Introspection Endpoint . . . . . . . . . . 5 63 7. Example usage with WebRTC . . . . . . . . . . . . . . . . . . 6 64 8. Alternate Approach . . . . . . . . . . . . . . . . . . . . . 8 65 9. Security Considerations . . . . . . . . . . . . . . . . . . . 9 66 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 67 10.1. JSON Web Token Claims . . . . . . . . . . . . . . . . . 9 68 10.2. Well-Known 'introspection' URI . . . . . . . . . . . . . 10 69 10.3. STUN attribute . . . . . . . . . . . . . . . . . . . . . 10 70 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 71 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 72 12.1. Normative References . . . . . . . . . . . . . . . . . . 10 73 12.2. Informative References . . . . . . . . . . . . . . . . . 11 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 76 1. Introduction 78 The TURN protocol [RFC5766] is used to setup a relay service (via a 79 TURN Server) to exchange traffic (real time media, data) between 80 peers when direct peer-to-peer connection is not otherwise possible. 81 Due to the costs associated with operating a relay service, it is 82 important to constrain resource usage. For example, the operator 83 might want to limit the number of allocations or bandwidth. 85 [RFC7635] allows clients to obtain OAuth2.0 access token (of type 86 'Assertion') authorized by a Authorization Server to access a given 87 TURN server. On receiving such a token, the TURN server validates 88 the token to grant or reject access to the session resources. 89 However, having a token doesn't provide any control for the operator 90 of the TURN server restrict the server's resources. This 91 specification proposes using the mechanism defined in 92 [I-D.ietf-oauth-introspection] to query OAuth2.0 authorization server 93 to determine resource restrictions for this token. 95 The rest of the document is organized as follows. Section 3 provides 96 procedure for querying the OAuth2.0 Introspection Endpoint and 97 Section 4 shows the introspection response with the parameters 98 identifying the policy controls associated with the access token. 100 2. Terminology 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 104 document are to be interpreted as described in [RFC2119]. 106 This document defines the following terms: 108 Access Token: OAuth 2.0 access token. 110 Token Introspection: The act of inquiring about the current state of 111 an OAuth 2.0 token through use of the network protocol defined in 112 this document. 114 Introspection Endpoint: The OAuth 2.0 endpoint through which the 115 token introspection operation is accomplished. The Introspection 116 Endpoint could be a WebRTC server. 118 3. Introspection Request 120 For introspecting the meta-information associated with the access 121 token, the TURN server shall execute the procedures defined in 122 Section 2.1 of [I-D.ietf-oauth-introspection]. 124 POST {scheme}://{host}:{port}/.well-known/introspection 125 Accept: application/json 126 Content-Type: application/x-www-form-urlencoded 128 { 129 "token" : "string" 130 "token_type_hint" : "string" 131 } 133 token REQUIRED. This parameter is defined in 134 [I-D.ietf-oauth-introspection]. The access token is conveyed by 135 the TURN client to the TURN server as discussed in Section 3.1 136 of [RFC7635]. 138 token_type_hint OPTIONAL. This parameter is defined in 139 [I-D.ietf-oauth-introspection]. The token type MUST be set to 140 'access_token' defined in [RFC7009]. If the token type is not 141 'access_token', the server rejects the request with a 400 (Bad 142 Request) error. 144 Following is a non-normative example request showcasing the 145 introspection request for a given access token. 147 POST /introspect HTTP/1.1 148 Host: server.example.com 149 Accept: application/json 150 Content-Type: application/x-www-form-urlencoded 152 { 154 "token" : "2YotnFZFEjr1zCsicMWpAA" 155 "token_type_hint" : "access_token" 157 } 159 4. Introspection Response 161 The OAuth2.0 Introspection Endpoint on recognizing the token, 162 responds with a JSON object [RFC7159] in "application/json" format 163 with the following members. 165 HTTP/1.1 200 OK 166 Content-Type: application/json 168 { 169 "active" : "boolean", 170 "scope" : "string", 171 "max_upstream_bandwidth" : "unsigned integer", 172 "max_downstream_bandwidth" : "unsigned integer", 173 "max_allocations" : "unsigned integer", 174 "lifetime" : "unsigned integer", 175 } 177 active REQUIRED. This parameter is defined in 178 [I-D.ietf-oauth-introspection]. 180 scope OPTIONAL. This parameter is defined in 181 [I-D.ietf-oauth-introspection]. For this specification, the 182 scope MUST be 'stun'. 184 max_upstream_bandwidth REQUIRED. The value of this parameter is 185 an 64 bit unsigned integer that represents the maximum upstream 186 bandwidth permitted for the token in kilobits per second (1 187 kilobit = 1024 bits). 189 max_downstream bandwidth REQUIRED. The value of this parameter 190 is an 64 bit unsigned integer that represents the maximum 191 downstream bandwidth permitted for the token in kilobits per 192 second (1 kilobit = 1024 bits). 194 max_allocations: REQUIRED. 16 bit unsigned integer defining 195 maximum number of allocations that is allowable for the given 196 access token. 198 lifetime: REQUIRED: The lifetime of the access token, in 199 seconds. 201 NOTE: Future specifications are allowed to define further top-level 202 members as mandated by the use-cases. 204 Following is a non-normative example response: 206 HTTP/1.1 200 OK 207 Content-Type: application/json 209 { 210 "active" : true, 211 "scope" : "stun", 212 "upstream-bandwidth" : 4096, 213 "downstream-bandwidth" : 4096, 214 "max-allocations" : 1, 215 } 217 5. INTROSPECTION_ENDPOINT Attribute 219 This attribute is used by the TURN client to inform the TURN server 220 the FQDN of Introspection Endpoint. 222 The TURN server establishes an HTTPS connection with the indicated 223 server and sends the above-described communications to that server. 224 The INTROSPECTION_ENDPOINT attribute is a comprehension-optional 225 attribute (see Section 15 from [RFC5389]). 227 TBD: An alternate approach is to convey the FQDN in the token itself. 229 6. Notifications from Introspection Endpoint 231 Introspection Endpoint can send unsolicited responses to notify 232 updates to the metadata associated with the token to the TURN server 233 using HTTP/2 server push mechanism. Examples where such 234 notifications are desired are: 236 o The Introspection Endpoint can signal the TURN server to revoke 237 the access token after the call is terminated by setting lifetime 238 to zero. 240 o When the call switches from audio to video, the Introspection 241 Endpoint notifies the increased bandwidth to the TURN server. 243 7. Example usage with WebRTC 245 Below diagram shows a flow where a WebRTC client uses the procedures 246 discussed in [RFC7635] to obtain a OAuth 2.0 access token from the 247 WebRTC server. The TURN Server queries the Introspection Endpoint to 248 determine the metadata associated with the token. Steps 7, 8 and 9 249 are done using the procedures mentioned in this document. 251 +-------------------+ +--------+ +---------------+ 252 | ......... TURN | | TURN | | WebRTC Server| 253 | .WebRTC . Client | | | | | 254 | .Client . | | Server | |(Introspection | 255 | ......... | | | | Endpoint) | 256 +-------------------+ +--------+ +---------------+ 257 | | (1)Allocate request | | 258 | |----------------------------------------->| | 259 | | | | 260 | | (2)Allocate error response | | 261 | | (401 Unauthorized) | | 262 | |<-----------------------------------------| | 263 | | THIRD-PARTY-AUTHORIZATION | | 264 | | | | 265 | | | | 266 | | (3)HTTP Request for token | | 267 |-------------------------------------------------------------------->| 268 | |(4) HTTP Response with token parameters | | 269 |<--------------------------------------------------------------------| 270 |OAuth 2.0 | | 271 Attributes | | 272 |------>| | | 273 | | (5)Allocate request ACCESS-TOKEN | | 274 | |----------------------------------------->| | 275 | | | | 276 | | (6)Allocate success response | | 277 | |<-----------------------------------------| | 278 | | |(7)Introspection | 279 | | | Request | 280 | | |----------------->| 281 | | | | 282 | | |(8)Introspection | 283 | | | response | 284 | | |<-----------------| 285 | |<---------------------------------------->| | 286 | | TURN Messages | | 287 | | ////// integrity protected ////// | | 288 | | ////// integrity protected ////// | | 289 | | | (9)Introspection | 290 | | | response | 291 | | |<-----------------| 293 Figure 1: Metadata discovery for TURN session 295 8. Alternate Approach 297 An alternate approach considered by the authors makes use of the 298 access token itself to deliver metadata related to the TURN 299 authentication request. Standard STUN TLV encoded attributes are 300 used to communicate additional metadata associated with the token. 301 Such attributes can be used to define the maximum bandwidth 302 utilization allowed for allocations associated with the token, the 303 maximum number of distinct concurrent allocations, etc. 305 To include STUN attributes within the body of the access token, the 306 authorization server simply appends them to the access token's 307 plaintext immediately after the lifetime field. The variable length 308 list of attributes MUST consume all of the additional plaintext data 309 space within the body of the access token. No explicit option length 310 value is required or provided. 312 In order for inclusion of attributes within the plaintext to work 313 correctly in the absence of an explicit length field, one of two 314 things must be true: either the receiver must be able to reliably 315 determine the correct content length from the output of the 316 decryption operation, or the receiver must be able to reliably 317 differentiate between padding bytes and data bytes within the token. 318 AES-128-GCM is an example of the first case, and AEAD mode AES-CBC- 319 HMAC-SHA256 is an example of the second case. 321 Before parsing the optional data within the access token, the TURN 322 server MUST first perform all token validation required by [RFC7635]. 323 If any of the specified validation checks fail, the TURN server MUST 324 NOT attempt to parse optional attributes. 326 To interpret the optional attributes within an access token, the TURN 327 server first calculates the amount of option space included in the 328 plaintext by subtracting the size of the base payload data (14 bytes 329 + key_length) from the total payload size. It then interprets the 330 data in the option space as STUN TLV formatted attributes. While 331 parsing the option space, the TURN server MUST apply the same 332 validations to the access token's attributes that it would have 333 applied if the attributes had been included in the outer STUN header 334 (e.g. Verify the data format and value types). If any such 335 validation checks fail, the TURN server MUST reject the STUN request 336 with an error response 401 (Unauthorized). 338 The following STUN attributes are defined by this document for 339 inclusion in the access token: TBD. Additional attributes may be 340 defined for this purpose in future specifications. 342 The primary benefits of this method of metadata distribution are: 344 o It does not impose additional requirements on the Introspection 345 Endpoint for out of band communication with the TURN server. 347 o Communicating with the Introspection Endpoint may increase the 348 latency associated with TURN allocation request handling. 350 The primary shortcomings of this method of metadata distribution are: 352 o Needs a larger TURN packet to accommodate the token. For example, 353 inclusion of the four fields defined above 354 (max_upstream_bandwidth, max_downstream_bandwidth, 355 max_allocations, and lifetime) would increase the token size by 356 around 38 bytes, depending upon whether the AEAD algorithm 357 requires padding. 359 o The Introspection Endpoint cannot notify the TURN server of 360 changes to the metadata associated with the token. 362 [NOTE: Backward compatibility with [RFC7635] requires discussion, but 363 it should not be a major issue if the dynamic option space 364 calculation method described is considered acceptable.] 366 [NOTE: The authors are seeking feedback from the working group on the 367 relative merits of this approach versus the "Introspection Endpoint" 368 approach. Which should we attempt to move forward? Or does each one 369 have enough merit that we should try to advance both?] 371 9. Security Considerations 373 The Security Considerations and Privacy Considerations of 374 [I-D.ietf-oauth-introspection] apply to this document. 376 10. IANA Considerations 378 10.1. JSON Web Token Claims 380 This specification requests IANA to register the following values 381 into the IANA JSON Web Token Claims registry for JWT Claim Names. 383 o Claim Name: "max_upstream_bandwidth" 384 o Claim Description: Maximum limit of upstream bandwidth 385 o Change Controller: IESG 386 o Specification Document(s): Section 4 of [[ this document ]]. 388 o Claim Name: "max_downstream_bandwidth" 389 o Claim Description: Maximum limit of downstream bandwidth 390 o Change Controller: IESG 391 o Specification Document(s): Section 4 of [[ this document ]]. 393 o Claim Name: "max_allocations" 394 o Claim Description: Maximum number of allocations 395 o Change Controller: IESG 396 o Specification Document(s): Section 4 of [[ this document ]]. 398 10.2. Well-Known 'introspection' URI 400 This memo registers the 'introspection' well-known URI in the Well- 401 Known URIs registry as defined by [RFC5785]. 403 URI suffix: introspection 405 Change controller: IETF 407 Specification document(s): This document 409 Related information: None 411 10.3. STUN attribute 413 [Paragraphs below in braces should be removed by the RFC Editor upon 414 publication] 416 [IANA is requested to add the following attributes to the STUN 417 attribute registry [iana-stun], the INTROSPECTION_ENDPOINT attribute 418 requires that IANA allocate a value in the "STUN attributes Registry" 419 from the comprehension-optional range (0x8000-0xBFFF)]. 421 This document defines the INTROSPECTION_ENDPOINT attribute, described 422 in Section 5. IANA has allocated the comprehension-optional 423 codepoint TBD for this attribute. 425 11. Acknowledgements 427 Authors would like to thank Ram Mohan for comments and review. 429 12. References 431 12.1. Normative References 433 [I-D.ietf-oauth-introspection] 434 Richer, J., "OAuth 2.0 Token Introspection", draft-ietf- 435 oauth-introspection-11 (work in progress), July 2015. 437 [iana-stun] 438 IANA, , "IANA: STUN Attributes", April 2011, 439 . 442 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 443 Requirement Levels", BCP 14, RFC 2119, 444 DOI 10.17487/RFC2119, March 1997, 445 . 447 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 448 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 449 DOI 10.17487/RFC5389, October 2008, 450 . 452 [RFC5766] Mahy, R., Matthews, P., and J. Rosenberg, "Traversal Using 453 Relays around NAT (TURN): Relay Extensions to Session 454 Traversal Utilities for NAT (STUN)", RFC 5766, 455 DOI 10.17487/RFC5766, April 2010, 456 . 458 [RFC7635] Reddy, T., Patil, P., Ravindranath, R., and J. Uberti, 459 "Session Traversal Utilities for NAT (STUN) Extension for 460 Third-Party Authorization", RFC 7635, 461 DOI 10.17487/RFC7635, August 2015, 462 . 464 12.2. Informative References 466 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 467 Uniform Resource Identifiers (URIs)", RFC 5785, 468 DOI 10.17487/RFC5785, April 2010, 469 . 471 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 472 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 473 August 2013, . 475 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 476 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 477 2014, . 479 Authors' Addresses 481 Tirumaleswar Reddy 482 Cisco Systems, Inc. 484 Email: tireddy@cisco.com 485 Suhas Nandakumar 486 Cisco Systems, Inc. 488 Email: snandaku@cisco.com 490 Dan Wing 491 Cisco Systems, Inc. 492 170 West Tasman Drive 493 San Jose, California 95134 494 USA 496 Email: dwing@cisco.com 498 Brandon Williams 499 Akamai, Inc. 500 8 Cambridge Center 501 Cambridge, MA 02142 502 USA 504 Email: brandon.williams@akamai.com