idnits 2.17.1 draft-ietf-oauth-introspection-01.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 (November 30, 2014) is 3432 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 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** 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) 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 November 30, 2014 5 Expires: June 3, 2015 7 OAuth 2.0 Token Introspection 8 draft-ietf-oauth-introspection-01 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 3, 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 2. Introspection Endpoint . . . . . . . . . . . . . . . . . . . 3 61 2.1. Introspection Request . . . . . . . . . . . . . . . . . . 3 62 2.2. Introspection Response . . . . . . . . . . . . . . . . . 4 63 2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 5 64 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 65 4. Security Considerations . . . . . . . . . . . . . . . . . . . 5 66 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 7 67 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 68 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 69 7.1. Normative References . . . . . . . . . . . . . . . . . . 7 70 7.2. Informative References . . . . . . . . . . . . . . . . . 8 71 Appendix A. Document History . . . . . . . . . . . . . . . . . . 8 72 Appendix B. Non-normative Example . . . . . . . . . . . . . . . 8 73 Appendix C. Use with Proof of Posession Tokens . . . . . . . . . 10 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 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 SAML [[ Editor's Note: 91 Which SAML document should we reference here? ]] and proprietary 92 inter-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 2. Introspection Endpoint 114 The introspection endpoint is an OAuth 2.0 endpoint that takes a 115 parameter representing an OAuth 2.0 token and returns a JSON 116 [RFC7159] document representing the meta information surrounding the 117 token. 119 The introspection endpoint MUST be protected by TLS of at least 120 version 1.2 RFC 5246 [RFC5246] and MAY support additional transport- 121 layer mechanisms meeting its security requirements. When using TLS, 122 the client or protected resource MUST perform a TLS/SSL server 123 certificate check, per RFC 6125 [RFC6125]. Implementation security 124 considerations can be found in Recommendations for Secure Use of TLS 125 and DTLS [TLS.BCP]. 127 2.1. Introspection Request 129 The protected resource calls the introspection endpoint using an HTTP 130 POST [RFC2616] request (or optionally an HTTP GET request). The 131 protected resource sends a parameter representing the token along 132 with optional parameters representing additional context that is 133 known by the protected resource to aid the authorization server in 134 its response. 136 token REQUIRED. The string value of the token. For access tokens, 137 this is the "access_token" value returned from the token endpoint 138 defined in OAuth 2.0 [RFC6749] section 5.1. For refresh tokens, 139 this is the "refresh_token" value returned from the token endpoint 140 as defined in OAuth 2.0 [RFC6749] section 5.1. Other token types 141 are outside the scope of this specification. 143 resource_id OPTIONAL. A service-specific string identifying the 144 resource that the token is being used for. This value allows the 145 protected resource to convey to the authorization server the 146 context in which the token is being used at the protected 147 resource, allowing the authorization server to tailor its response 148 accordingly if desired. 150 token_type_hint OPTIONAL. A hint about the type of the token 151 submitted for introspection. The protected resource re MAY pass 152 this parameter in order to help the authorization server to 153 optimize the token lookup. If the server is unable to locate the 154 token using the given hint, it MUST extend its search across all 155 of its supported token types. An authorization server MAY ignore 156 this parameter, particularly if it is able to detect the token 157 type automatically. Values for this field are defined in OAuth 158 Token Revocation [RFC7009]. 160 The endpoint MAY allow other parameters to provide further context to 161 the query. For instance, an authorization service may need to know 162 the IP address of the client accessing the protected resource in 163 order to determine the appropriateness of the token being presented. 165 To prevent unauthorized token scanning attacks, the endpoint SHOULD 166 also require some form of authorization to access this endpoint, such 167 as client authentication as described in OAuth 2.0 [RFC6749] or a 168 separate OAuth 2.0 access token such as the bearer token described in 169 OAuth 2.0 Bearer Token Usage [RFC6750]. The methods of managing and 170 validating these authentication credentials are out of scope of this 171 specification, though it is RECOMMENDED that these credentials be 172 distinct from those used at an authorization server's token endpoint. 174 2.2. Introspection Response 176 The server responds with a JSON object [RFC7159] in "application/ 177 json" format with the following top-level members. Specific 178 implementations MAY extend this structure with their own service- 179 specific pieces of information. 181 active REQUIRED. Boolean indicator of whether or not the presented 182 token is currently active. The authorization server determines 183 whether and when a given token is in an active state. 185 exp OPTIONAL. Integer timestamp, measured in the number of seconds 186 since January 1 1970 UTC, indicating when this token will expire. 188 iat OPTIONAL. Integer timestamp, measured in the number of seconds 189 since January 1 1970 UTC, indicating when this token was 190 originally issued. 192 scope OPTIONAL. A space-separated list of strings representing the 193 scopes associated with this token, in the format described in 194 section 3.3 of OAuth 2.0 [RFC6749]. 196 client_id OPTIONAL. Client identifier for the OAuth 2.0 client that 197 requested this token. 199 sub OPTIONAL. Machine-readable identifier of the resource owner who 200 authorized this token. 202 user_id OPTIONAL. Human-readable identifier for the user who 203 authorized this token. 205 aud OPTIONAL. Service-specific string identifier or list of string 206 identifiers representing the intended audience for this token. 208 iss OPTIONAL. String representing the issuer of this token. 210 token_type OPTIONAL. Type of the token as defined in section 5.1 of 211 OAuth 2.0 [RFC6749]. 213 The response MAY be cached by the protected resource, and the 214 authorization server SHOULD communicate appropriate cache controls 215 using applicable HTTP headers. 217 2.3. Error Response 219 If the protected resource uses OAuth 2.0 client credentials to 220 authenticate to the introspection endpoint and its credentials are 221 invalid, the authorization server responds with an HTTP 400 (Bad 222 Request) as described in section 5.2 of OAuth 2.0 [RFC6749]. 224 If the protected resource uses an OAuth 2.0 bearer token to authorize 225 its call to the introspection endpoint and the token used for 226 authorization does not contain sufficient privileges or is otherwise 227 invalid for this request, the authorization server responds with an 228 HTTP 400 code as described in section 3 of OAuth 2.0 Bearer Token 229 Usage [RFC6750]. 231 3. IANA Considerations 233 This document makes no request of IANA. 235 4. Security Considerations 237 If left unprotected and un-throttled, the introspection endpoint 238 could present a means for an attacker to poll a series of possible 239 token values, fishing for a valid token. The specifics of this 240 authentication credentials are out of scope of this specification, 241 but commonly these credentials could take the form of any valid 242 client authentication mechanism used with the token endpoint, an 243 OAuth 2.0 access token, or other HTTP authorization or authentication 244 mechanism. The authorization server SHOULD issue credentials to any 245 protected resources that need to access the introspection endpoint, 246 SHOULD require protected resources to be specifically authorized to 247 call the introspection endpoint, and SHOULD NOT allow a single piece 248 of software acting as both a client and a protected resource to re- 249 use the same credentials between the token endpoint and the 250 introspection endpoint. 252 Since the introspection endpoint takes in OAuth 2.0 tokens as 253 parameters, the server MUST support TLS 1.2 RFC 5246 [RFC5246] and 254 MAY support additional transport-layer mechanisms meeting its 255 security requirements. When using TLS, the client or protected 256 resource MUST perform a TLS/SSL server certificate check, per RFC 257 6125 [RFC6125]. Implementation security considerations can be found 258 in Recommendations for Secure Use of TLS and DTLS [TLS.BCP]. 260 In order to prevent the values of access tokens being from leaking 261 into server-side logs via query parameters, an authorization server 262 offering token introspection MAY disallow HTTP GET and instead 263 require an HTTP POST method only to the introspection endpoint. 265 An authorization server offering token introspection MUST be able to 266 understand the token values being presented to it during this call. 267 The exact means by which this happens is an implementation detail and 268 outside the scope of this specification. For unstructured tokens, 269 this could take the form of a simple server-side database query 270 against a data store containing the context information for the 271 token. For structured tokens, this could take the form of the server 272 parsing the token, validating its signature or other protection 273 mechanisms, and returning the information contained in the token back 274 to the protected resource (allowing the protected resource to be 275 unaware of the token's contents, much like the client). 277 Note that for a token carrying encrypted information that is needed 278 during the introspection process, the authorization server MUST be 279 able to decrypt and validate the token in order to access this 280 information. In cases where the authorization server stores no 281 information about the token and has no means of accessing information 282 about the token, it can not likely offer an introspection service. 284 5. Privacy Considerations 286 The introspection response may contain privacy-sensitive information 287 such as user identifiers for resource owners. When this is the case, 288 measures MUST be taken to prevent disclosure of this information to 289 unintended parties. One way to limit disclosure is to require 290 authorization to call the introspection endpoint and to limit calls 291 to only registered and trusted protected resource servers. Another 292 method is to transmit user identifiers as opaque service-specific 293 strings, potentially returning different identifiers to each 294 protected resource. Omitting privacy-sensitive information from an 295 introspection response is the simplest way of minimizing privacy 296 issues. 298 6. Acknowledgements 300 Thanks to the OAuth Working Group and the UMA Working Group for 301 feedback. 303 7. References 305 7.1. Normative References 307 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 308 Requirement Levels", BCP 14, RFC 2119, March 1997. 310 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 311 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 312 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 314 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 315 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 317 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 318 Verification of Domain-Based Application Service Identity 319 within Internet Public Key Infrastructure Using X.509 320 (PKIX) Certificates in the Context of Transport Layer 321 Security (TLS)", RFC 6125, March 2011. 323 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 324 6749, October 2012. 326 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 327 Framework: Bearer Token Usage", RFC 6750, October 2012. 329 [RFC7009] Lodderstedt, T., Dronia, S., and M. Scurtescu, "OAuth 2.0 330 Token Revocation", RFC 7009, August 2013. 332 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 333 Interchange Format", RFC 7159, March 2014. 335 7.2. Informative References 337 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 338 (JWT)", draft-ietf-oauth-json-web-token (work in 339 progress), July 2014. 341 [TLS.BCP] Sheffer, Y., Holz, R., and P. Saint-Andre, 342 "Recommendations for Secure Use of TLS and DTLS", November 343 2014. 345 Appendix A. Document History 347 [[ To be removed by the RFC Editor. ]] 349 - 01 351 o Fixed casing and consistent term usage. 353 o Incorporated working group comments. 355 o Clarified that authorization servers need to be able to understand 356 the token if they're to introspect it. 358 o Various editorial cleanups. 360 - 00 362 o Created initial IETF drafted based on draft-richer-oauth- 363 introspection-06 with no normative changes. 365 Appendix B. Non-normative Example 367 In this non-normative example, a protected resource receives a 368 request from a client carrying an OAuth 2.0 bearer token as defined 369 in OAuth 2.0 Bearer Token Usage [RFC6750]. In order to know how and 370 whether to serve the request given this token, the protected resource 371 then makes the following request to the introspection endpoint of the 372 authorization server. The protected resource authenticates with its 373 own credentials, here re-using the format of client identifier and 374 client secret conveyed as HTTP Basic authentication as per OAuth 2.0 375 [RFC6749] Section 2.3.1. 377 Following is a non-normative example request: 379 POST /introspect HTTP/1.1 380 Host: authserver.example.com 381 Content-type: application/x-www-form-urlencoded 382 Accept: application/json 383 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 385 token=X3241Affw.4233-99JXJ 387 The authorization server validates the protected resource's 388 credentials and looks up the information in the token. If the token 389 is currently active and the authenticated protected resource is 390 authorized to know information about this token, the authorization 391 server returns the following JSON document. 393 Following is a non-normative example active token response (with line 394 wraps for display purposes only): 396 HTTP/1.1 200 OK 397 Content-Type: application/json 398 Cache-Control: no-store 400 { 401 "active": true, 402 "client_id":"s6BhdRkqt3", 403 "scope": "read write dolphin", 404 "sub": "2309fj32kl", 405 "user_id": "jdoe", 406 "aud": "https://example.org/protected-resource/*", 407 "iss": "https://authserver.example.com/" 408 } 410 If the token presented is not currently active for any reason (for 411 instance, it has been revoked by the resource owner) but the 412 authorization presented during the request is otherwise valid, the 413 authorization server returns the following JSON document. 415 Following is a non-normative example response to an inactive or 416 invalid token (with line wraps for display purposes only): 418 HTTP/1.1 200 OK 419 Content-Type: application/json 420 Cache-Control: no-store 422 { 423 "active": false 424 } 425 Note that in order to avoid disclosing too much of the authorization 426 server's state to a third party, the authorization server SHOULD NOT 427 include any additional information about an inactive token. 429 Appendix C. Use with Proof of Posession Tokens 431 With bearer tokens such as those defined by OAuth 2.0 Bearer Token 432 Usage [RFC6750], the protected resource will have in its posession 433 the entire secret portion of the token for submission to the 434 introspection service. However, for proof-of-posession style tokens, 435 the protected resource will have only a token identifier used during 436 the request, along with the cryptographic signature on the request. 437 The protected resource would be able to submit the token identifier 438 to the authoriation server's token endpoint in order to obtain the 439 necessary key information needed to validate the signature on the 440 request. The details of this usage are outside the scope of this 441 specification and should be defined in an extension to this 442 specification. 444 Author's Address 446 Justin Richer (editor) 447 The MITRE Corporation 449 Email: jricher@mitre.org