idnits 2.17.1 draft-ietf-oauth-introspection-08.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 21, 2015) is 3292 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 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) Summary: 5 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group J. Richer, Ed. 3 Internet-Draft April 21, 2015 4 Intended status: Standards Track 5 Expires: October 23, 2015 7 OAuth 2.0 Token Introspection 8 draft-ietf-oauth-introspection-08 10 Abstract 12 This specification defines a method for a protected resource to query 13 an OAuth 2.0 authorization server to determine the active state of an 14 OAuth 2.0 token and to determine meta-information about this token. 15 OAuth 2.0 deployments can use this method to convey information about 16 the authorization context of the token from the authorization server 17 to the protected resource. 19 Requirements Language 21 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 22 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 23 document are to be interpreted as described in RFC 2119 [RFC2119]. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on October 23, 2015. 42 Copyright Notice 44 Copyright (c) 2015 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 61 2. Introspection Endpoint . . . . . . . . . . . . . . . . . . . 3 62 2.1. Introspection Request . . . . . . . . . . . . . . . . . . 4 63 2.2. Introspection Response . . . . . . . . . . . . . . . . . 5 64 2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 8 65 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 66 3.1. OAuth Token Introspection Response Registry . . . . . . . 8 67 3.1.1. Registration Template . . . . . . . . . . . . . . . . 9 68 3.1.2. Initial Registry Contents . . . . . . . . . . . . . . 9 69 4. Security Considerations . . . . . . . . . . . . . . . . . . . 11 70 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 13 71 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13 72 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 73 7.1. Normative References . . . . . . . . . . . . . . . . . . 14 74 7.2. Informative References . . . . . . . . . . . . . . . . . 14 75 Appendix A. Use with Proof of Posession Tokens . . . . . . . . . 15 76 Appendix B. Document History . . . . . . . . . . . . . . . . . . 15 77 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16 79 1. Introduction 81 In OAuth 2.0, the contents of tokens are opaque to clients. This 82 means that the client does not need to know anything about the 83 content or structure of the token itself, if there is any. However, 84 there is still a large amount of metadata that may be attached to a 85 token, such as its current validity, approved scopes, and information 86 about the context in which the token was issued. These pieces of 87 information are often vital to protected resources making 88 authorization decisions based on the tokens being presented. Since 89 OAuth 2.0 [RFC6749] does not define a protocol for the resource 90 server to learn meta-information about a token that is has received 91 from an authorization server, several different approaches have been 92 developed to bridge this gap. These include using structured token 93 formats such as JWT [JWT] or proprietary inter-service communication 94 mechanisms (such as shared databases and protected enterprise service 95 buses) that convey token information. 97 This specification defines an interoperable web API that allows 98 authorized protected resources to query the authorization server to 99 determine the set of metadata for a given token that was presented to 100 them by an OAuth 2.0 client. This metadata includes whether or not 101 the token is currently active (or if it has expired or otherwise been 102 revoked), what rights of access the token carries (usually conveyed 103 through OAuth 2.0 scopes), and the authorization context in which the 104 token was granted (including who authorized the token and which 105 client it was issued to). Token introspection allows a protected 106 resource to query this information regardless of whether or not it is 107 carried in the token itself, allowing this method to be used along 108 with or independently of structured token values. Additionally, a 109 protected resource can use the mechanism described in this 110 specification to introspect the token in a particular authorization 111 decision context and ascertain the relevant metadata about the token 112 in order to make this authorization decision appropriately. 114 1.1. Terminology 116 This section defines the terminology used by this specification. 117 This section is a normative portion of this specification, imposing 118 requirements upon implementations. 120 This specification uses the terms "access token", "authorization 121 endpoint", "authorization grant", "authorization server", "client", 122 "client identifier", "protected resource", "refresh token", "resource 123 owner", "resource server", and "token endpoint" defined by OAuth 2.0 124 [RFC6749], and the terms "claim names" and "claim values" defined by 125 JSON Web Token (JWT) [JWT]. 127 2. Introspection Endpoint 129 The introspection endpoint is an OAuth 2.0 endpoint that takes a 130 parameter representing an OAuth 2.0 token and returns a JSON 131 [RFC7159] document representing the meta information surrounding the 132 token, including whether this token is currently active. The 133 definition of an active token is up to the authorization server, but 134 this is commonly a token that has been issued by this authorization 135 server, is not expired, has not been revoked, and is within the 136 purview of the protected resource making the introspection call. 138 The introspection endpoint MUST be protected by a transport-layer 139 security mechanism as described in Section 4. 141 2.1. Introspection Request 143 The protected resource calls the introspection endpoint using an HTTP 144 POST [RFC7231] request with parameters sent as "application/x-www- 145 form-urlencoded" data as defined in [W3C.REC-html5-20141028]. The 146 authorization server MAY allow an HTTP GET [RFC7231] request with 147 parameters passed in the query string as defined in 148 [W3C.REC-html5-20141028]. The protected resource sends a parameter 149 representing the token along with optional parameters representing 150 additional context that is known by the protected resource to aid the 151 authorization server in its response. 153 token REQUIRED. The string value of the token. For access tokens, 154 this is the "access_token" value returned from the token endpoint 155 defined in OAuth 2.0 [RFC6749] section 5.1. For refresh tokens, 156 this is the "refresh_token" value returned from the token endpoint 157 as defined in OAuth 2.0 [RFC6749] section 5.1. Other token types 158 are outside the scope of this specification. 159 token_type_hint OPTIONAL. A hint about the type of the token 160 submitted for introspection. The protected resource MAY pass this 161 parameter in order to help the authorization server to optimize 162 the token lookup. If the server is unable to locate the token 163 using the given hint, it MUST extend its search across all of its 164 supported token types. An authorization server MAY ignore this 165 parameter, particularly if it is able to detect the token type 166 automatically. Values for this field are defined in OAuth Token 167 Revocation [RFC7009]. 169 The endpoint MAY allow other parameters to provide further context to 170 the query. For instance, an authorization service may need to know 171 the IP address of the client accessing the protected resource in 172 order to determine the appropriateness of the token being presented. 174 To prevent unauthorized token scanning attacks, the endpoint MUST 175 also require some form of authorization to access this endpoint, such 176 as client authentication as described in OAuth 2.0 [RFC6749] or a 177 separate OAuth 2.0 access token such as the bearer token described in 178 OAuth 2.0 Bearer Token Usage [RFC6750]. The methods of managing and 179 validating these authentication credentials are out of scope of this 180 specification. 182 For example, the following example shows a protected resource calling 183 the token introspection endpoint to query about an OAuth 2.0 bearer. 184 The protected resource is using a separate OAuth 2.0 bearer token to 185 authorize this call. 187 Following is a non-normative example request: 189 POST /introspect HTTP/1.1 190 Host: server.example.com 191 Accept: application/json 192 Content-Type: application/x-www-form-urlencoded 193 Authorization: Bearer 23410913-abewfq.123483 195 token=2YotnFZFEjr1zCsicMWpAA 197 In this example, the protected resource uses a client identifier and 198 client secret to authenticate itself to the introspection endpoint as 199 well as send a token type hint. 201 Following is a non-normative example request: 203 POST /introspect HTTP/1.1 204 Host: server.example.com 205 Accept: application/json 206 Content-Type: application/x-www-form-urlencoded 207 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 209 token=mF_9.B5f-4.1JqM&token_type_hint=access_token 211 2.2. Introspection Response 213 The server responds with a JSON object [RFC7159] in "application/ 214 json" format with the following top-level members. 216 active 217 REQUIRED. Boolean indicator of whether or not the presented token 218 is currently active. The specifics of a token's "active" state 219 will vary depending on the implementation of the authorization 220 server, and the information it keeps about its tokens, but a 221 "true" value return for the "active" property will generally 222 indicate that a given token has been issued by this authorization 223 server, has not been revoked by the resource owner, and is within 224 its given time window of validity (e.g. after its issuance time 225 and before its expiration time). See Section 4 for information on 226 implementation of such checks. 227 scope 228 OPTIONAL. A space-separated list of strings representing the 229 scopes associated with this token, in the format described in 230 section 3.3 of OAuth 2.0 [RFC6749]. 231 client_id 232 OPTIONAL. Client identifier for the OAuth 2.0 client that 233 requested this token. 234 username 235 OPTIONAL. Human-readable identifier for the resource owner who 236 authorized this token. 237 token_type 238 OPTIONAL. Type of the token as defined in section 5.1 of OAuth 239 2.0 [RFC6749]. 240 exp 241 OPTIONAL. Integer timestamp, measured in the number of seconds 242 since January 1 1970 UTC, indicating when this token will expire, 243 as defined in JWT [JWT]. 244 iat 245 OPTIONAL. Integer timestamp, measured in the number of seconds 246 since January 1 1970 UTC, indicating when this token was 247 originally issued, as defined in JWT [JWT]. 248 nbf 249 OPTIONAL. Integer timestamp, measured in the number of seconds 250 since January 1 1970 UTC, indicating when this token is not to be 251 used before, as defined in JWT [JWT]. 252 sub 253 OPTIONAL. Subject of the token, as defined in JWT [JWT]. Usually 254 a machine-readable identifier of the resource owner who authorized 255 this token. 256 aud 257 OPTIONAL. Service-specific string identifier or list of string 258 identifiers representing the intended audience for this token, as 259 defined in JWT [JWT]. 260 iss 261 OPTIONAL. String representing the issuer of this token, as 262 defined in JWT [JWT]. 263 jti 264 OPTIONAL. String identifier for the token, as defined in JWT 265 [JWT]. 267 Specific implementations MAY extend this structure with their own 268 service-specific response names as top-level members of this JSON 269 object. Response names intended to be used across domains MUST be 270 registered in the OAuth Token Introspection Response registry defined 271 in Section 3.1. 273 The authorization server MAY respond differently to different 274 protected resources making the same request. For instance, an 275 authorization server MAY limit which scopes from a given token are 276 returned for each protected resource in order to prevent protected 277 resources from learning more about the larger network than is 278 necessary for their function. 280 The response MAY be cached by the protected resource to improve 281 performance and reduce load on the introspection endpoint, but at the 282 cost of liveness of the information used by the protected resource. 283 See Section 4 for more information regarding the trade off when the 284 response is cached. 286 For example, the following response contains a set of information 287 about an active token: 289 Following is a non-normative example response: 291 HTTP/1.1 200 OK 292 Content-Type: application/json 294 { 295 "active": true, 296 "client_id": "l238j323ds-23ij4", 297 "username": "jdoe", 298 "scope": "read write dolphin", 299 "sub": "Z5O3upPC88QrAjx00dis", 300 "aud": "https://protected.example.net/resource", 301 "iss": "https://server.example.com/", 302 "exp": 1419356238, 303 "iat": 1419350238, 304 "extension_field": "twenty-seven" 305 } 307 If the introspection call is properly authorized but the token is not 308 active, does not exist on this server, or the protected resource is 309 not allowed to introspect this particular token, the authorization 310 server MUST return an introspection response with the active field 311 set to false. Note that in order to avoid disclosing too much of the 312 authorization server's state to a third party, the authorization 313 server SHOULD NOT include any additional information about an 314 inactive token, including why the token is inactive. For example, 315 the response for a token that has been revoked or is otherwise 316 invalid would look like the following: 318 Following is a non-normative example response: 320 HTTP/1.1 200 OK 321 Content-Type: application/json 323 { 324 "active": false 325 } 327 2.3. Error Response 329 If the protected resource uses OAuth 2.0 client credentials to 330 authenticate to the introspection endpoint and its credentials are 331 invalid, the authorization server responds with an HTTP 401 332 (Unauthorized) as described in section 5.2 of OAuth 2.0 [RFC6749]. 334 If the protected resource uses an OAuth 2.0 bearer token to authorize 335 its call to the introspection endpoint and the token used for 336 authorization does not contain sufficient privileges or is otherwise 337 invalid for this request, the authorization server responds with an 338 HTTP 401 code as described in section 3 of OAuth 2.0 Bearer Token 339 Usage [RFC6750]. 341 Note that a properly formed and authorized query for an inactive or 342 otherwise invalid token (or a token the protected resource is not 343 allowed to know about) is not considered an error response by this 344 specification. In these cases, the authorization server MUST instead 345 respond with an introspection response with the "active" field set to 346 "false" as described in Section 2.2. 348 3. IANA Considerations 350 3.1. OAuth Token Introspection Response Registry 352 This specification establishes the OAuth Token Introspection Response 353 registry. 355 OAuth registration client metadata names and descriptions are 356 registered with a Specification Required ([RFC5226]) after a two-week 357 review period on the oauth-ext-review@ietf.org mailing list, on the 358 advice of one or more Designated Experts. However, to allow for the 359 allocation of names prior to publication, the Designated Expert(s) 360 may approve registration once they are satisfied that such a 361 specification will be published. 363 Registration requests sent to the mailing list for review should use 364 an appropriate subject (e.g., "Request to register OAuth Token 365 Introspection Response name: example"). 367 Within the review period, the Designated Expert(s) will either 368 approve or deny the registration request, communicating this decision 369 to the review list and IANA. Denials should include an explanation 370 and, if applicable, suggestions as to how to make the request 371 successful. 373 IANA must only accept registry updates from the Designated Expert(s) 374 and should direct all requests for registration to the review mailing 375 list. 377 3.1.1. Registration Template 379 Name: 380 The name requested (e.g., "example"). This name is case 381 sensitive. Names that match other registered names in a case 382 insensitive manner SHOULD NOT be accepted. Names that match 383 claims registered in the JSON Web Token Claims registry 384 established by [JWT] SHOULD have comparable definitions and 385 semantics. 387 Description: 388 Brief description of the metadata value (e.g., "Example 389 description"). 391 Change controller: 392 For Standards Track RFCs, state "IESG". For others, give the name 393 of the responsible party. Other details (e.g., postal address, 394 email address, home page URI) may also be included. 396 Specification document(s): 397 Reference to the document(s) that specify the token endpoint 398 authorization method, preferably including a URI that can be used 399 to retrieve a copy of the document(s). An indication of the 400 relevant sections may also be included but is not required. 402 3.1.2. Initial Registry Contents 404 The initial contents of the OAuth Token Introspection Response 405 registry are: 407 o Name: "active" 408 o Description: Token active status 409 o Change Controller: IESG 410 o Specification Document(s): Section 2.2 of [[ this document ]]. 412 o Name: "username" 413 o Description: User identifier of the resource owner 414 o Change Controller: IESG 415 o Specification Document(s): Section 2.2 of [[ this document ]]. 417 o Name: "client_id" 418 o Description: Client identifier of the client 419 o Change Controller: IESG 420 o Specification Document(s): Section 2.2 of [[ this document ]]. 422 o Name: "scope" 423 o Description: Authorized scopes of the token 424 o Change Controller: IESG 425 o Specification Document(s): Section 2.2 of [[ this document ]]. 427 o Name: "token_type" 428 o Description: Type of the token 429 o Change Controller: IESG 430 o Specification Document(s): Section 2.2 of [[ this document ]]. 432 o Name: "exp" 433 o Description: Expiration timestamp of the token 434 o Change Controller: IESG 435 o Specification Document(s): Section 2.2 of [[ this document ]]. 437 o Name: "iat" 438 o Description: Issuance timestamp of the token 439 o Change Controller: IESG 440 o Specification Document(s): Section 2.2 of [[ this document ]]. 442 o Name: "nbf" 443 o Description: Timestamp which the token is not valid before 444 o Change Controller: IESG 445 o Specification Document(s): Section 2.2 of [[ this document ]]. 447 o Name: "sub" 448 o Description: Subject of the token 449 o Change Controller: IESG 450 o Specification Document(s): Section 2.2 of [[ this document ]]. 452 o Name: "aud" 453 o Description: Audience of the token 454 o Change Controller: IESG 455 o Specification Document(s): Section 2.2 of [[ this document ]]. 457 o Name: "iss" 458 o Description: Issuer of the token 459 o Change Controller: IESG 460 o Specification Document(s): Section 2.2 of [[ this document ]]. 462 o Name: "jti" 463 o Description: Unique identifier of the token 464 o Change Controller: IESG 465 o Specification Document(s): Section 2.2 of [[ this document ]]. 467 4. Security Considerations 469 Since there are many different and valid ways to implement an OAuth 470 2.0 system, there are consequently many ways for an authorization 471 server to determine whether or not a token is currently "active" or 472 not. However, since resource servers using token introspection rely 473 on the authorization server to determine the state of a token, the 474 authorization server MUST perform all applicable checks against a 475 token's state. For instance: 477 o If the token can expire, the authorization server MUST determine 478 whether or not the token has expired. 479 o If the token can be issued before it is able to be used, the 480 authorization server MUST determine whether or not a token's valid 481 period has started yet. 482 o If the token can be revoked after it was issued, the authorization 483 server MUST determine whether or not such a revocation has taken 484 place. 485 o If the token has been signed, the authorization server MUST 486 validate the signature. 488 If an authorization server fails to perform any applicable check, the 489 resource server could make an errant security decision based on that 490 response. Note that not all of these checks will be applicable to 491 all OAuth 2.0 deployments and it is up to the authorization server to 492 determine which of these checks (and any other checks) apply. 494 If left unprotected and un-throttled, the introspection endpoint 495 could present a means for an attacker to poll a series of possible 496 token values, fishing for a valid token. To prevent this, the 497 authorization server MUST require authentication of protected 498 resources that need to access the introspection endpoint and SHOULD 499 require protected resources to be specifically authorized to call the 500 introspection endpoint. The specifics of this authentication 501 credentials are out of scope of this specification, but commonly 502 these credentials could take the form of any valid client 503 authentication mechanism used with the token endpoint, an OAuth 2.0 504 access token, or other HTTP authorization or authentication 505 mechanism. A single piece of software acting as both a client and a 506 protected resource MAY re-use the same credentials between the token 507 endpoint and the introspection endpoint, though doing so potentially 508 conflates the activities of the client and protected resource 509 portions of the software and the authorization server MAY require 510 separate credentials for each mode. 512 Since the introspection endpoint takes in OAuth 2.0 tokens as 513 parameters and responds with information used to make authorization 514 decisions, the server MUST support TLS 1.2 RFC 5246 [RFC5246] and MAY 515 support additional transport-layer mechanisms meeting its security 516 requirements. When using TLS, the client or protected resource MUST 517 perform a TLS/SSL server certificate check, per RFC 6125 [RFC6125]. 518 Implementation security considerations can be found in 519 Recommendations for Secure Use of TLS and DTLS [TLS.BCP]. 521 In order to prevent the values of access tokens from leaking into 522 server-side logs via query parameters, an authorization server 523 offering token introspection MAY disallow HTTP GET and instead 524 require an HTTP POST method to be used at the introspection endpoint. 526 In order to avoid disclosing internal server state, an introspection 527 response for an inactive token SHOULD NOT contain any additional 528 claims beyond the required "active" claim (with its value set to 529 "false"). 531 Since a protected resource MAY cache the response of the 532 introspection endpoint, designers of an OAuth 2.0 system using this 533 protocol MUST consider the performance and security trade-offs 534 inherent in caching security information such as this. A less 535 aggressive cache with a short timeout will provide the protected 536 resource with more up to date information (due to it needing to query 537 the introspection endpoint more often) at the cost of increased 538 network traffic and load on the introspection endpoint. A more 539 aggressive cache with a longer duration will minimize network traffic 540 and load on the introspection endpoint, but at the risk of stale 541 information about the token. For example, the token may be revoked 542 while the protected resource is relying on the value of the cached 543 response to make authorization decisions. This creates a window 544 during which a revoked token could be used at the protected resource. 545 Consequently, an acceptable cache validity duration needs to be 546 carefully considered given the concerns and sensitivities of the 547 protected resource being accessed and the likelihood of a token being 548 revoked or invalidated in the interim period. Highly sensitive 549 environments can opt to disable caching entirely on the protected 550 resource in order to eliminate the risk of stale cached information 551 entirely, again at the cost of increased network traffic and server 552 load. 554 An authorization server offering token introspection MUST be able to 555 understand the token values being presented to it during this call. 556 The exact means by which this happens is an implementation detail and 557 outside the scope of this specification. For unstructured tokens, 558 this could take the form of a simple server-side database query 559 against a data store containing the context information for the 560 token. For structured tokens, this could take the form of the server 561 parsing the token, validating its signature or other protection 562 mechanisms, and returning the information contained in the token back 563 to the protected resource (allowing the protected resource to be 564 unaware of the token's contents, much like the client). 566 Note that for tokens carrying encrypted information that is needed 567 during the introspection process, the authorization server MUST be 568 able to decrypt and validate the token in order to access this 569 information. Also note that in cases where the authorization server 570 stores no information about the token and has no means of accessing 571 information about the token by parsing the token itself, it can not 572 likely offer an introspection service. 574 5. Privacy Considerations 576 The introspection response may contain privacy-sensitive information 577 such as user identifiers for resource owners. When this is the case, 578 measures MUST be taken to prevent disclosure of this information to 579 unintended parties. One way to limit disclosure is to require 580 authorization to call the introspection endpoint and to limit calls 581 to only registered and trusted protected resource servers. Another 582 method is to transmit user identifiers as opaque service-specific 583 strings, potentially returning different identifiers to each 584 protected resource. 586 If the protected resource sends additional information about the 587 client's request to the authorization server (such as the client's IP 588 address) using an extension of this specification, such information 589 could have additional privacy considerations. However, the nature 590 and implications of such extensions are outside the scope of this 591 specification. 593 Omitting privacy-sensitive information from an introspection response 594 is the simplest way of minimizing privacy issues. 596 6. Acknowledgements 598 Thanks to the OAuth Working Group and the User Managed Access Working 599 Group for feedback and review of this document, and to the various 600 implementors of both the client and server components of this 601 specification. In particular, the author would like to thank Amanda 602 Anganes, John Bradley, Thomas Broyer, Brian Campbell, George 603 Fletcher, Paul Freemantle, Thomas Hardjono, Eve Maler, Josh Mandel, 604 Steve Moore, Mike Schwartz, Prabath Siriwardena, Sarah Squire, and 605 Hannes Tschofennig, 607 7. References 609 7.1. Normative References 611 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 612 Requirement Levels", BCP 14, RFC 2119, March 1997. 614 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 615 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 616 May 2008. 618 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 619 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 621 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 622 Verification of Domain-Based Application Service Identity 623 within Internet Public Key Infrastructure Using X.509 624 (PKIX) Certificates in the Context of Transport Layer 625 Security (TLS)", RFC 6125, March 2011. 627 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 628 6749, October 2012. 630 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 631 Framework: Bearer Token Usage", RFC 6750, October 2012. 633 [RFC7009] Lodderstedt, T., Dronia, S., and M. Scurtescu, "OAuth 2.0 634 Token Revocation", RFC 7009, August 2013. 636 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 637 Interchange Format", RFC 7159, March 2014. 639 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 640 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 642 [W3C.REC-html5-20141028] 643 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 644 Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", 645 World Wide Web Consortium Recommendation REC- 646 html5-20141028, October 2014, 647 . 649 7.2. Informative References 651 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 652 (JWT)", draft-ietf-oauth-json-web-token (work in 653 progress), July 2014. 655 [TLS.BCP] Sheffer, Y., Holz, R., and P. Saint-Andre, 656 "Recommendations for Secure Use of TLS and DTLS", November 657 2014. 659 Appendix A. Use with Proof of Posession Tokens 661 With bearer tokens such as those defined by OAuth 2.0 Bearer Token 662 Usage [RFC6750], the protected resource will have in its possession 663 the entire secret portion of the token for submission to the 664 introspection service. However, for proof-of-possession style 665 tokens, the protected resource will have only a token identifier used 666 during the request, along with the cryptographic signature on the 667 request. The protected resource would be able to submit the token 668 identifier to the authorization server's token endpoint in order to 669 obtain the necessary key information needed to validate the signature 670 on the request. The details of this usage are outside the scope of 671 this specification and will be defined in an extension to this 672 specification. 674 Appendix B. Document History 676 [[ To be removed by the RFC Editor. ]] 678 -08 680 o Added privacy considerations note about extensions. 681 o Added acknowledgements (finally). 683 -07 685 o Created a separate IANA registry for introspection responses, 686 importing the values from JWT. 688 -06 690 o Clarified relationship between AS and RS in introduction. 691 o Used updated TLS text imported from Dyn-Reg drafts. 692 o Clarified definition of active state. 693 o Added some advice on caching responses. 694 o Added security considerations on active state implementation. 695 o Changed user_id to username based on WG feedback. 697 -05 699 o Typo fix. 700 o Updated author information. 701 o Removed extraneous "linewrap" note from examples. 703 - 04 705 o Removed "resource_id" from request. 706 o Added examples. 708 - 03 710 o Updated HTML and HTTP references. 711 o Call for registration of parameters in the JWT registry. 713 - 02 715 o Removed SAML pointer. 716 o Clarified what an "active" token could be. 717 o Explicitly declare introspection request as x-www-form-urlencoded 718 format. 719 o Added extended example. 720 o Made protected resource authentication a MUST. 722 - 01 724 o Fixed casing and consistent term usage. 725 o Incorporated working group comments. 726 o Clarified that authorization servers need to be able to understand 727 the token if they're to introspect it. 728 o Various editorial cleanups. 730 - 00 732 o Created initial IETF drafted based on draft-richer-oauth- 733 introspection-06 with no normative changes. 735 Author's Address 737 Justin Richer (editor) 739 Email: ietf@justin.richer.org