idnits 2.17.1 draft-richer-oauth-introspection-02.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 6, 2013) is 4069 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) == Unused Reference: 'RFC6750' is defined on line 231, but no explicit reference was found in the text ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Richer, Ed. 3 Internet-Draft The MITRE Corporation 4 Intended status: Standards Track February 6, 2013 5 Expires: August 10, 2013 7 OAuth Token Introspection 8 draft-richer-oauth-introspection-02 10 Abstract 12 This specification defines a method for a client or protected 13 resource to query an OAuth authorization server to determine meta- 14 information about an OAuth token. 16 Requirements Language 18 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 19 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 20 document are to be interpreted as described in RFC 2119 [RFC2119]. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on August 10, 2013. 39 Copyright Notice 41 Copyright (c) 2013 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Introspection Endpoint . . . . . . . . . . . . . . . . . . . . 3 58 2.1. Introspection Request . . . . . . . . . . . . . . . . . . . 3 59 2.2. Introspection Response . . . . . . . . . . . . . . . . . . 4 60 2.3. Non-normative Example . . . . . . . . . . . . . . . . . . . 4 61 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5 62 4. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 63 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 6 64 6. Normative References . . . . . . . . . . . . . . . . . . . . . 6 65 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 6 67 1. Introduction 69 In OAuth, the contents of tokens are opaque to clients. This means 70 that the client does not need to know anything about the content or 71 structure of the token itself, if there is any. However, there is 72 still a large amount of metadata that may be attached to a token, 73 such as its current validity, approved scopes, and extra information 74 about the authentication context in which the token was issued. 75 These pieces of information are often vital to Protected Resources 76 making authorization decisions based on the tokens being presented. 77 Since OAuth2 defines no direct relationship between the Authorization 78 Server and the Protected Resource, only that they must have an 79 agreement on the tokens themselves, there have been many different 80 approaches to bridging this gap. 82 This specification defines an Introspection Endpoint that allows the 83 holder of a token to query the Authorization Server to discover the 84 set of metadata for a token. A Protected Resource may use the 85 mechanism described in this draft to query the Introspection Endpoint 86 in a particular authorization decision context and ascertain the 87 relevant metadata about the token in order to make this authorization 88 decision appropriately. 90 2. Introspection Endpoint 92 The Introspection Endpoint is an OAuth 2 Endpoint that responds to 93 HTTP GET and HTTP POST requests from token holders. The endpoint 94 takes a single parameter representing the token (and optionally 95 further authentication) and returns a JSON document representing the 96 meta information surrounding the token. 98 2.1. Introspection Request 100 token REQUIRED. The string value of the token. 102 resource_id OPTIONAL. A service-specific string identifying the 103 resource that the client doing the introspection is asking about. 105 The endpoint MAY allow other parameters to provide context to the 106 query. For instance, an authorization service may need to know the 107 IP address of the Client in order to determine the appropriateness of 108 the token being presented. 110 The endpoint SHOULD also require some form of authentication to 111 access this endpoint, such as the Client Authentication as described 112 in OAuth 2 Core Specification [RFC6749] or a separate OAuth2 Access 113 Token. The methods of managing and validating these authentication 114 credentials are out of scope of this specification. 116 2.2. Introspection Response 118 The server responds with a JSON object [RFC4627] in 119 "application/json" format with the following top-level members. 120 Specific implementations MAY extend this structure with their own 121 service-specific pieces of information. 123 valid REQUIRED. Boolean indicator of whether or not the presented 124 token is valid. 126 expires_at OPTIONAL. Integer timestamp, measured in the number of 127 seconds since January 1 1970 UTC, indicating when this token will 128 expire. 130 issued_at OPTIONAL. Integer timestamp, measured in the number of 131 seconds since January 1 1970 UTC, indicating when this token was 132 originally issued. 134 scope OPTIONAL. A space-separated list of strings representing the 135 scopes associated with this token, in the format described in 136 Section 3.3 of OAuth 2.0 [RFC6749]. 138 client_id OPTIONAL. Client Identifier for the OAuth Client that 139 requested this token. 141 sub OPTIONAL. Local identifier of the Resource Owner who authorized 142 this token. 144 aud OPTIONAL. Service-specific string identifier or list of string 145 identifiers representing the intended audience for this token. 147 2.3. Non-normative Example 149 For example, a Protected Resource accepts a request from a Client 150 carrying an OAuth2 Bearer Token. In order to know how and whether to 151 serve the request, the Protected Resource then makes the following 152 request to the Introspection Endpoint of the Authorization Server. 153 The Protected Resource is here authenticating with its own Client ID 154 and Client Secret as per OAuth2 [RFC6749] Section 2.3.1. 156 Following is a non-normative example request (with line wraps for 157 display purposes only): 158 POST /register HTTP/1.1 159 Accept: application/x-www-form-urlencoded 160 Host: server.example.com 161 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 163 token=X3241Affw.4233-99JXJ 165 The Authorization Server validates the client credentials and looks 166 up the information in the token. If the token is valid, it returns 167 the following JSON document. 169 Following is a non-normative example valid token response (with line 170 wraps for display purposes only): 171 HTTP/1.1 200 OK 172 Content-Type: application/json 173 Cache-Control: no-store 175 { 176 "valid": true, 177 "client_id":"s6BhdRkqt3", 178 "scope": "read write dolphin", 179 "sub": "2309fj32kl", 180 "aud": "http://example.org/protected-resource/*" 181 } 183 If the token presented is not valid (but the authentication presented 184 is valid), it returns the following JSON document. 186 Following is a non-normative example response to an invalid token 187 (with line wraps for display purposes only): 188 HTTP/1.1 200 OK 189 Content-Type: application/json 190 Cache-Control: no-store 192 { 193 "valid": false 194 } 196 If the client credentials are invalid or there is another error, the 197 Authorization Server responds with an HTTP 400 (Bad Request) as 198 described in OAuth 2.0 section 5.2 [RFC6749]. 200 3. IANA Considerations 202 This document makes no request of IANA. 204 4. Security Considerations 206 If left unprotected and un-throttled, the Introspection Endpoint 207 could present a means for an attacker to poll a series of possible 208 token values, fishing for a valid token. Therefore, the 209 Authorization Server SHOULD issue special client credentials to any 210 protected resources or clients that need to access the introspection 211 endpoint. These credentials may be used directly at the endpoint, or 212 they may be exchanged for an OAuth2 Access token scoped specifically 213 for the Introspection Endpoint. 215 5. Acknowledgements 217 Thanks to the OAuth Working Group and the UMA Working Group for 218 feedback. 220 6. Normative References 222 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 223 Requirement Levels", BCP 14, RFC 2119, March 1997. 225 [RFC4627] Crockford, D., "The application/json Media Type for 226 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 228 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 229 RFC 6749, October 2012. 231 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 232 Framework: Bearer Token Usage", RFC 6750, October 2012. 234 Author's Address 236 Justin Richer (editor) 237 The MITRE Corporation 239 Email: jricher@mitre.org