idnits 2.17.1 draft-lodderstedt-oauth-revocation-04.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (March 31, 2012) is 4380 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) == Unused Reference: 'RFC2119' is defined on line 212, but no explicit reference was found in the text == Outdated reference: A later version (-31) exists of draft-ietf-oauth-v2-25 ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Open Authentication Protocol T. Lodderstedt, Ed. 3 Internet-Draft Deutsche Telekom AG 4 Intended status: Standards Track S. Dronia 5 Expires: October 2, 2012 SYRACOM Consulting AG 6 M. Scurtescu 7 Google 8 March 31, 2012 10 Token Revocation 11 draft-lodderstedt-oauth-revocation-04 13 Abstract 15 This draft proposes an additional endpoint for OAuth authorization 16 servers for revoking tokens. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on October 2, 2012. 35 Copyright Notice 37 Copyright (c) 2012 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Token Revocation . . . . . . . . . . . . . . . . . . . . . . . 3 54 2.1. JSONP Support . . . . . . . . . . . . . . . . . . . . . . . 5 55 3. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 5 56 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5 57 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 5 58 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6 59 6.1. Normative References . . . . . . . . . . . . . . . . . . . 6 60 6.2. Informative References . . . . . . . . . . . . . . . . . . 6 61 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 6 63 1. Introduction 65 The OAuth 2.0 core specification [I-D.ietf-oauth-v2] defines several 66 ways for a client to obtain refresh and access tokens. This 67 specification supplements the core specification with a mechanism to 68 revoke both types of tokens and facilitates the following use cases: 70 o The end-user triggers revocation from within the client that sends 71 the appropriate revocation request to the autorization server. 72 From the end-user's perspective, this looks like a "logout" or 73 "reset" function. The request causes the removal of the client 74 permissions associated with the particular token to access the 75 end-user's protected resources. This use case makes it even more 76 comfortable to the end-user to revoke his access grant immediately 77 via the client. 79 o In contrast to revocation by a client, the authorization server 80 (or a related entity) may offer its end-users a self-care portal 81 to delete access grants given to clients independent of any token 82 storing devices. Such a portal offers the possibility to an end- 83 user to look at and revoke all access grants he once authorized. 84 In cases the token storing device is not available, e.g. it is 85 lost or stolen, revocation by a self-care portal is the only 86 possibility to limit or avoid abuse. 88 In the end, security, usability, and ease of use are increased by 89 token revocation. 91 By using an additional endpoint, the token revocation endpoint, 92 clients can request the revocation of a particular token. Compliant 93 implementation MUST support the revocation of refresh tokens, access 94 token revocation MAY be supported. 96 2. Token Revocation 98 The client requests the revocation of a particular token by making an 99 HTTP POST request to the token revocation endpoint. The location of 100 the token revocation endpoint can be found in the authorization 101 servers documentation. The token endpoint URI MAY include a query 102 component. 104 Since requests to the token revocation endpoint result in the 105 transmission of plain text credentials in the HTTP request, the 106 authorization server MUST require the use of a transport-layer 107 security mechanism when sending requests to the token revocation 108 endpoints. The authorization server MUST support TLS 1.0 109 ([RFC2246]), SHOULD support TLS 1.2 ([RFC5246]) and its future 110 replacements, and MAY support additional transport-layer mechanisms 111 meeting its security requirements. 113 The client constructs the request by including the following 114 parameters using the "application/x-www-form-urlencoded" format in 115 the HTTP request entity-body: 117 token REQUIRED. The token that the client wants to get revoked. 118 Note: the authorization server is supposed to detect the 119 token type automatically. 121 The client also includes its authentication credentials as described 122 in Section 2.3. of [I-D.ietf-oauth-v2]. 124 For example, a client may request the revocation of a refresh token 125 with the following request (line breaks are for display purposes 126 only): 128 POST /revoke HTTP/1.1 129 Host: server.example.com 130 Content-Type: application/x-www-form-urlencoded 131 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 133 token=45ghiukldjahdnhzdauz& 135 The authorization server first validates the client credentials (if 136 present) and verifies whether the client is authorized to revoke the 137 particular token based on the client identity and its policy. For 138 example, only the client the token has been issued for might be 139 allowed to revoke it. It is also conceivable to allow a dedicated 140 user self-care portal to revoke all kinds of tokens. 142 In the next step, the authorization server invalidates the token. 143 Whether the revocation takes effect instantly or with some delay 144 depends on the architecture of the particular deployment. The client 145 MUST NOT make any assumptions about the timing and MUST NOT use the 146 token again. 148 If the processed token is a refresh token and the authorization 149 server supports the revocation of access tokens, then the 150 authorization server SHOULD also invalidate all access tokens issued 151 for that refresh token. 153 The authorization server indicates a successful processing of the 154 request by a HTTP status code 200. Status code 401 indicates a 155 failed client authentication, whereas a status code 403 is used if 156 the client is not authorized to revoke the particular token. For all 157 other error conditions, a status code 400 is used along with an error 158 response as defined in section 5.2. of [I-D.ietf-oauth-v2]. The 159 following error codes are defined for the token revocation endpoint: 161 unsupported_token_type The authorization server does not support the 162 revocation of the presented token type. I.e. the client 163 tried to revoke an access token on a server not supporting 164 this feature. 166 invalid_token The presented token is invalid. 168 2.1. JSONP Support 170 The revocation endpoint MAY support JSONP [jsonp] by allowing GET 171 requests with an additional parameter: 173 callback The qualified name of a JavaScript function. 175 Example request: 177 https://example.com/revoke?token=45ghiukldjahdnhzdauz& 178 callback=package.myCallback 180 Successful response: 182 package.myCallback(); 184 Error response: 186 package.myCallback({"error":"invalid_token"}); 188 3. Acknowledgements 190 We would like to thank Sebastian Ebling, Christian Stuebner, Brian 191 Campbell, Igor Faynberg, Lukas Rosenstock, and Justin P. Richer for 192 their valuable feedback. 194 4. IANA Considerations 196 This draft includes no request to IANA. 198 5. Security Considerations 200 All relevant security considerations have been given in the 201 functional specification. 203 6. References 205 6.1. Normative References 207 [I-D.ietf-oauth-v2] 208 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 209 2.0 Authorization Protocol", draft-ietf-oauth-v2-25 (work 210 in progress), March 2012. 212 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 213 Requirement Levels", BCP 14, RFC 2119, March 1997. 215 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 216 RFC 2246, January 1999. 218 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 219 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 221 6.2. Informative References 223 [jsonp] Ippolito, B., "Remote JSON - JSONP", December 2005. 225 Authors' Addresses 227 Torsten Lodderstedt (editor) 228 Deutsche Telekom AG 230 Email: torsten@lodderstedt.net 232 Stefanie Dronia 233 SYRACOM Consulting AG 235 Email: sdronia@gmx.de 237 Marius Scurtescu 238 Google 240 Email: mscurtescu@google.com