idnits 2.17.00 (12 Aug 2021) /tmp/idnits62612/draft-ietf-oauth-introspection-05.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 (February 9, 2015) is 2658 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 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) == Outdated reference: draft-ietf-oauth-json-web-token has been published as RFC 7519 Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 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 4 Intended status: Standards Track February 9, 2015 5 Expires: August 13, 2015 7 OAuth 2.0 Token Introspection 8 draft-ietf-oauth-introspection-05 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 August 13, 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 . . . . . . . . . . . . . . . . . . . . . 7 65 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 66 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 67 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 10 68 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 69 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 70 7.1. Normative References . . . . . . . . . . . . . . . . . . 10 71 7.2. Informative References . . . . . . . . . . . . . . . . . 11 72 Appendix A. Document History . . . . . . . . . . . . . . . . . . 11 73 Appendix B. Use with Proof of Posession Tokens . . . . . . . . . 12 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 76 1. Introduction 78 In OAuth 2.0, the contents of tokens are opaque to clients. This 79 means that the client does not need to know anything about the 80 content or structure of the token itself, if there is any. However, 81 there is still a large amount of metadata that may be attached to a 82 token, such as its current validity, approved scopes, and information 83 about the context in which the token was issued. These pieces of 84 information are often vital to protected resources making 85 authorization decisions based on the tokens being presented. Since 86 OAuth 2.0 [RFC6749] defines no direct relationship between the 87 authorization server and the protected resource, only that they must 88 have an agreement on the tokens themselves, there have been many 89 different approaches to bridging this gap. These include using 90 structured token formats such as JWT [JWT] or proprietary inter- 91 service communication mechanisms (such as shared databases and 92 protected enterprise service buses) that convey token information. 94 This specification defines an interoperable web API that allows 95 authorized protected resources to query the authorization server to 96 determine the set of metadata for a given token that was presented to 97 them by an OAuth 2.0 client. This metadata includes whether or not 98 the token is currently active (or if it has expired or otherwise been 99 revoked), what rights of access the token carries (usually conveyed 100 through OAuth 2.0 scopes), and the authorization context in which the 101 token was granted (including who authorized the token and which 102 client it was issued to). Token introspection allows a protected 103 resource to query this information regardless of whether or not it is 104 carried in the token itself, allowing this method to be used along 105 with or independently of structured token values. Additionally, a 106 protected resource can use the mechanism described in this 107 specification to introspect the token in a particular authorization 108 decision context and ascertain the relevant metadata about the token 109 in order to make this authorization decision appropriately. 111 1.1. Terminology 113 This section defines the terminology used by this specification. 114 This section is a normative portion of this specification, imposing 115 requirements upon implementations. 117 This specification uses the terms "access token", "authorization 118 endpoint", "authorization grant", "authorization server", "client", 119 "client identifier", "protected resource", "refresh token", "resource 120 owner", "resource server", and "token endpoint" defined by OAuth 2.0 121 [RFC6749], and the terms "claim names" and "claim values" defined by 122 JSON Web Token (JWT) [JWT]. 124 2. Introspection Endpoint 126 The introspection endpoint is an OAuth 2.0 endpoint that takes a 127 parameter representing an OAuth 2.0 token and returns a JSON 128 [RFC7159] document representing the meta information surrounding the 129 token, including whether this token is currently active. The 130 definition of an active token is up to the authorization server, but 131 this is commonly a token that has been issued by this authorization 132 server, is not expired, has not been revoked, and is within the 133 purview of the protected resource making the introspection call. 135 The introspection endpoint MUST be protected by TLS of at least 136 version 1.2 RFC 5246 [RFC5246] and MAY support additional transport- 137 layer mechanisms meeting its security requirements. When using TLS, 138 the protected resource MUST perform a TLS/SSL server certificate 139 check, per RFC 6125 [RFC6125]. Implementation security 140 considerations can be found in Recommendations for Secure Use of TLS 141 and DTLS [TLS.BCP]. 143 2.1. Introspection Request 145 The protected resource calls the introspection endpoint using an HTTP 146 POST [RFC7231] request with parameters sent as "application/x-www- 147 form-urlencoded" data as defined in [W3C.REC-html5-20141028]. The 148 authorization server MAY allow an HTTP GET [RFC7231] request with 149 parameters passed in the query string as defined in 150 [W3C.REC-html5-20141028]. The protected resource sends a parameter 151 representing the token along with optional parameters representing 152 additional context that is known by the protected resource to aid the 153 authorization server in its response. 155 token REQUIRED. The string value of the token. For access tokens, 156 this is the "access_token" value returned from the token endpoint 157 defined in OAuth 2.0 [RFC6749] section 5.1. For refresh tokens, 158 this is the "refresh_token" value returned from the token endpoint 159 as defined in OAuth 2.0 [RFC6749] section 5.1. Other token types 160 are outside the scope of this specification. 162 token_type_hint OPTIONAL. A hint about the type of the token 163 submitted for introspection. The protected resource MAY pass this 164 parameter in order to help the authorization server to optimize 165 the token lookup. If the server is unable to locate the token 166 using the given hint, it MUST extend its search across all of its 167 supported token types. An authorization server MAY ignore this 168 parameter, particularly if it is able to detect the token type 169 automatically. Values for this field are defined in OAuth Token 170 Revocation [RFC7009]. 172 The endpoint MAY allow other parameters to provide further context to 173 the query. For instance, an authorization service may need to know 174 the IP address of the client accessing the protected resource in 175 order to determine the appropriateness of the token being presented. 177 To prevent unauthorized token scanning attacks, the endpoint MUST 178 also require some form of authorization to access this endpoint, such 179 as client authentication as described in OAuth 2.0 [RFC6749] or a 180 separate OAuth 2.0 access token such as the bearer token described in 181 OAuth 2.0 Bearer Token Usage [RFC6750]. The methods of managing and 182 validating these authentication credentials are out of scope of this 183 specification. 185 For example, the following example shows a protected resource calling 186 the token introspection endpoint to query about an OAuth 2.0 bearer. 187 The protected resource is using a separate OAuth 2.0 bearer token to 188 authorize this call. 190 Following is a non-normative example request: 192 POST /introspect HTTP/1.1 193 Host: server.example.com 194 Accept: application/json 195 Content-Type: application/x-www-form-urlencoded 196 Authorization: Bearer 23410913-abewfq.123483 198 token=2YotnFZFEjr1zCsicMWpAA 200 In this example, the protected resource uses a client identifier and 201 client secret to authenticate itself to the introspection endpoint as 202 well as send a token type hint. 204 Following is a non-normative example request: 206 POST /introspect HTTP/1.1 207 Host: server.example.com 208 Accept: application/json 209 Content-Type: application/x-www-form-urlencoded 210 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 212 token=mF_9.B5f-4.1JqM&token_type_hint=access_token 214 2.2. Introspection Response 216 The server responds with a JSON object [RFC7159] in "application/ 217 json" format with the following top-level members. 219 active 220 REQUIRED. Boolean indicator of whether or not the presented token 221 is currently active. The authorization server determines whether 222 and when a given token is in an active state. 224 scope 225 OPTIONAL. A space-separated list of strings representing the 226 scopes associated with this token, in the format described in 227 section 3.3 of OAuth 2.0 [RFC6749]. 229 client_id 230 OPTIONAL. Client identifier for the OAuth 2.0 client that 231 requested this token. 233 user_id 234 OPTIONAL. Human-readable identifier for the user who authorized 235 this token. 237 token_type 238 OPTIONAL. Type of the token as defined in section 5.1 of OAuth 239 2.0 [RFC6749]. 241 The response MAY include any claims defined as JWT [JWT] claim names 242 and carry the same semantics and syntax, such as the following: 244 exp 245 OPTIONAL. Integer timestamp, measured in the number of seconds 246 since January 1 1970 UTC, indicating when this token will expire. 248 iat 249 OPTIONAL. Integer timestamp, measured in the number of seconds 250 since January 1 1970 UTC, indicating when this token was 251 originally issued. 253 nbf 254 OPTIONAL. Integer timestamp, measured in the number of seconds 255 since January 1 1970 UTC, indicating when this token is not to be 256 used before. 258 sub 259 OPTIONAL. Subject of the token. Usually a machine-readable 260 identifier of the resource owner who authorized this token 262 aud 263 OPTIONAL. Service-specific string identifier or list of string 264 identifiers representing the intended audience for this token. 266 iss 267 OPTIONAL. String representing the issuer of this token. 269 jti 270 OPTIONAL. String identifier for the token. 272 Specific implementations MAY extend this structure with their own 273 service-specific pieces of information as top-level members of this 274 JSON object. 276 The authorization server MAY respond differently to different 277 protected resources making the same request. For instance, an 278 authorization server MAY limit which scopes from a given token for 279 each protected resources in order to prevent protected resources from 280 learning more about the larger network than is necessary for their 281 function. 283 The response MAY be cached by the protected resource. 285 For example, the following response contains a set of information 286 about an active token: 288 Following is a non-normative example response: 290 HTTP/1.1 200 OK 291 Content-Type: application/json 293 { 294 "active": true, 295 "client_id": "l238j323ds-23ij4", 296 "user_id": "jdoe", 297 "scope": "read write dolphin", 298 "sub": "Z5O3upPC88QrAjx00dis", 299 "aud": "https://protected.example.net/resource", 300 "iss": "https://server.example.com/", 301 "exp": 1419356238, 302 "iat": 1419350238, 303 "extension_field": "twenty-seven" 304 } 306 If the introspection call is properly authorized but the token is not 307 active, does not exist on this server, or the protected resource is 308 not allowed to introspect this particular token, the authorization 309 server MUST return an introspection response with the active field 310 set to false. Note that in order to avoid disclosing too much of the 311 authorization server's state to a third party, the authorization 312 server SHOULD NOT include any additional information about an 313 inactive token, including why the token is inactive. For example, 314 the response for a token that has been revoked or is otherwise 315 invalid would look like the following: 317 Following is a non-normative example response: 319 HTTP/1.1 200 OK 320 Content-Type: application/json 322 { 323 "active": false 324 } 326 2.3. Error Response 328 If the protected resource uses OAuth 2.0 client credentials to 329 authenticate to the introspection endpoint and its credentials are 330 invalid, the authorization server responds with an HTTP 401 331 (Unauthorized) as described in section 5.2 of OAuth 2.0 [RFC6749]. 333 If the protected resource uses an OAuth 2.0 bearer token to authorize 334 its call to the introspection endpoint and the token used for 335 authorization does not contain sufficient privileges or is otherwise 336 invalid for this request, the authorization server responds with an 337 HTTP 401 code as described in section 3 of OAuth 2.0 Bearer Token 338 Usage [RFC6750]. 340 Note that a properly formed and authorized query for an inactive or 341 otherwise invalid token (or a token the protected resource is not 342 allowed to know about) is not considered an error response by this 343 specification. In these cases, the authorization server MUST instead 344 respond with an introspection response with the "active" field set to 345 "false" as described in Section 2.2. 347 3. IANA Considerations 349 This specification requests IANA to register the following values 350 into the IANA JSON Web Token Claims registry for JWT Claim Names. 352 o Claim Name: "active" 353 o Claim Description: Token active status 354 o Change Controller: IESG 355 o Specification Document(s): Section 2.2 of [[ this document ]]. 357 o Claim Name: "user_id" 358 o Claim Description: User identifier of the resource owner 359 o Change Controller: IESG 360 o Specification Document(s): Section 2.2 of [[ this document ]]. 362 o Claim Name: "client_id" 363 o Claim Description: Client identifier of the client 364 o Change Controller: IESG 365 o Specification Document(s): Section 2.2 of [[ this document ]]. 367 o Claim Name: "scope" 368 o Claim Description: Authorized scopes of the token 369 o Change Controller: IESG 370 o Specification Document(s): Section 2.2 of [[ this document ]]. 372 o Claim Name: "token_type" 373 o Claim Description: Type of the token 374 o Change Controller: IESG 375 o Specification Document(s): Section 2.2 of [[ this document ]]. 377 4. Security Considerations 379 If left unprotected and un-throttled, the introspection endpoint 380 could present a means for an attacker to poll a series of possible 381 token values, fishing for a valid token. To prevent this, the 382 authorization server MUST require authentication of protected 383 resources that need to access the introspection endpoint and SHOULD 384 require protected resources to be specifically authorized to call the 385 introspection endpoint. The specifics of this authentication 386 credentials are out of scope of this specification, but commonly 387 these credentials could take the form of any valid client 388 authentication mechanism used with the token endpoint, an OAuth 2.0 389 access token, or other HTTP authorization or authentication 390 mechanism. A single piece of software acting as both a client and a 391 protected resource MAY re-use the same credentials between the token 392 endpoint and the introspection endpoint, though doing so potentially 393 conflates the activities of the client and protected resource 394 portions of the software and the authorization server MAY require 395 separate credentials for each mode. 397 Since the introspection endpoint takes in OAuth 2.0 tokens as 398 parameters, the server MUST support TLS 1.2 RFC 5246 [RFC5246] and 399 MAY support additional transport-layer mechanisms meeting its 400 security requirements. When using TLS, the client or protected 401 resource MUST perform a TLS/SSL server certificate check, per RFC 402 6125 [RFC6125]. Implementation security considerations can be found 403 in Recommendations for Secure Use of TLS and DTLS [TLS.BCP]. 405 In order to prevent the values of access tokens being from leaking 406 into server-side logs via query parameters, an authorization server 407 offering token introspection MAY disallow HTTP GET and instead 408 require an HTTP POST method only to the introspection endpoint. 410 In order to avoid disclosing internal server state, an introspection 411 response for an inactive token SHOULD NOT contain any additional 412 claims beyond the required "active" claim (with its value set to 413 "false"). 415 An authorization server offering token introspection MUST be able to 416 understand the token values being presented to it during this call. 417 The exact means by which this happens is an implementation detail and 418 outside the scope of this specification. For unstructured tokens, 419 this could take the form of a simple server-side database query 420 against a data store containing the context information for the 421 token. For structured tokens, this could take the form of the server 422 parsing the token, validating its signature or other protection 423 mechanisms, and returning the information contained in the token back 424 to the protected resource (allowing the protected resource to be 425 unaware of the token's contents, much like the client). 427 Note that for tokens carrying encrypted information that is needed 428 during the introspection process, the authorization server MUST be 429 able to decrypt and validate the token in order to access this 430 information. Also note that in cases where the authorization server 431 stores no information about the token and has no means of accessing 432 information about the token by parsing the token itself, it can not 433 likely offer an introspection service. 435 5. Privacy Considerations 437 The introspection response may contain privacy-sensitive information 438 such as user identifiers for resource owners. When this is the case, 439 measures MUST be taken to prevent disclosure of this information to 440 unintended parties. One way to limit disclosure is to require 441 authorization to call the introspection endpoint and to limit calls 442 to only registered and trusted protected resource servers. Another 443 method is to transmit user identifiers as opaque service-specific 444 strings, potentially returning different identifiers to each 445 protected resource. Omitting privacy-sensitive information from an 446 introspection response is the simplest way of minimizing privacy 447 issues. 449 6. Acknowledgements 451 Thanks to the OAuth Working Group and the UMA Working Group for 452 feedback. 454 7. References 456 7.1. Normative References 458 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 459 Requirement Levels", BCP 14, RFC 2119, March 1997. 461 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 462 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 464 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 465 Verification of Domain-Based Application Service Identity 466 within Internet Public Key Infrastructure Using X.509 467 (PKIX) Certificates in the Context of Transport Layer 468 Security (TLS)", RFC 6125, March 2011. 470 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 471 6749, October 2012. 473 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 474 Framework: Bearer Token Usage", RFC 6750, October 2012. 476 [RFC7009] Lodderstedt, T., Dronia, S., and M. Scurtescu, "OAuth 2.0 477 Token Revocation", RFC 7009, August 2013. 479 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 480 Interchange Format", RFC 7159, March 2014. 482 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 483 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 485 [W3C.REC-html5-20141028] 486 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 487 Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", 488 World Wide Web Consortium Recommendation REC- 489 html5-20141028, October 2014, 490 . 492 7.2. Informative References 494 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 495 (JWT)", draft-ietf-oauth-json-web-token (work in 496 progress), July 2014. 498 [TLS.BCP] Sheffer, Y., Holz, R., and P. Saint-Andre, 499 "Recommendations for Secure Use of TLS and DTLS", November 500 2014. 502 Appendix A. Document History 504 [[ To be removed by the RFC Editor. ]] 506 -05 508 o Typo fix. 510 o Updated author information. 512 o Removed extraneous "linewrap" note from examples. 514 - 04 516 o Removed "resource_id" from request. 518 o Added examples. 520 - 03 521 o Updated HTML and HTTP references. 523 o Call for registration of parameters in the JWT registry. 525 - 02 527 o Removed SAML pointer. 529 o Clarified what an "active" token could be. 531 o Explicitly declare introspection request as x-www-form-urlencoded 532 format. 534 o Added extended example. 536 o Made protected resource authentication a MUST. 538 - 01 540 o Fixed casing and consistent term usage. 542 o Incorporated working group comments. 544 o Clarified that authorization servers need to be able to understand 545 the token if they're to introspect it. 547 o Various editorial cleanups. 549 - 00 551 o Created initial IETF drafted based on draft-richer-oauth- 552 introspection-06 with no normative changes. 554 Appendix B. Use with Proof of Posession Tokens 556 With bearer tokens such as those defined by OAuth 2.0 Bearer Token 557 Usage [RFC6750], the protected resource will have in its possession 558 the entire secret portion of the token for submission to the 559 introspection service. However, for proof-of-possession style 560 tokens, the protected resource will have only a token identifier used 561 during the request, along with the cryptographic signature on the 562 request. The protected resource would be able to submit the token 563 identifier to the authorization server's token endpoint in order to 564 obtain the necessary key information needed to validate the signature 565 on the request. The details of this usage are outside the scope of 566 this specification and should be defined in an extension to this 567 specification. 569 Author's Address 571 Justin Richer (editor) 573 Email: ietf@justin.richer.org