idnits 2.17.1 draft-ietf-oauth-introspection-03.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 (December 6, 2014) is 3427 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) Summary: 4 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group J. Richer, Ed. 3 Internet-Draft The MITRE Corporation 4 Intended status: Standards Track December 6, 2014 5 Expires: June 9, 2015 7 OAuth 2.0 Token Introspection 8 draft-ietf-oauth-introspection-03 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 June 9, 2015. 42 Copyright Notice 44 Copyright (c) 2014 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 . . . . . . . . . . . . . . . . . . . . . 6 65 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 66 4. Security Considerations . . . . . . . . . . . . . . . . . . . 7 67 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 8 68 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8 69 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 70 7.1. Normative References . . . . . . . . . . . . . . . . . . 8 71 7.2. Informative References . . . . . . . . . . . . . . . . . 9 72 Appendix A. Document History . . . . . . . . . . . . . . . . . . 9 73 Appendix B. Non-normative Examples . . . . . . . . . . . . . . . 10 74 Appendix C. Use with Proof of Posession Tokens . . . . . . . . . 12 75 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 77 1. Introduction 79 In OAuth 2.0, the contents of tokens are opaque to clients. This 80 means that the client does not need to know anything about the 81 content or structure of the token itself, if there is any. However, 82 there is still a large amount of metadata that may be attached to a 83 token, such as its current validity, approved scopes, and information 84 about the context in which the token was issued. These pieces of 85 information are often vital to protected resources making 86 authorization decisions based on the tokens being presented. Since 87 OAuth 2.0 [RFC6749] defines no direct relationship between the 88 authorization server and the protected resource, only that they must 89 have an agreement on the tokens themselves, there have been many 90 different approaches to bridging this gap. These include using 91 structured token formats such as JWT [JWT] or proprietary inter- 92 service communication mechanisms (such as shared databases and 93 protected enterprise service buses) that convey token information. 95 This specification defines an interoperable web API that allows 96 authorized protected resources to query the authorization server to 97 determine the set of metadata for a given token that was presented to 98 them by an OAuth 2.0 client. This metadata includes whether or not 99 the token is currently active (or if it has expired or otherwise been 100 revoked), what rights of access the token carries (usually conveyed 101 through OAuth 2.0 scopes), and the authorization context in which the 102 token was granted (including who authorized the token and which 103 client it was issued to). Token introspection allows a protected 104 resource to query this information regardless of whether or not it is 105 carried in the token itself, allowing this method to be used along 106 with or independently of structured token values. Additionally, a 107 protected resource can use the mechanism described in this 108 specification to introspect the token in a particular authorization 109 decision context and ascertain the relevant metadata about the token 110 in order to make this authorization decision appropriately. 112 1.1. Terminology 114 This section defines the terminology used by this specification. 115 This section is a normative portion of this specification, imposing 116 requirements upon implementations. 118 This specification uses the terms "access token", "authorization 119 endpoint", "authorization grant", "authorization server", "client", 120 "client identifier", "protected resource", "refresh token", "resource 121 owner", "resource server", and "token endpoint" defined by OAuth 2.0 122 [RFC6749], and the terms "claim names" and "claim values" defined by 123 JSON Web Token (JWT) [JWT]. 125 2. Introspection Endpoint 127 The introspection endpoint is an OAuth 2.0 endpoint that takes a 128 parameter representing an OAuth 2.0 token and returns a JSON 129 [RFC7159] document representing the meta information surrounding the 130 token, including whether this token is currently active. The 131 definition of an active token is up to the authorization server, but 132 this is commonly a token that has been issued by this authorization 133 server, is not expired, has not been revoked, and is within the 134 purview of the protected resource making the introspection call. 136 The introspection endpoint MUST be protected by TLS of at least 137 version 1.2 RFC 5246 [RFC5246] and MAY support additional transport- 138 layer mechanisms meeting its security requirements. When using TLS, 139 the protected resource MUST perform a TLS/SSL server certificate 140 check, per RFC 6125 [RFC6125]. Implementation security 141 considerations can be found in Recommendations for Secure Use of TLS 142 and DTLS [TLS.BCP]. 144 2.1. Introspection Request 146 The protected resource calls the introspection endpoint using an HTTP 147 POST [RFC7231] request with parameters sent as "application/x-www- 148 form-urlencoded" data as defined in [W3C.REC-html5-20141028]. The 149 authorization server MAY allow an HTTP GET [RFC7231] request with 150 parameters passed in the query string as defined in 151 [W3C.REC-html5-20141028]. The protected resource sends a parameter 152 representing the token along with optional parameters representing 153 additional context that is known by the protected resource to aid the 154 authorization server in its response. 156 token REQUIRED. The string value of the token. For access tokens, 157 this is the "access_token" value returned from the token endpoint 158 defined in OAuth 2.0 [RFC6749] section 5.1. For refresh tokens, 159 this is the "refresh_token" value returned from the token endpoint 160 as defined in OAuth 2.0 [RFC6749] section 5.1. Other token types 161 are outside the scope of this specification. 163 resource_id OPTIONAL. A service-specific string identifying the 164 resource that the token is being used for. This value allows the 165 protected resource to convey to the authorization server the 166 context in which the token is being used at the protected 167 resource, allowing the authorization server to tailor its response 168 accordingly if desired. 170 token_type_hint OPTIONAL. A hint about the type of the token 171 submitted for introspection. The protected resource re MAY pass 172 this parameter in order to help the authorization server to 173 optimize the token lookup. If the server is unable to locate the 174 token using the given hint, it MUST extend its search across all 175 of its supported token types. An authorization server MAY ignore 176 this parameter, particularly if it is able to detect the token 177 type automatically. Values for this field are defined in OAuth 178 Token Revocation [RFC7009]. 180 The endpoint MAY allow other parameters to provide further context to 181 the query. For instance, an authorization service may need to know 182 the IP address of the client accessing the protected resource in 183 order to determine the appropriateness of the token being presented. 185 To prevent unauthorized token scanning attacks, the endpoint MUST 186 also require some form of authorization to access this endpoint, such 187 as client authentication as described in OAuth 2.0 [RFC6749] or a 188 separate OAuth 2.0 access token such as the bearer token described in 189 OAuth 2.0 Bearer Token Usage [RFC6750]. The methods of managing and 190 validating these authentication credentials are out of scope of this 191 specification. 193 2.2. Introspection Response 195 The server responds with a JSON object [RFC7159] in "application/ 196 json" format with the following top-level members. Several of these 198 active REQUIRED. Boolean indicator of whether or not the presented 199 token is currently active. The authorization server determines 200 whether and when a given token is in an active state. 202 scope OPTIONAL. A space-separated list of strings representing the 203 scopes associated with this token, in the format described in 204 section 3.3 of OAuth 2.0 [RFC6749]. 206 client_id OPTIONAL. Client identifier for the OAuth 2.0 client that 207 requested this token. 209 user_id OPTIONAL. Human-readable identifier for the user who 210 authorized this token. 212 token_type OPTIONAL. Type of the token as defined in section 5.1 of 213 OAuth 2.0 [RFC6749]. 215 The response MAY include any claims defined as JWT [JWT] claim names 216 and carry the same semantics and syntax, such as the following: 218 exp OPTIONAL. Integer timestamp, measured in the number of seconds 219 since January 1 1970 UTC, indicating when this token will expire. 221 iat OPTIONAL. Integer timestamp, measured in the number of seconds 222 since January 1 1970 UTC, indicating when this token was 223 originally issued. 225 nbf OPTIONAL. Integer timestamp, measured in the number of seconds 226 since January 1 1970 UTC, indicating when this token is not to be 227 used before. 229 sub OPTIONAL. Subject of the token. Usually a machine-readable 230 identifier of the resource owner who authorized this token 232 aud OPTIONAL. Service-specific string identifier or list of string 233 identifiers representing the intended audience for this token. 235 iss OPTIONAL. String representing the issuer of this token. 237 jti OPTIONAL. String identifier for the token. 239 Specific implementations MAY extend this structure with their own 240 service-specific pieces of information. 242 The response MAY be cached by the protected resource. 244 The authorization server MAY respond differently to different 245 protected resources making the same request. 247 Note that in order to avoid disclosing too much of the authorization 248 server's state to a third party, the authorization server SHOULD NOT 249 include any additional information about an inactive token, including 250 why the token is inactive. 252 2.3. Error Response 254 If the protected resource uses OAuth 2.0 client credentials to 255 authenticate to the introspection endpoint and its credentials are 256 invalid, the authorization server responds with an HTTP 401 257 (Unauthorized) as described in section 5.2 of OAuth 2.0 [RFC6749]. 259 If the protected resource uses an OAuth 2.0 bearer token to authorize 260 its call to the introspection endpoint and the token used for 261 authorization does not contain sufficient privileges or is otherwise 262 invalid for this request, the authorization server responds with an 263 HTTP 401 code as described in section 3 of OAuth 2.0 Bearer Token 264 Usage [RFC6750]. 266 3. IANA Considerations 268 This specification requests IANA to register the following values 269 into the IANA JSON Web Token Claims registry for JWT Claim Names. 271 o Claim Name: "active" 272 o Claim Description: Token active status 273 o Change Controller: IESG 274 o Specification Document(s): Section 2.2 of [[ this document ]]. 276 o Claim Name: "user_id" 277 o Claim Description: User identifier of the resource owner 278 o Change Controller: IESG 279 o Specification Document(s): Section 2.2 of [[ this document ]]. 281 o Claim Name: "client_id" 282 o Claim Description: Client identifier of the client 283 o Change Controller: IESG 284 o Specification Document(s): Section 2.2 of [[ this document ]]. 286 o Claim Name: "scope" 287 o Claim Description: Authorized scopes of the token 288 o Change Controller: IESG 289 o Specification Document(s): Section 2.2 of [[ this document ]]. 291 o Claim Name: "token_type" 292 o Claim Description: Type of the token 293 o Change Controller: IESG 294 o Specification Document(s): Section 2.2 of [[ this document ]]. 296 4. Security Considerations 298 If left unprotected and un-throttled, the introspection endpoint 299 could present a means for an attacker to poll a series of possible 300 token values, fishing for a valid token. To prevent this, the 301 authorization server MUST require authentication of protected 302 resources that need to access the introspection endpoint and SHOULD 303 require protected resources to be specifically authorized to call the 304 introspection endpoint. The specifics of this authentication 305 credentials are out of scope of this specification, but commonly 306 these credentials could take the form of any valid client 307 authentication mechanism used with the token endpoint, an OAuth 2.0 308 access token, or other HTTP authorization or authentication 309 mechanism. A single piece of software acting as both a client and a 310 protected resource MAY re-use the same credentials between the token 311 endpoint and the introspection endpoint, though doing so potentially 312 conflates the activities of the client and protected resource 313 portions of the software and the authorization server MAY require 314 separate credentials for each mode. 316 Since the introspection endpoint takes in OAuth 2.0 tokens as 317 parameters, the server MUST support TLS 1.2 RFC 5246 [RFC5246] and 318 MAY support additional transport-layer mechanisms meeting its 319 security requirements. When using TLS, the client or protected 320 resource MUST perform a TLS/SSL server certificate check, per RFC 321 6125 [RFC6125]. Implementation security considerations can be found 322 in Recommendations for Secure Use of TLS and DTLS [TLS.BCP]. 324 In order to prevent the values of access tokens being from leaking 325 into server-side logs via query parameters, an authorization server 326 offering token introspection MAY disallow HTTP GET and instead 327 require an HTTP POST method only to the introspection endpoint. 329 In order to avoid disclosing internal server state, an introspection 330 response for an inactive token SHOULD NOT contain any additional 331 claims beyond the required "active" claim (with its value set to 332 "false"). 334 An authorization server offering token introspection MUST be able to 335 understand the token values being presented to it during this call. 336 The exact means by which this happens is an implementation detail and 337 outside the scope of this specification. For unstructured tokens, 338 this could take the form of a simple server-side database query 339 against a data store containing the context information for the 340 token. For structured tokens, this could take the form of the server 341 parsing the token, validating its signature or other protection 342 mechanisms, and returning the information contained in the token back 343 to the protected resource (allowing the protected resource to be 344 unaware of the token's contents, much like the client). 346 Note that for tokens carrying encrypted information that is needed 347 during the introspection process, the authorization server MUST be 348 able to decrypt and validate the token in order to access this 349 information. Also note that in cases where the authorization server 350 stores no information about the token and has no means of accessing 351 information about the token by parsing the token itself, it can not 352 likely offer an introspection service. 354 5. Privacy Considerations 356 The introspection response may contain privacy-sensitive information 357 such as user identifiers for resource owners. When this is the case, 358 measures MUST be taken to prevent disclosure of this information to 359 unintended parties. One way to limit disclosure is to require 360 authorization to call the introspection endpoint and to limit calls 361 to only registered and trusted protected resource servers. Another 362 method is to transmit user identifiers as opaque service-specific 363 strings, potentially returning different identifiers to each 364 protected resource. Omitting privacy-sensitive information from an 365 introspection response is the simplest way of minimizing privacy 366 issues. 368 6. Acknowledgements 370 Thanks to the OAuth Working Group and the UMA Working Group for 371 feedback. 373 7. References 375 7.1. Normative References 377 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 378 Requirement Levels", BCP 14, RFC 2119, March 1997. 380 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 381 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 383 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 384 Verification of Domain-Based Application Service Identity 385 within Internet Public Key Infrastructure Using X.509 386 (PKIX) Certificates in the Context of Transport Layer 387 Security (TLS)", RFC 6125, March 2011. 389 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 390 6749, October 2012. 392 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 393 Framework: Bearer Token Usage", RFC 6750, October 2012. 395 [RFC7009] Lodderstedt, T., Dronia, S., and M. Scurtescu, "OAuth 2.0 396 Token Revocation", RFC 7009, August 2013. 398 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 399 Interchange Format", RFC 7159, March 2014. 401 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 402 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 404 [W3C.REC-html5-20141028] 405 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 406 Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", 407 World Wide Web Consortium Recommendation REC- 408 html5-20141028, October 2014, 409 . 411 7.2. Informative References 413 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 414 (JWT)", draft-ietf-oauth-json-web-token (work in 415 progress), July 2014. 417 [TLS.BCP] Sheffer, Y., Holz, R., and P. Saint-Andre, 418 "Recommendations for Secure Use of TLS and DTLS", November 419 2014. 421 Appendix A. Document History 423 [[ To be removed by the RFC Editor. ]] 425 - 03 427 o Updated HTML and HTTP references. 429 o Call for registration of parameters in the JWT registry. 431 - 02 433 o Removed SAML pointer. 435 o Clarified what an "active" token could be. 437 o Explicitly declare introspection request as x-www-form-urlencoded 438 format. 440 o Added extended example. 442 o Made protected resource authentication a MUST. 444 - 01 446 o Fixed casing and consistent term usage. 448 o Incorporated working group comments. 450 o Clarified that authorization servers need to be able to understand 451 the token if they're to introspect it. 453 o Various editorial cleanups. 455 - 00 457 o Created initial IETF drafted based on draft-richer-oauth- 458 introspection-06 with no normative changes. 460 Appendix B. Non-normative Examples 462 In this non-normative example, a protected resource receives a 463 request from a client carrying an OAuth 2.0 bearer token as defined 464 in OAuth 2.0 Bearer Token Usage [RFC6750]. In order to know how and 465 whether to serve the request given this token, the protected resource 466 then makes the following request to the introspection endpoint of the 467 authorization server. The protected resource authenticates with its 468 own credentials, here re-using the format of client identifier and 469 client secret conveyed as HTTP Basic authentication as per OAuth 2.0 470 [RFC6749] Section 2.3.1. 472 Following is a non-normative example request: 474 POST /introspect HTTP/1.1 475 Host: authserver.example.com 476 Content-type: application/x-www-form-urlencoded 477 Accept: application/json 478 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 480 token=X3241Affw.4233-99JXJ 482 In this non-normative example, the protected resource also sends a 483 resource identifier and token type hint to the authorization server 484 to aid the authorization server's response: 486 Following is a non-normative example request (with line wraps for 487 display purposes only): 489 POST /introspect HTTP/1.1 490 Host: authserver.example.com 491 Content-type: application/x-www-form-urlencoded 492 Accept: application/json 493 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 495 token=X3241Affw.4233-99JXJ 496 &resource_id=rsid-2348e.2381k3 497 &token_type_hint=access_token 499 The authorization server validates the protected resource's 500 credentials and looks up the information in the token. If the token 501 is currently active and the authenticated protected resource is 502 authorized to know information about this token, the authorization 503 server returns the following JSON document. 505 Following is a non-normative example active token response (with line 506 wraps for display purposes only): 508 HTTP/1.1 200 OK 509 Content-Type: application/json 511 { 512 "active": true, 513 "client_id":"s6BhdRkqt3", 514 "scope": "read write dolphin", 515 "sub": "2309fj32kl", 516 "user_id": "jdoe", 517 "aud": "https://example.org/protected-resource/*", 518 "iss": "https://authserver.example.com/" 519 } 520 If the token presented is not currently active for any reason (for 521 instance, it has been revoked by the resource owner, it has expired, 522 or the protected resource is not allowed to ask about this particular 523 token) but the authorization presented during the request is 524 otherwise valid, the authorization server returns the following JSON 525 document. 527 Following is a non-normative example response to an inactive or 528 invalid token (with line wraps for display purposes only): 530 HTTP/1.1 200 OK 531 Content-Type: application/json 533 { 534 "active": false 535 } 537 Appendix C. Use with Proof of Posession Tokens 539 With bearer tokens such as those defined by OAuth 2.0 Bearer Token 540 Usage [RFC6750], the protected resource will have in its possession 541 the entire secret portion of the token for submission to the 542 introspection service. However, for proof-of-possession style 543 tokens, the protected resource will have only a token identifier used 544 during the request, along with the cryptographic signature on the 545 request. The protected resource would be able to submit the token 546 identifier to the authorization server's token endpoint in order to 547 obtain the necessary key information needed to validate the signature 548 on the request. The details of this usage are outside the scope of 549 this specification and should be defined in an extension to this 550 specification. 552 Author's Address 554 Justin Richer (editor) 555 The MITRE Corporation 557 Email: jricher@mitre.org