idnits 2.17.1 draft-richer-oauth-introspection-00.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 == Line 90 has weird spacing: '... token the s...' -- The document date (November 27, 2012) is 4166 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: 'RFC4627' is defined on line 202, but no explicit reference was found in the text == Unused Reference: 'RFC6750' is defined on line 208, 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 (~~), 4 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 November 27, 2012 5 Expires: May 31, 2013 7 OAuth Token Introspection 8 draft-richer-oauth-introspection-00 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 May 31, 2013. 39 Copyright Notice 41 Copyright (c) 2012 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 . . . . . . . . . . . . . . . . . . 3 60 2.3. Non-normative Example . . . . . . . . . . . . . . . . . . . 4 61 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5 62 4. Security Considerations . . . . . . . . . . . . . . . . . . . . 5 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. 76 This specification defines an Introspection Endpoint that allows the 77 holder of a token to query the Authorization Server to discover the 78 set of meta-information for a token. 80 2. Introspection Endpoint 82 The Introspection Endpoint is an OAuth 2 Endpoint that responds to 83 HTTP GET and HTTP POST requests from token holders. The endpoint 84 takes a single parameter representing the token (and optionally 85 further authentication) and returns a JSON document representing the 86 meta information surrounding the token. 88 2.1. Introspection Request 90 token the string value of the token. 92 The endpoint SHOULD also require some form of authentication to 93 access this endpoint, such as the Client Authentication as described 94 in OAuth 2 Core Specification [RFC6749] or a separate OAuth2 Access 95 Token. The methods of managing and validating these authentication 96 credentials are out of scope of this specification. 98 2.2. Introspection Response 100 The server responds with a JSON object in application/json format 101 with the following top-level members. Specific implementations MAY 102 extend this structure with their own service-specific pieces of 103 information. 105 valid REQUIRED. Boolean indicator of whether or not the presented 106 token is valid. 108 expires_at OPTIONAL. Integer timestamp, measured in the number of 109 seconds since January 1 1970 UTC, indicating when this token will 110 expire. 112 issued_at OPTIONAL. Integer timestamp, measured in the number of 113 seconds since January 1 1970 UTC, indicating when this token was 114 originally issued. 116 scope OPTIONAL. Array of strings representing the scopes associated 117 with this token. 119 user_id OPTIONAL. Local identifier of the Resource Owner who 120 authorized this token. 122 client_id OPTIONAL. Client Identifier for the Client that requested 123 this token. 125 audience OPTIONAL. Service-specific string identifier of the 126 intended audience for this token. 128 2.3. Non-normative Example 130 For example, a Protected Resource accepts a request from a Client 131 carrying an OAuth2 Bearer Token. In order to know how and whether to 132 serve the request, the Protected Resource then makes the following 133 request to the Introspection Endpoint of the Authorization Server. 135 Following is a non-normative example request (with line wraps for 136 display purposes only): 137 POST /register HTTP/1.1 138 Accept: application/x-www-form-urlencoded 139 Host: server.example.com 140 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 142 token=X3241Affw.4233-99JXJ 144 The Authorization Server validates the client credentials and looks 145 up the information in the token. If the token is valid, it returns 146 the following JSON document. 148 Following is a non-normative example request (with line wraps for 149 display purposes only): 150 HTTP/1.1 200 OK 151 Content-Type: application/json 152 Cache-Control: no-store 154 { 155 "valid": true, 156 "client_id":"s6BhdRkqt3", 157 "scope": ["read", "write", "dolphin"], 158 "user_id": "2309fj32kl", 159 "audience": "http://example.org/protected-resource/*" 160 } 162 If the token presented is not valid (but the authentication presented 163 is valid), it returns the following JSON document. 165 Following is a non-normative example request (with line wraps for 166 display purposes only): 167 HTTP/1.1 200 OK 168 Content-Type: application/json 169 Cache-Control: no-store 171 { 172 "valid": false 173 } 175 If the credentials are invalid, the Authorization Server responds 176 with the appropriate error response from the OAuth2 Core. 178 3. IANA Considerations 180 This document makes no request of IANA. 182 4. Security Considerations 184 If left unprotected and un-throttled, the Introspection Endpoint 185 could present a means for an attacker to poll a series of possible 186 token values, fishing for a valid token. Therefore, the 187 Authorization Server SHOULD issue special client credentials to any 188 protected resources or clients that need to access the introspection 189 endpoint. These credentials may be used directly at the endpoint, or 190 they may be exchanged for an OAuth2 Access token scoped specifically 191 for the Introspection Endpoint. 193 5. Acknowledgements 195 Thanks to the OAuth Working Group for feedback. 197 6. Normative References 199 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 200 Requirement Levels", BCP 14, RFC 2119, March 1997. 202 [RFC4627] Crockford, D., "The application/json Media Type for 203 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 205 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 206 RFC 6749, October 2012. 208 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 209 Framework: Bearer Token Usage", RFC 6750, October 2012. 211 Author's Address 213 Justin Richer (editor) 214 The MITRE Corporation 216 Email: jricher@mitre.org