idnits 2.17.1 draft-ietf-oauth-introspection-10.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 (June 22, 2015) is 3228 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 June 22, 2015 4 Intended status: Standards Track 5 Expires: December 24, 2015 7 OAuth 2.0 Token Introspection 8 draft-ietf-oauth-introspection-10 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 December 24, 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. Notational Conventions . . . . . . . . . . . . . . . . . 3 61 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Introspection Endpoint . . . . . . . . . . . . . . . . . . . 4 63 2.1. Introspection Request . . . . . . . . . . . . . . . . . . 4 64 2.2. Introspection Response . . . . . . . . . . . . . . . . . 6 65 2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 8 66 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 67 3.1. OAuth Token Introspection Response Registry . . . . . . . 9 68 3.1.1. Registration Template . . . . . . . . . . . . . . . . 9 69 3.1.2. Initial Registry Contents . . . . . . . . . . . . . . 10 70 4. Security Considerations . . . . . . . . . . . . . . . . . . . 11 71 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 14 72 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 14 73 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 74 7.1. Normative References . . . . . . . . . . . . . . . . . . 14 75 7.2. Informative References . . . . . . . . . . . . . . . . . 15 76 Appendix A. Use with Proof of Posession Tokens . . . . . . . . . 15 77 Appendix B. Document History . . . . . . . . . . . . . . . . . . 16 78 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 17 80 1. Introduction 82 In OAuth 2.0, the contents of tokens are opaque to clients. This 83 means that the client does not need to know anything about the 84 content or structure of the token itself, if there is any. However, 85 there is still a large amount of metadata that may be attached to a 86 token, such as its current validity, approved scopes, and information 87 about the context in which the token was issued. These pieces of 88 information are often vital to protected resources making 89 authorization decisions based on the tokens being presented. Since 90 OAuth 2.0 [RFC6749] does not define a protocol for the resource 91 server to learn meta-information about a token that is has received 92 from an authorization server, several different approaches have been 93 developed to bridge this gap. These include using structured token 94 formats such as JWT [RFC7519] or proprietary inter-service 95 communication mechanisms (such as shared databases and protected 96 enterprise service buses) that convey token information. 98 This specification defines a protocol that allows authorized 99 protected resources to query the authorization server to determine 100 the set of metadata for a given token that was presented to them by 101 an OAuth 2.0 client. This metadata includes whether or not the token 102 is currently active (or if it has expired or otherwise been revoked), 103 what rights of access the token carries (usually conveyed through 104 OAuth 2.0 scopes), and the authorization context in which the token 105 was granted (including who authorized the token and which client it 106 was issued to). Token introspection allows a protected resource to 107 query this information regardless of whether or not it is carried in 108 the token itself, allowing this method to be used along with or 109 independently of structured token values. Additionally, a protected 110 resource can use the mechanism described in this specification to 111 introspect the token in a particular authorization decision context 112 and ascertain the relevant metadata about the token to make this 113 authorization decision appropriately. 115 1.1. Notational Conventions 117 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 118 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 119 document are to be interpreted as described in [RFC2119]. 121 Unless otherwise noted, all the protocol parameter names and values 122 are case sensitive. 124 1.2. Terminology 126 This section defines the terminology used by this specification. 127 This section is a normative portion of this specification, imposing 128 requirements upon implementations. 130 This specification uses the terms "access token", "authorization 131 endpoint", "authorization grant", "authorization server", "client", 132 "client identifier", "protected resource", "refresh token", "resource 133 owner", "resource server", and "token endpoint" defined by OAuth 2.0 134 [RFC6749], and the terms "claim names" and "claim values" defined by 135 JSON Web Token (JWT) [RFC7519]. 137 This specification defines the following terms: 139 Token Introspection 140 The act of inquiring about the current state of an OAuth 2.0 token 141 through use of the network protocol defined in this document. 143 Introspection Endpoint 144 The OAuth 2.0 endpoint through which the token introspection 145 operation is accomplished.. 147 2. Introspection Endpoint 149 The introspection endpoint is an OAuth 2.0 endpoint that takes a 150 parameter representing an OAuth 2.0 token and returns a JSON 151 [RFC7159] document representing the meta information surrounding the 152 token, including whether this token is currently active. The 153 definition of an active token is dependent upon the authorization 154 server, but this is commonly a token that has been issued by this 155 authorization server, is not expired, has not been revoked, and valid 156 for use at the protected resource making the introspection call. 158 The introspection endpoint MUST be protected by a transport-layer 159 security mechanism as described in Section 4. The means by which the 160 protected resource discovers the location of the introspection 161 endpoint are outside the scope of this specification. 163 2.1. Introspection Request 165 The protected resource calls the introspection endpoint using an HTTP 166 POST [RFC7231] request with parameters sent as "application/x-www- 167 form-urlencoded" data as defined in [W3C.REC-html5-20141028]. The 168 protected resource sends a parameter representing the token along 169 with optional parameters representing additional context that is 170 known by the protected resource to aid the authorization server in 171 its response. 173 token REQUIRED. The string value of the token. For access tokens, 174 this is the "access_token" value returned from the token endpoint 175 defined in OAuth 2.0 [RFC6749] section 5.1. For refresh tokens, 176 this is the "refresh_token" value returned from the token endpoint 177 as defined in OAuth 2.0 [RFC6749] section 5.1. Other token types 178 are outside the scope of this specification. 180 token_type_hint OPTIONAL. A hint about the type of the token 181 submitted for introspection. The protected resource MAY pass this 182 parameter to help the authorization server to optimize the token 183 lookup. If the server is unable to locate the token using the 184 given hint, it MUST extend its search across all of its supported 185 token types. An authorization server MAY ignore this parameter, 186 particularly if it is able to detect the token type automatically. 187 Values for this field are defined in the OAuth Token Type Hints 188 registry defined in OAuth Token Revocation [RFC7009]. 190 The endpoint MAY accept other OPTIONAL parameters to provide further 191 context to the query. For instance, an authorization server may 192 desire to know the IP address of the client accessing the protected 193 resource to determine the appropriateness of the token being 194 presented. The definition of any other parameters are outside the 195 scope of this specification, to be defined by service documentation 196 or extensions to this specification. If the authorization server is 197 unable to determine the state of the token without additional 198 information, it SHOULD return an introspection response indicating 199 the token is not active as described in Section 2.2. 201 To prevent token scanning attacks, the endpoint MUST also require 202 some form of authorization to access this endpoint, such as client 203 authentication as described in OAuth 2.0 [RFC6749] or a separate 204 OAuth 2.0 access token such as the bearer token described in OAuth 205 2.0 Bearer Token Usage [RFC6750]. The methods of managing and 206 validating these authentication credentials are out of scope of this 207 specification. 209 For example, the following example shows a protected resource calling 210 the token introspection endpoint to query about an OAuth 2.0 bearer 211 token. The protected resource is using a separate OAuth 2.0 bearer 212 token to authorize this call. 214 Following is a non-normative example request: 216 POST /introspect HTTP/1.1 217 Host: server.example.com 218 Accept: application/json 219 Content-Type: application/x-www-form-urlencoded 220 Authorization: Bearer 23410913-abewfq.123483 222 token=2YotnFZFEjr1zCsicMWpAA 224 In this example, the protected resource uses a client identifier and 225 client secret to authenticate itself to the introspection endpoint as 226 well as send a token type hint. 228 Following is a non-normative example request: 230 POST /introspect HTTP/1.1 231 Host: server.example.com 232 Accept: application/json 233 Content-Type: application/x-www-form-urlencoded 234 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 236 token=mF_9.B5f-4.1JqM&token_type_hint=access_token 238 2.2. Introspection Response 240 The server responds with a JSON object [RFC7159] in "application/ 241 json" format with the following top-level members. 243 active 244 REQUIRED. Boolean indicator of whether or not the presented token 245 is currently active. The specifics of a token's "active" state 246 will vary depending on the implementation of the authorization 247 server, and the information it keeps about its tokens, but a 248 "true" value return for the "active" property will generally 249 indicate that a given token has been issued by this authorization 250 server, has not been revoked by the resource owner, and is within 251 its given time window of validity (e.g. after its issuance time 252 and before its expiration time). See Section 4 for information on 253 implementation of such checks. 255 scope 256 OPTIONAL. A JSON string containing a space-separated list of 257 scopes associated with this token, in the format described in 258 section 3.3 of OAuth 2.0 [RFC6749]. 260 client_id 261 OPTIONAL. Client identifier for the OAuth 2.0 client that 262 requested this token. 264 username 265 OPTIONAL. Human-readable identifier for the resource owner who 266 authorized this token. 268 token_type 269 OPTIONAL. Type of the token as defined in section 5.1 of OAuth 270 2.0 [RFC6749]. 272 exp 273 OPTIONAL. Integer timestamp, measured in the number of seconds 274 since January 1 1970 UTC, indicating when this token will expire, 275 as defined in JWT [RFC7519]. 277 iat 278 OPTIONAL. Integer timestamp, measured in the number of seconds 279 since January 1 1970 UTC, indicating when this token was 280 originally issued, as defined in JWT [RFC7519]. 282 nbf 283 OPTIONAL. Integer timestamp, measured in the number of seconds 284 since January 1 1970 UTC, indicating when this token is not to be 285 used before, as defined in JWT [RFC7519]. 287 sub 288 OPTIONAL. Subject of the token, as defined in JWT [RFC7519]. 289 Usually a machine-readable identifier of the resource owner who 290 authorized this token. 292 aud 293 OPTIONAL. Service-specific string identifier or list of string 294 identifiers representing the intended audience for this token, as 295 defined in JWT [RFC7519]. 297 iss 298 OPTIONAL. String representing the issuer of this token, as 299 defined in JWT [RFC7519]. 301 jti 302 OPTIONAL. String identifier for the token, as defined in JWT 303 [RFC7519]. 305 Specific implementations MAY extend this structure with their own 306 service-specific response names as top-level members of this JSON 307 object. Response names intended to be used across domains MUST be 308 registered in the OAuth Token Introspection Response registry defined 309 in Section 3.1. 311 The authorization server MAY respond differently to different 312 protected resources making the same request. For instance, an 313 authorization server MAY limit which scopes from a given token are 314 returned for each protected resource to prevent protected resources 315 from learning more about the larger network than is necessary for its 316 operation. 318 The response MAY be cached by the protected resource to improve 319 performance and reduce load on the introspection endpoint, but at the 320 cost of liveness of the information used by the protected resource. 321 See Section 4 for more information regarding the trade off when the 322 response is cached. 324 For example, the following response contains a set of information 325 about an active token: 327 Following is a non-normative example response: 329 HTTP/1.1 200 OK 330 Content-Type: application/json 332 { 333 "active": true, 334 "client_id": "l238j323ds-23ij4", 335 "username": "jdoe", 336 "scope": "read write dolphin", 337 "sub": "Z5O3upPC88QrAjx00dis", 338 "aud": "https://protected.example.net/resource", 339 "iss": "https://server.example.com/", 340 "exp": 1419356238, 341 "iat": 1419350238, 342 "extension_field": "twenty-seven" 343 } 345 If the introspection call is properly authorized but the token is not 346 active, does not exist on this server, or the protected resource is 347 not allowed to introspect this particular token, the authorization 348 server MUST return an introspection response with the active field 349 set to false. Note that to avoid disclosing too much of the 350 authorization server's state to a third party, the authorization 351 server SHOULD NOT include any additional information about an 352 inactive token, including why the token is inactive. For example, 353 the response for a token that has been revoked or is otherwise 354 invalid would look like the following: 356 Following is a non-normative example response: 358 HTTP/1.1 200 OK 359 Content-Type: application/json 361 { 362 "active": false 363 } 365 2.3. Error Response 367 If the protected resource uses OAuth 2.0 client credentials to 368 authenticate to the introspection endpoint and its credentials are 369 invalid, the authorization server responds with an HTTP 401 370 (Unauthorized) as described in section 5.2 of OAuth 2.0 [RFC6749]. 372 If the protected resource uses an OAuth 2.0 bearer token to authorize 373 its call to the introspection endpoint and the token used for 374 authorization does not contain sufficient privileges or is otherwise 375 invalid for this request, the authorization server responds with an 376 HTTP 401 code as described in section 3 of OAuth 2.0 Bearer Token 377 Usage [RFC6750]. 379 Note that a properly formed and authorized query for an inactive or 380 otherwise invalid token (or a token the protected resource is not 381 allowed to know about) is not considered an error response by this 382 specification. In these cases, the authorization server MUST instead 383 respond with an introspection response with the "active" field set to 384 "false" as described in Section 2.2. 386 3. IANA Considerations 388 3.1. OAuth Token Introspection Response Registry 390 This specification establishes the OAuth Token Introspection Response 391 registry. 393 OAuth registration client metadata names and descriptions are 394 registered with a Specification Required ([RFC5226]) after a two-week 395 review period on the oauth-ext-review@ietf.org mailing list, on the 396 advice of one or more Designated Experts. However, to allow for the 397 allocation of names prior to publication, the Designated Expert(s) 398 may approve registration once they are satisfied that such a 399 specification will be published. 401 Registration requests sent to the mailing list for review should use 402 an appropriate subject (e.g., "Request to register OAuth Token 403 Introspection Response name: example"). 405 Within the review period, the Designated Expert(s) will either 406 approve or deny the registration request, communicating this decision 407 to the review list and IANA. Denials should include an explanation 408 and, if applicable, suggestions as to how to make the request 409 successful. 411 IANA must only accept registry updates from the Designated Expert(s) 412 and should direct all requests for registration to the review mailing 413 list. 415 3.1.1. Registration Template 417 Name: 418 The name requested (e.g., "example"). This name is case 419 sensitive. Names that match other registered names in a case 420 insensitive manner SHOULD NOT be accepted. Names that match 421 claims registered in the JSON Web Token Claims registry 422 established by [RFC7519] SHOULD have comparable definitions and 423 semantics. 425 Description: 426 Brief description of the metadata value (e.g., "Example 427 description"). 429 Change controller: 430 For Standards Track RFCs, state "IESG". For others, give the name 431 of the responsible party. Other details (e.g., postal address, 432 email address, home page URI) may also be included. 434 Specification document(s): 435 Reference to the document(s) that specify the token endpoint 436 authorization method, preferably including a URI that can be used 437 to retrieve a copy of the document(s). An indication of the 438 relevant sections may also be included but is not required. 440 3.1.2. Initial Registry Contents 442 The initial contents of the OAuth Token Introspection Response 443 registry are: 445 o Name: "active" 446 o Description: Token active status 447 o Change Controller: IESG 448 o Specification Document(s): Section 2.2 of [[ this document ]]. 450 o Name: "username" 451 o Description: User identifier of the resource owner 452 o Change Controller: IESG 453 o Specification Document(s): Section 2.2 of [[ this document ]]. 455 o Name: "client_id" 456 o Description: Client identifier of the client 457 o Change Controller: IESG 458 o Specification Document(s): Section 2.2 of [[ this document ]]. 460 o Name: "scope" 461 o Description: Authorized scopes of the token 462 o Change Controller: IESG 463 o Specification Document(s): Section 2.2 of [[ this document ]]. 465 o Name: "token_type" 466 o Description: Type of the token 467 o Change Controller: IESG 468 o Specification Document(s): Section 2.2 of [[ this document ]]. 470 o Name: "exp" 471 o Description: Expiration timestamp of the token 472 o Change Controller: IESG 473 o Specification Document(s): Section 2.2 of [[ this document ]]. 475 o Name: "iat" 476 o Description: Issuance timestamp of the token 477 o Change Controller: IESG 478 o Specification Document(s): Section 2.2 of [[ this document ]]. 480 o Name: "nbf" 481 o Description: Timestamp which the token is not valid before 482 o Change Controller: IESG 483 o Specification Document(s): Section 2.2 of [[ this document ]]. 485 o Name: "sub" 486 o Description: Subject of the token 487 o Change Controller: IESG 488 o Specification Document(s): Section 2.2 of [[ this document ]]. 490 o Name: "aud" 491 o Description: Audience of the token 492 o Change Controller: IESG 493 o Specification Document(s): Section 2.2 of [[ this document ]]. 495 o Name: "iss" 496 o Description: Issuer of the token 497 o Change Controller: IESG 498 o Specification Document(s): Section 2.2 of [[ this document ]]. 500 o Name: "jti" 501 o Description: Unique identifier of the token 502 o Change Controller: IESG 503 o Specification Document(s): Section 2.2 of [[ this document ]]. 505 4. Security Considerations 507 Since there are many different and valid ways to implement an OAuth 508 2.0 system, there are consequently many ways for an authorization 509 server to determine whether or not a token is currently "active" or 510 not. However, since resource servers using token introspection rely 511 on the authorization server to determine the state of a token, the 512 authorization server MUST perform all applicable checks against a 513 token's state. For instance: 515 o If the token can expire, the authorization server MUST determine 516 whether or not the token has expired. 517 o If the token can be issued before it is able to be used, the 518 authorization server MUST determine whether or not a token's valid 519 period has started yet. 520 o If the token can be revoked after it was issued, the authorization 521 server MUST determine whether or not such a revocation has taken 522 place. 523 o If the token has been signed, the authorization server MUST 524 validate the signature. 525 o If the token can be used only at certain resource servers, the 526 authorization server MUST determine whether or not the token can 527 be used at the resource server making the introspection call. 529 If an authorization server fails to perform any applicable check, the 530 resource server could make an erroneous security decision based on 531 that response. Note that not all of these checks will be applicable 532 to all OAuth 2.0 deployments and it is up to the authorization server 533 to determine which of these checks (and any other checks) apply. 535 If left unprotected and un-throttled, the introspection endpoint 536 could present a means for an attacker to poll a series of possible 537 token values, fishing for a valid token. To prevent this, the 538 authorization server MUST require authentication of protected 539 resources that need to access the introspection endpoint and SHOULD 540 require protected resources to be specifically authorized to call the 541 introspection endpoint. The specifics of this authentication 542 credentials are out of scope of this specification, but commonly 543 these credentials could take the form of any valid client 544 authentication mechanism used with the token endpoint, an OAuth 2.0 545 access token, or other HTTP authorization or authentication 546 mechanism. A single piece of software acting as both a client and a 547 protected resource MAY re-use the same credentials between the token 548 endpoint and the introspection endpoint, though doing so potentially 549 conflates the activities of the client and protected resource 550 portions of the software and the authorization server MAY require 551 separate credentials for each mode. 553 Since the introspection endpoint takes in OAuth 2.0 tokens as 554 parameters and responds with information used to make authorization 555 decisions, the server MUST support TLS 1.2 RFC 5246 [RFC5246] and MAY 556 support additional transport-layer mechanisms meeting its security 557 requirements. When using TLS, the client or protected resource MUST 558 perform a TLS/SSL server certificate check, as specified in RFC 6125 559 [RFC6125]. Implementation security considerations can be found in 560 Recommendations for Secure Use of TLS and DTLS [TLS.BCP]. 562 To prevent the values of access tokens from leaking into server-side 563 logs via query parameters, an authorization server offering token 564 introspection MAY disallow the use of HTTP GET on the introspection 565 endpoint and instead require the HTTP POST method to be used at the 566 introspection endpoint. 568 To avoid disclosing internal server state, an introspection response 569 for an inactive token SHOULD NOT contain any additional claims beyond 570 the required "active" claim (with its value set to "false"). 572 Since a protected resource MAY cache the response of the 573 introspection endpoint, designers of an OAuth 2.0 system using this 574 protocol MUST consider the performance and security trade-offs 575 inherent in caching security information such as this. A less 576 aggressive cache with a short timeout will provide the protected 577 resource with more up to date information (due to it needing to query 578 the introspection endpoint more often) at the cost of increased 579 network traffic and load on the introspection endpoint. A more 580 aggressive cache with a longer duration will minimize network traffic 581 and load on the introspection endpoint, but at the risk of stale 582 information about the token. For example, the token may be revoked 583 while the protected resource is relying on the value of the cached 584 response to make authorization decisions. This creates a window 585 during which a revoked token could be used at the protected resource. 586 Consequently, an acceptable cache validity duration needs to be 587 carefully considered given the concerns and sensitivities of the 588 protected resource being accessed and the likelihood of a token being 589 revoked or invalidated in the interim period. Highly sensitive 590 environments can opt to disable caching entirely on the protected 591 resource to eliminate the risk of stale cached information entirely, 592 again at the cost of increased network traffic and server load. If 593 the response contains the "exp" parameter (expiration), the response 594 MUST NOT be cached beyond the time indicated therein. 596 An authorization server offering token introspection must be able to 597 understand the token values being presented to it during this call. 598 The exact means by which this happens is an implementation detail and 599 outside the scope of this specification. For unstructured tokens, 600 this could take the form of a simple server-side database query 601 against a data store containing the context information for the 602 token. For structured tokens, this could take the form of the server 603 parsing the token, validating its signature or other protection 604 mechanisms, and returning the information contained in the token back 605 to the protected resource (allowing the protected resource to be 606 unaware of the token's contents, much like the client). Note that 607 for tokens carrying encrypted information that is needed during the 608 introspection process, the authorization server must be able to 609 decrypt and validate the token to access this information. Also note 610 that in cases where the authorization server stores no information 611 about the token and has no means of accessing information about the 612 token by parsing the token itself, it can not likely offer an 613 introspection service. 615 5. Privacy Considerations 617 The introspection response may contain privacy-sensitive information 618 such as user identifiers for resource owners. When this is the case, 619 measures MUST be taken to prevent disclosure of this information to 620 unintended parties. One method is to transmit user identifiers as 621 opaque service-specific strings, potentially returning different 622 identifiers to each protected resource. 624 If the protected resource sends additional information about the 625 client's request to the authorization server (such as the client's IP 626 address) using an extension of this specification, such information 627 could have additional privacy considerations. However, the nature 628 and implications of such extensions are outside the scope of this 629 specification. 631 Omitting privacy-sensitive information from an introspection response 632 is the simplest way of minimizing privacy issues. 634 6. Acknowledgements 636 Thanks to the OAuth Working Group and the User Managed Access Working 637 Group for feedback and review of this document, and to the various 638 implementors of both the client and server components of this 639 specification. In particular, the author would like to thank Amanda 640 Anganes, John Bradley, Thomas Broyer, Brian Campbell, George 641 Fletcher, Paul Freemantle, Thomas Hardjono, Eve Maler, Josh Mandel, 642 Steve Moore, Mike Schwartz, Prabath Siriwardena, Sarah Squire, and 643 Hannes Tschofennig. 645 7. References 647 7.1. Normative References 649 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 650 Requirement Levels", BCP 14, RFC 2119, March 1997. 652 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 653 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 654 May 2008. 656 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 657 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 659 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 660 Verification of Domain-Based Application Service Identity 661 within Internet Public Key Infrastructure Using X.509 662 (PKIX) Certificates in the Context of Transport Layer 663 Security (TLS)", RFC 6125, March 2011. 665 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 666 6749, October 2012. 668 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 669 Framework: Bearer Token Usage", RFC 6750, October 2012. 671 [RFC7009] Lodderstedt, T., Dronia, S., and M. Scurtescu, "OAuth 2.0 672 Token Revocation", RFC 7009, August 2013. 674 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 675 Interchange Format", RFC 7159, March 2014. 677 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 678 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 680 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 681 (JWT)", RFC 7519, May 2015. 683 [W3C.REC-html5-20141028] 684 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 685 Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", 686 World Wide Web Consortium Recommendation REC- 687 html5-20141028, October 2014, 688 . 690 7.2. Informative References 692 [TLS.BCP] Sheffer, Y., Holz, R., and P. Saint-Andre, 693 "Recommendations for Secure Use of TLS and DTLS", November 694 2014. 696 Appendix A. Use with Proof of Posession Tokens 698 With bearer tokens such as those defined by OAuth 2.0 Bearer Token 699 Usage [RFC6750], the protected resource will have in its possession 700 the entire secret portion of the token for submission to the 701 introspection service. However, for proof-of-possession style 702 tokens, the protected resource will have only a token identifier used 703 during the request, along with the cryptographic signature on the 704 request. The protected resource would be able to submit the token 705 identifier to the authorization server's token endpoint to obtain the 706 necessary key information needed to validate the signature on the 707 request. The details of this usage are outside the scope of this 708 specification and will be defined in an extension to this 709 specification. 711 Appendix B. Document History 713 [[ To be removed by the RFC Editor. ]] 715 -10 717 o Added missing 2119 section to terminology. 718 o Removed optional HTTP GET at introspection endpoint. 719 o Added terminology. 720 o Renamed this "a protocol" instead of "web API". 721 o Moved JWT to normative reference. 722 o Reworded definition of "scope" value. 723 o Clarified extensibility of input parameters. 724 o Noted that discover is out of scope. 725 o Fixed several typos and imprecise references. 727 -09 729 o Updated JOSE, JWT, and OAuth Assertion draft references to final 730 RFC numbers. 732 -08 734 o Added privacy considerations note about extensions. 735 o Added acknowledgements (finally). 737 -07 739 o Created a separate IANA registry for introspection responses, 740 importing the values from JWT. 742 -06 744 o Clarified relationship between AS and RS in introduction. 745 o Used updated TLS text imported from Dyn-Reg drafts. 746 o Clarified definition of active state. 747 o Added some advice on caching responses. 748 o Added security considerations on active state implementation. 749 o Changed user_id to username based on WG feedback. 751 -05 753 o Typo fix. 754 o Updated author information. 756 o Removed extraneous "linewrap" note from examples. 758 - 04 760 o Removed "resource_id" from request. 761 o Added examples. 763 - 03 765 o Updated HTML and HTTP references. 766 o Call for registration of parameters in the JWT registry. 768 - 02 770 o Removed SAML pointer. 771 o Clarified what an "active" token could be. 772 o Explicitly declare introspection request as x-www-form-urlencoded 773 format. 774 o Added extended example. 775 o Made protected resource authentication a MUST. 777 - 01 779 o Fixed casing and consistent term usage. 780 o Incorporated working group comments. 781 o Clarified that authorization servers need to be able to understand 782 the token if they're to introspect it. 783 o Various editorial cleanups. 785 - 00 787 o Created initial IETF drafted based on draft-richer-oauth- 788 introspection-06 with no normative changes. 790 Author's Address 792 Justin Richer (editor) 794 Email: ietf@justin.richer.org