idnits 2.17.1 draft-ietf-oauth-introspection-09.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 (May 28, 2015) is 3250 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 May 28, 2015 4 Intended status: Standards Track 5 Expires: November 29, 2015 7 OAuth 2.0 Token Introspection 8 draft-ietf-oauth-introspection-09 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 November 29, 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 . . . . . . . . . . . . . . . . . 15 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 [RFC7519] or proprietary inter-service 94 communication mechanisms (such as shared databases and protected 95 enterprise service 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) [RFC7519]. 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. 160 token_type_hint OPTIONAL. A hint about the type of the token 161 submitted for introspection. The protected resource MAY pass this 162 parameter in order to help the authorization server to optimize 163 the token lookup. If the server is unable to locate the token 164 using the given hint, it MUST extend its search across all of its 165 supported token types. An authorization server MAY ignore this 166 parameter, particularly if it is able to detect the token type 167 automatically. Values for this field are defined in OAuth Token 168 Revocation [RFC7009]. 170 The endpoint MAY allow other parameters to provide further context to 171 the query. For instance, an authorization service may need to know 172 the IP address of the client accessing the protected resource in 173 order to determine the appropriateness of the token being presented. 175 To prevent unauthorized token scanning attacks, the endpoint MUST 176 also require some form of authorization to access this endpoint, such 177 as client authentication as described in OAuth 2.0 [RFC6749] or a 178 separate OAuth 2.0 access token such as the bearer token described in 179 OAuth 2.0 Bearer Token Usage [RFC6750]. The methods of managing and 180 validating these authentication credentials are out of scope of this 181 specification. 183 For example, the following example shows a protected resource calling 184 the token introspection endpoint to query about an OAuth 2.0 bearer. 185 The protected resource is using a separate OAuth 2.0 bearer token to 186 authorize this call. 188 Following is a non-normative example request: 190 POST /introspect HTTP/1.1 191 Host: server.example.com 192 Accept: application/json 193 Content-Type: application/x-www-form-urlencoded 194 Authorization: Bearer 23410913-abewfq.123483 196 token=2YotnFZFEjr1zCsicMWpAA 198 In this example, the protected resource uses a client identifier and 199 client secret to authenticate itself to the introspection endpoint as 200 well as send a token type hint. 202 Following is a non-normative example request: 204 POST /introspect HTTP/1.1 205 Host: server.example.com 206 Accept: application/json 207 Content-Type: application/x-www-form-urlencoded 208 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 210 token=mF_9.B5f-4.1JqM&token_type_hint=access_token 212 2.2. Introspection Response 214 The server responds with a JSON object [RFC7159] in "application/ 215 json" format with the following top-level members. 217 active 218 REQUIRED. Boolean indicator of whether or not the presented token 219 is currently active. The specifics of a token's "active" state 220 will vary depending on the implementation of the authorization 221 server, and the information it keeps about its tokens, but a 222 "true" value return for the "active" property will generally 223 indicate that a given token has been issued by this authorization 224 server, has not been revoked by the resource owner, and is within 225 its given time window of validity (e.g. after its issuance time 226 and before its expiration time). See Section 4 for information on 227 implementation of such checks. 229 scope 230 OPTIONAL. A space-separated list of strings representing the 231 scopes associated with this token, in the format described in 232 section 3.3 of OAuth 2.0 [RFC6749]. 234 client_id 235 OPTIONAL. Client identifier for the OAuth 2.0 client that 236 requested this token. 238 username 239 OPTIONAL. Human-readable identifier for the resource owner who 240 authorized this token. 242 token_type 243 OPTIONAL. Type of the token as defined in section 5.1 of OAuth 244 2.0 [RFC6749]. 246 exp 247 OPTIONAL. Integer timestamp, measured in the number of seconds 248 since January 1 1970 UTC, indicating when this token will expire, 249 as defined in JWT [RFC7519]. 251 iat 252 OPTIONAL. Integer timestamp, measured in the number of seconds 253 since January 1 1970 UTC, indicating when this token was 254 originally issued, as defined in JWT [RFC7519]. 256 nbf 257 OPTIONAL. Integer timestamp, measured in the number of seconds 258 since January 1 1970 UTC, indicating when this token is not to be 259 used before, as defined in JWT [RFC7519]. 261 sub 262 OPTIONAL. Subject of the token, as defined in JWT [RFC7519]. 263 Usually a machine-readable identifier of the resource owner who 264 authorized this token. 266 aud 267 OPTIONAL. Service-specific string identifier or list of string 268 identifiers representing the intended audience for this token, as 269 defined in JWT [RFC7519]. 271 iss 272 OPTIONAL. String representing the issuer of this token, as 273 defined in JWT [RFC7519]. 275 jti 276 OPTIONAL. String identifier for the token, as defined in JWT 277 [RFC7519]. 279 Specific implementations MAY extend this structure with their own 280 service-specific response names as top-level members of this JSON 281 object. Response names intended to be used across domains MUST be 282 registered in the OAuth Token Introspection Response registry defined 283 in Section 3.1. 285 The authorization server MAY respond differently to different 286 protected resources making the same request. For instance, an 287 authorization server MAY limit which scopes from a given token are 288 returned for each protected resource in order to prevent protected 289 resources from learning more about the larger network than is 290 necessary for their function. 292 The response MAY be cached by the protected resource to improve 293 performance and reduce load on the introspection endpoint, but at the 294 cost of liveness of the information used by the protected resource. 295 See Section 4 for more information regarding the trade off when the 296 response is cached. 298 For example, the following response contains a set of information 299 about an active token: 301 Following is a non-normative example response: 303 HTTP/1.1 200 OK 304 Content-Type: application/json 306 { 307 "active": true, 308 "client_id": "l238j323ds-23ij4", 309 "username": "jdoe", 310 "scope": "read write dolphin", 311 "sub": "Z5O3upPC88QrAjx00dis", 312 "aud": "https://protected.example.net/resource", 313 "iss": "https://server.example.com/", 314 "exp": 1419356238, 315 "iat": 1419350238, 316 "extension_field": "twenty-seven" 317 } 319 If the introspection call is properly authorized but the token is not 320 active, does not exist on this server, or the protected resource is 321 not allowed to introspect this particular token, the authorization 322 server MUST return an introspection response with the active field 323 set to false. Note that in order to avoid disclosing too much of the 324 authorization server's state to a third party, the authorization 325 server SHOULD NOT include any additional information about an 326 inactive token, including why the token is inactive. For example, 327 the response for a token that has been revoked or is otherwise 328 invalid would look like the following: 330 Following is a non-normative example response: 332 HTTP/1.1 200 OK 333 Content-Type: application/json 335 { 336 "active": false 337 } 339 2.3. Error Response 341 If the protected resource uses OAuth 2.0 client credentials to 342 authenticate to the introspection endpoint and its credentials are 343 invalid, the authorization server responds with an HTTP 401 344 (Unauthorized) as described in section 5.2 of OAuth 2.0 [RFC6749]. 346 If the protected resource uses an OAuth 2.0 bearer token to authorize 347 its call to the introspection endpoint and the token used for 348 authorization does not contain sufficient privileges or is otherwise 349 invalid for this request, the authorization server responds with an 350 HTTP 401 code as described in section 3 of OAuth 2.0 Bearer Token 351 Usage [RFC6750]. 353 Note that a properly formed and authorized query for an inactive or 354 otherwise invalid token (or a token the protected resource is not 355 allowed to know about) is not considered an error response by this 356 specification. In these cases, the authorization server MUST instead 357 respond with an introspection response with the "active" field set to 358 "false" as described in Section 2.2. 360 3. IANA Considerations 362 3.1. OAuth Token Introspection Response Registry 364 This specification establishes the OAuth Token Introspection Response 365 registry. 367 OAuth registration client metadata names and descriptions are 368 registered with a Specification Required ([RFC5226]) after a two-week 369 review period on the oauth-ext-review@ietf.org mailing list, on the 370 advice of one or more Designated Experts. However, to allow for the 371 allocation of names prior to publication, the Designated Expert(s) 372 may approve registration once they are satisfied that such a 373 specification will be published. 375 Registration requests sent to the mailing list for review should use 376 an appropriate subject (e.g., "Request to register OAuth Token 377 Introspection Response name: example"). 379 Within the review period, the Designated Expert(s) will either 380 approve or deny the registration request, communicating this decision 381 to the review list and IANA. Denials should include an explanation 382 and, if applicable, suggestions as to how to make the request 383 successful. 385 IANA must only accept registry updates from the Designated Expert(s) 386 and should direct all requests for registration to the review mailing 387 list. 389 3.1.1. Registration Template 391 Name: 392 The name requested (e.g., "example"). This name is case 393 sensitive. Names that match other registered names in a case 394 insensitive manner SHOULD NOT be accepted. Names that match 395 claims registered in the JSON Web Token Claims registry 396 established by [RFC7519] SHOULD have comparable definitions and 397 semantics. 399 Description: 400 Brief description of the metadata value (e.g., "Example 401 description"). 403 Change controller: 404 For Standards Track RFCs, state "IESG". For others, give the name 405 of the responsible party. Other details (e.g., postal address, 406 email address, home page URI) may also be included. 408 Specification document(s): 409 Reference to the document(s) that specify the token endpoint 410 authorization method, preferably including a URI that can be used 411 to retrieve a copy of the document(s). An indication of the 412 relevant sections may also be included but is not required. 414 3.1.2. Initial Registry Contents 416 The initial contents of the OAuth Token Introspection Response 417 registry are: 419 o Name: "active" 420 o Description: Token active status 421 o Change Controller: IESG 422 o Specification Document(s): Section 2.2 of [[ this document ]]. 424 o Name: "username" 425 o Description: User identifier of the resource owner 426 o Change Controller: IESG 427 o Specification Document(s): Section 2.2 of [[ this document ]]. 429 o Name: "client_id" 430 o Description: Client identifier of the client 431 o Change Controller: IESG 432 o Specification Document(s): Section 2.2 of [[ this document ]]. 434 o Name: "scope" 435 o Description: Authorized scopes of the token 436 o Change Controller: IESG 437 o Specification Document(s): Section 2.2 of [[ this document ]]. 439 o Name: "token_type" 440 o Description: Type of the token 441 o Change Controller: IESG 442 o Specification Document(s): Section 2.2 of [[ this document ]]. 444 o Name: "exp" 445 o Description: Expiration timestamp of the token 446 o Change Controller: IESG 447 o Specification Document(s): Section 2.2 of [[ this document ]]. 449 o Name: "iat" 450 o Description: Issuance timestamp of the token 451 o Change Controller: IESG 452 o Specification Document(s): Section 2.2 of [[ this document ]]. 454 o Name: "nbf" 455 o Description: Timestamp which the token is not valid before 456 o Change Controller: IESG 457 o Specification Document(s): Section 2.2 of [[ this document ]]. 459 o Name: "sub" 460 o Description: Subject of the token 461 o Change Controller: IESG 462 o Specification Document(s): Section 2.2 of [[ this document ]]. 464 o Name: "aud" 465 o Description: Audience of the token 466 o Change Controller: IESG 467 o Specification Document(s): Section 2.2 of [[ this document ]]. 469 o Name: "iss" 470 o Description: Issuer of the token 471 o Change Controller: IESG 472 o Specification Document(s): Section 2.2 of [[ this document ]]. 474 o Name: "jti" 475 o Description: Unique identifier of the token 476 o Change Controller: IESG 477 o Specification Document(s): Section 2.2 of [[ this document ]]. 479 4. Security Considerations 481 Since there are many different and valid ways to implement an OAuth 482 2.0 system, there are consequently many ways for an authorization 483 server to determine whether or not a token is currently "active" or 484 not. However, since resource servers using token introspection rely 485 on the authorization server to determine the state of a token, the 486 authorization server MUST perform all applicable checks against a 487 token's state. For instance: 489 o If the token can expire, the authorization server MUST determine 490 whether or not the token has expired. 491 o If the token can be issued before it is able to be used, the 492 authorization server MUST determine whether or not a token's valid 493 period has started yet. 494 o If the token can be revoked after it was issued, the authorization 495 server MUST determine whether or not such a revocation has taken 496 place. 497 o If the token has been signed, the authorization server MUST 498 validate the signature. 500 If an authorization server fails to perform any applicable check, the 501 resource server could make an errant security decision based on that 502 response. Note that not all of these checks will be applicable to 503 all OAuth 2.0 deployments and it is up to the authorization server to 504 determine which of these checks (and any other checks) apply. 506 If left unprotected and un-throttled, the introspection endpoint 507 could present a means for an attacker to poll a series of possible 508 token values, fishing for a valid token. To prevent this, the 509 authorization server MUST require authentication of protected 510 resources that need to access the introspection endpoint and SHOULD 511 require protected resources to be specifically authorized to call the 512 introspection endpoint. The specifics of this authentication 513 credentials are out of scope of this specification, but commonly 514 these credentials could take the form of any valid client 515 authentication mechanism used with the token endpoint, an OAuth 2.0 516 access token, or other HTTP authorization or authentication 517 mechanism. A single piece of software acting as both a client and a 518 protected resource MAY re-use the same credentials between the token 519 endpoint and the introspection endpoint, though doing so potentially 520 conflates the activities of the client and protected resource 521 portions of the software and the authorization server MAY require 522 separate credentials for each mode. 524 Since the introspection endpoint takes in OAuth 2.0 tokens as 525 parameters and responds with information used to make authorization 526 decisions, the server MUST support TLS 1.2 RFC 5246 [RFC5246] and MAY 527 support additional transport-layer mechanisms meeting its security 528 requirements. When using TLS, the client or protected resource MUST 529 perform a TLS/SSL server certificate check, per RFC 6125 [RFC6125]. 530 Implementation security considerations can be found in 531 Recommendations for Secure Use of TLS and DTLS [TLS.BCP]. 533 In order to prevent the values of access tokens from leaking into 534 server-side logs via query parameters, an authorization server 535 offering token introspection MAY disallow HTTP GET and instead 536 require an HTTP POST method to be used at the introspection endpoint. 538 In order to avoid disclosing internal server state, an introspection 539 response for an inactive token SHOULD NOT contain any additional 540 claims beyond the required "active" claim (with its value set to 541 "false"). 543 Since a protected resource MAY cache the response of the 544 introspection endpoint, designers of an OAuth 2.0 system using this 545 protocol MUST consider the performance and security trade-offs 546 inherent in caching security information such as this. A less 547 aggressive cache with a short timeout will provide the protected 548 resource with more up to date information (due to it needing to query 549 the introspection endpoint more often) at the cost of increased 550 network traffic and load on the introspection endpoint. A more 551 aggressive cache with a longer duration will minimize network traffic 552 and load on the introspection endpoint, but at the risk of stale 553 information about the token. For example, the token may be revoked 554 while the protected resource is relying on the value of the cached 555 response to make authorization decisions. This creates a window 556 during which a revoked token could be used at the protected resource. 557 Consequently, an acceptable cache validity duration needs to be 558 carefully considered given the concerns and sensitivities of the 559 protected resource being accessed and the likelihood of a token being 560 revoked or invalidated in the interim period. Highly sensitive 561 environments can opt to disable caching entirely on the protected 562 resource in order to eliminate the risk of stale cached information 563 entirely, again at the cost of increased network traffic and server 564 load. 566 An authorization server offering token introspection MUST be able to 567 understand the token values being presented to it during this call. 569 The exact means by which this happens is an implementation detail and 570 outside the scope of this specification. For unstructured tokens, 571 this could take the form of a simple server-side database query 572 against a data store containing the context information for the 573 token. For structured tokens, this could take the form of the server 574 parsing the token, validating its signature or other protection 575 mechanisms, and returning the information contained in the token back 576 to the protected resource (allowing the protected resource to be 577 unaware of the token's contents, much like the client). 579 Note that for tokens carrying encrypted information that is needed 580 during the introspection process, the authorization server MUST be 581 able to decrypt and validate the token in order to access this 582 information. Also note that in cases where the authorization server 583 stores no information about the token and has no means of accessing 584 information about the token by parsing the token itself, it can not 585 likely offer an introspection service. 587 5. Privacy Considerations 589 The introspection response may contain privacy-sensitive information 590 such as user identifiers for resource owners. When this is the case, 591 measures MUST be taken to prevent disclosure of this information to 592 unintended parties. One way to limit disclosure is to require 593 authorization to call the introspection endpoint and to limit calls 594 to only registered and trusted protected resource servers. Another 595 method is to transmit user identifiers as opaque service-specific 596 strings, potentially returning different identifiers to each 597 protected resource. 599 If the protected resource sends additional information about the 600 client's request to the authorization server (such as the client's IP 601 address) using an extension of this specification, such information 602 could have additional privacy considerations. However, the nature 603 and implications of such extensions are outside the scope of this 604 specification. 606 Omitting privacy-sensitive information from an introspection response 607 is the simplest way of minimizing privacy issues. 609 6. Acknowledgements 611 Thanks to the OAuth Working Group and the User Managed Access Working 612 Group for feedback and review of this document, and to the various 613 implementors of both the client and server components of this 614 specification. In particular, the author would like to thank Amanda 615 Anganes, John Bradley, Thomas Broyer, Brian Campbell, George 616 Fletcher, Paul Freemantle, Thomas Hardjono, Eve Maler, Josh Mandel, 617 Steve Moore, Mike Schwartz, Prabath Siriwardena, Sarah Squire, and 618 Hannes Tschofennig. 620 7. References 622 7.1. Normative References 624 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 625 Requirement Levels", BCP 14, RFC 2119, March 1997. 627 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 628 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 629 May 2008. 631 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 632 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 634 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 635 Verification of Domain-Based Application Service Identity 636 within Internet Public Key Infrastructure Using X.509 637 (PKIX) Certificates in the Context of Transport Layer 638 Security (TLS)", RFC 6125, March 2011. 640 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 641 6749, October 2012. 643 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 644 Framework: Bearer Token Usage", RFC 6750, October 2012. 646 [RFC7009] Lodderstedt, T., Dronia, S., and M. Scurtescu, "OAuth 2.0 647 Token Revocation", RFC 7009, August 2013. 649 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 650 Interchange Format", RFC 7159, March 2014. 652 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 653 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 655 [W3C.REC-html5-20141028] 656 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 657 Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", 658 World Wide Web Consortium Recommendation REC- 659 html5-20141028, October 2014, 660 . 662 7.2. Informative References 664 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 665 (JWT)", RFC 7519, May 2015. 667 [TLS.BCP] Sheffer, Y., Holz, R., and P. Saint-Andre, 668 "Recommendations for Secure Use of TLS and DTLS", November 669 2014. 671 Appendix A. Use with Proof of Posession Tokens 673 With bearer tokens such as those defined by OAuth 2.0 Bearer Token 674 Usage [RFC6750], the protected resource will have in its possession 675 the entire secret portion of the token for submission to the 676 introspection service. However, for proof-of-possession style 677 tokens, the protected resource will have only a token identifier used 678 during the request, along with the cryptographic signature on the 679 request. The protected resource would be able to submit the token 680 identifier to the authorization server's token endpoint in order to 681 obtain the necessary key information needed to validate the signature 682 on the request. The details of this usage are outside the scope of 683 this specification and will be defined in an extension to this 684 specification. 686 Appendix B. Document History 688 [[ To be removed by the RFC Editor. ]] 690 -09 692 o Updated JOSE, JWT, and OAuth Assertion draft references to final 693 RFC numbers. 695 -08 697 o Added privacy considerations note about extensions. 698 o Added acknowledgements (finally). 700 -07 702 o Created a separate IANA registry for introspection responses, 703 importing the values from JWT. 705 -06 707 o Clarified relationship between AS and RS in introduction. 708 o Used updated TLS text imported from Dyn-Reg drafts. 709 o Clarified definition of active state. 711 o Added some advice on caching responses. 712 o Added security considerations on active state implementation. 713 o Changed user_id to username based on WG feedback. 715 -05 717 o Typo fix. 718 o Updated author information. 719 o Removed extraneous "linewrap" note from examples. 721 - 04 723 o Removed "resource_id" from request. 724 o Added examples. 726 - 03 728 o Updated HTML and HTTP references. 729 o Call for registration of parameters in the JWT registry. 731 - 02 733 o Removed SAML pointer. 734 o Clarified what an "active" token could be. 735 o Explicitly declare introspection request as x-www-form-urlencoded 736 format. 737 o Added extended example. 738 o Made protected resource authentication a MUST. 740 - 01 742 o Fixed casing and consistent term usage. 743 o Incorporated working group comments. 744 o Clarified that authorization servers need to be able to understand 745 the token if they're to introspect it. 746 o Various editorial cleanups. 748 - 00 750 o Created initial IETF drafted based on draft-richer-oauth- 751 introspection-06 with no normative changes. 753 Author's Address 755 Justin Richer (editor) 757 Email: ietf@justin.richer.org