idnits 2.17.1 draft-gpujol-oauth-atrl-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 106 has weird spacing: '... server this ...' == Line 112 has weird spacing: '... server this ...' -- The document date (July 14, 2018) is 2112 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) == Missing Reference: 'UMA' is mentioned on line 118, but not defined ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group G. Pujol 3 Internet-Draft DS 4 Intended status: Standards Track July 14, 2018 5 Expires: January 15, 2019 7 OAuth 2.0 Token Revocation List 8 draft-gpujol-oauth-atrl-00 10 Abstract 12 This document defines a format and a standardised uri for a Token 13 Revocation List. An OAuth 2.0 authorization server can use those to 14 expose a current list of revoked access tokens identifiers that it 15 previously issued, intended for use by OAuth 2.0 resource servers. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on January 15, 2019. 34 Copyright Notice 36 Copyright (c) 2018 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 53 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2.1. Token Revocation List . . . . . . . . . . . . . . . . . . 4 55 2.2. Symbols and abbreviated terms . . . . . . . . . . . . . . 4 56 3. Authorization server metadata . . . . . . . . . . . . . . . . 4 57 4. Token Revocation List Format . . . . . . . . . . . . . . . . 4 58 5. Token Revocation List Request . . . . . . . . . . . . . . . . 6 59 6. Token Revocation List Response . . . . . . . . . . . . . . . 6 60 7. Security Considerations . . . . . . . . . . . . . . . . . . . 7 61 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 62 8.1. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 8 63 8.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 8 64 9. Normative References . . . . . . . . . . . . . . . . . . . . 8 65 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 67 1. Introduction 69 OAuth 2.0 Token Revocation [RFC7009] defines a way for OAuth 2.0 70 clients to revoke access tokens and refresh tokens issued by an OAuth 71 2.0 authorization server. While refresh token are typically only 72 used by the authorization server itself, access tokens on the other 73 hand are consumed by OAuth 2.0 resource servers; those are logically 74 separated from the authorization server, and must learn about the 75 revocation status of the access tokens they receive, if the local 76 security requirements mandates it. 78 Some deployments of OAuth 2.0 (or derived protocols) use signed JWT 79 as access tokens. Those access tokens are self-sufficient for 80 resource server to validate that the access token is currently not 81 expired, but provide no means for the resource server to obtain the 82 revocation status of the token. 84 OAuth 2.0 Token Introspection [RFC7662] defines a way for resource 85 servers to obtain the metadata attached to a given access token. For 86 performance reasons, this metadata may be put in cache by the 87 resource server, instead of calling the introspection endpoint 88 synchronously every time the same access token is received. This 89 voids the possibility for the resource server to be informed about a 90 revocation of an access token that occurs after the first call to the 91 introspection endpoint. 93 This specification defines a Token Revocation List (TRL), a document 94 exposed by the OAuth 2.0 authorization server, containing a list of 95 revoked access tokens identifiers. Resource servers can periodically 96 retrieve that list to obtain the revocation status of access tokens. 98 By doing so, they can either flag currently cached introspected token 99 metadata as revoked, or avoid unnecessary calls to the introspection 100 endpoint for unknown tokens that are already expired when they are 101 received by the resource server. 103 This allows better performance for the authorization server and lower 104 response times for resource requests [RFC6750], since: 106 for resource server this allow caching the token introspection 107 response until the expiration date of the access token. The TRL 108 can be retrieved asynchronously to actual resource requests, so 109 the round trip to the authorization server does not add up to the 110 resource server response time. 112 for the authorization server this avoids unnecessary calls to the 113 introspection endpoint 115 This is especially important in scenarios where the authorization 116 server issues relatively long lived access tokens, and the 117 authorization server and resource servers are loosely coupled (e.g. 118 User Managed Access [UMA]), and the introspection endpoint is heavily 119 used. 121 Note that using short-lived access tokens should be the preferred way 122 to protect sensitive resources, rather than relying on the Token 123 Revocation List. Issuing a TRL does not provide any assurance that 124 resource servers will use it, nor does provide real time access token 125 revocation; depending on their configuration, resource servers might 126 take a few seconds or minutes to obtain a fresh TRL after any given 127 token is expired. During that time, access tokens may still be 128 considered as active by resource servers. This hardly avoidable 129 delay may however be better than not checking the revocation status 130 at all. 132 1.1. Notational Conventions 134 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 135 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 136 document are to be interpreted as described in RFC 2119 [RFC2119]. 138 2. Terminology 140 For the purposes of this specification, the following terms and 141 definitions in addition to what is defined in OAuth 2.0 Framework 142 [RFC6749], Authorization server [RFC6749], Resource Server [RFC6749], 143 Access Token [RFC6749], and JSON Web Encryption [RFC7519] apply. 145 2.1. Token Revocation List 147 JWT [RFC7519] that holds a list of access tokens identifiers issued 148 by a given authorization server, that are revoked but not expired at 149 the time it is issued. 151 2.2. Symbols and abbreviated terms 153 The following abbreviations are common to this specification. 155 JWT JSON Web Token 157 URI Uniform Resource Identifier 159 URL Uniform Resource Locator 161 TRL Token Revocation List 163 3. Authorization server metadata 165 Authorization servers can have metadata describing their 166 configuration. The following authorization server metadata value is 167 used by this specification and are registered in the IANA "OAuth 168 Authorization Server Metadata" registry established in Section 7.1 of 169 OAuth 2.0 Authorization Server Metadata [RFC8414]: 171 token_revocation_list_uri OPTIONAL. URL [RFC3986] of an 172 authorization server, where resource servers can retrieve the 173 Token Revocation List. This url MUST use the https scheme. The 174 referenced document contains a JWT whose payload contains the list 175 of currently revoked access tokens. The exact contents of this 176 JWT is defined in the present specification. 178 If an authorization server advertises the presence of its token 179 revocation list, resource servers SHOULD use it as their prefered way 180 to obtain the revocation status of access tokens, rather that using 181 the token introspection endpoint. 183 4. Token Revocation List Format 185 A Token Revocation List (TRL) is a JWT. The JWT payload MUST contain 186 the following claims: 188 iss REQUIRED. MUST be the authorization server issuer 190 iat REQUIRED. time at which the TRL was generated, as defined in the 191 exp REQUIRED. as defined in [RFC7519], time at which the TRL SHOULD 192 be considered as expired by resource servers. 194 rev_jtis REQUIRED. [CLAIM NAME TO BE REVISED] a JSON list whose 195 items are the JWT Identifiers (jti) of the revoked, non-expired 196 access tokens at the time the TRL was generated. If no tokens are 197 revoked at that time, this MUST be an empty list. 199 rev_ctis OPTIONAL. [NOT SURE IF ACTUALLY USEFUL IN THIS 200 SPECIFICATION] OPTIONAL: if the authorization server issues access 201 tokens that are in CWT format [RFC8392], a JSON list of all 202 revoked, non-expired access tokens in CWT format at the time the 203 TRL was generated. 205 The JWT payload MAY contain other claims. Claims not known or not 206 understood by resource servers MUST be ignored. 208 Note that despite the name, a "jti" is not always bound to an access 209 token in JWT format. The introspection endpoint [RFC7662] returns a 210 jti value for tokens that are in an opaque format. This jti is then 211 an unique identifier for a token, no matter if that token is in JWT 212 (or similar structured, self-carrying formats) or in an opaque 213 format. 215 To allow resource server to learn about the revocation status of a 216 token, the resource server must be able to obtain this token unique 217 identifier. This can be done either by reading the jti claims from 218 access tokens that are in JWT format, or by reading the jti attribute 219 as returned by the authorization server introspection endpoint. 221 The TRL exposed by an OAuth authorization server at any given time 222 MUST have an expiration date (exp) in the future and SHOULD have an 223 expiration date reasonably far away in the future. The exact 224 frequency for an authorization server to generate a new TRL and the 225 lifetime of generated TRLs is deployment specific and is out of scope 226 of this specification. Some authorization servers MAY choose to 227 generate a new TRL every time an access token is revoked, while 228 others MAY generate a new TRL periodically at a fixed time period. 229 Some MAY also choose to generate a new TRL only when an access token 230 considered as security sensitive is revoked (e.g. bound to a scope 231 that is internally flagged as sensitive). 233 A TRL SHOULD contain only a list of jtis that are revoked and not 234 expired at the time the TRL is generated. A TRL MUST NOT contain a 235 jti of a token that has not been revoked before the TRL is generated. 236 A TRL MAY contain some jtis that have been revoked but are already 237 expired at the time the TRL is generated. 239 A TRL JWT SHOULD be signed. If signature is used, that signature 240 MUST use an asymmetric algorithm, and the JWT header MUST contain 241 both the "alg" and the "kid" claims; the JWK referenced by this kid 242 MUST be part of the JWKS [RFC7517] exposed by the authorization 243 server on its jwks_uri. If the JWT is not signed, it must be 244 represented as an Unsecured JWT [RFC7519]. 246 A TRL JWT MUST NOT be encrypted. 248 5. Token Revocation List Request 250 An authorization server Token Revocation List MUST be queryied using 251 an HTTP "GET" request [RFC7230] at the URL defined in the 252 authorization server metadata. 254 The following is a non-normative example TRL request (with line 255 breaks for display purposes only): 257 GET /token_revocation_list HTTP/1.1 258 Host: server.example.com 260 Once a resource server obtains a TRL and that TRL reaches its 261 expiration date, a resource server SHOULD obtain a new TRL from the 262 authorization server. A resource server MAY obtain a new TRL before 263 the last TRL in its possession is expired. The frequency at which 264 the resource server obtains updated TRLs is out of the scope of this 265 specification, and depends on the resource server security 266 requirements. 268 6. Token Revocation List Response 270 An authorization server responds to a Token Revocation List request 271 with the most recently available TRL and the Content-Type 272 "application/jwt". 274 The following is a non-normative example TRL response (with line 275 breaks for display purposes only): 277 200 OK 278 Content-Type: application/jwt 279 Content-Length: 542 281 eyJhbGciOiJSUzI1NiIsImtpZCI6IlRSTF8yMDE4MDcxMCJ9.eyJleHAiOjE1MzE 282 zMjMwNjguMjc3MzYsImlhdCI6MTUzMTMyMzAwOC4yNzczNiwiaXNzIjoic2VydmV 283 yLmV4YW1wbGUuY29tIiwicmV2X2p0aXMiOlsiMTIzNDU2NzkwIiwiMjM0NTY3ODk 284 wMSJdfQ.LdMV-QMRsXwHxI4ZfQvQEv5_wNe22VHBa5x6CIbG-3H-0R2nMnB_tNeA 285 8nngNNo_vdDRj6Z25Bu6wlTQOM8VufPbUGyAM1Q3LLjPU8pcEnM79Z8LW305M09I 286 Laumgg94HrFSTPyEnlIGkVFF_x2vYTf-FbYEFlz2he3WDatoPXXXh9gVlfTeinPw 287 VtEZv-k740nUHVJjoSLSS7f_ZVmRnT_wUF_Wisx5YRtrkcu8bXJqEykswgYmrzxe 288 wCHsc03qEV3HwQPc15_MJBF8tQT9vLTwnYSdMXJh9J5uREzIEFqBQpQyIAtbqVT7 289 eD9OMQOttWfB5LVtlnAVHRRdFVkuWA 291 7. Security Considerations 293 The TRL is publicly exposed to anyone, not just authorized resource 294 servers. However the TRL does not contain anything security 295 sensitive, just identifiers of tokens that are not sufficient to gain 296 any access anywhere. An alternative would be to require some form of 297 authentication of TRL clients (which would be resource servers). 298 However, the added complexity, and (however small) performance impact 299 of managing that authentication would curb usage of the TRL. 301 The TRL SHOULD be signed by its issuer (the authorization server). 302 Since the TRL MUST be retrieved over an https channel, the signature 303 validation may be considered optional when the TRL is directly used 304 by the client initiating the TLS connection. However, in real life, 305 the https security and the TRL SHOULD be signed to allow end-to-end 306 security and temporary inalterable storage on resource servers. The 307 cost of a TRL signature being equivalent to signing a JWT token (e.g. 308 an ID Token), the TRL SHOULD be signed. If the TRL is signed, the 309 resource servers MUST validate the signature before trusting the TRL. 310 This avoids misuse or denial of service when the party controlling 311 the https (server-side) connection (which, in complex environments, 312 may be different than the entity controlling the authorization 313 servers) remove revoked tokens from the TRL, and/or issues a TRL 314 containing non-revoked tokens. 316 8. IANA Considerations 317 8.1. OAuth 2.0 Authorization Server Metadata 319 This specification registers the following values in the IANA "OAuth 320 2.0 Authorization Server Metadata" registry [IANA.OAuth.Parameters] 321 established by [RFC8414]. 323 8.1.1. Registry Contents 325 o Metadata name: token_revocation_list_uri 326 o Metadata Description: The Token Revocation List Uri. 327 o Change controller: IESG 328 o Specification Document: Section 3 of [[ this specification ]] 330 9. Normative References 332 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 333 Requirement Levels", BCP 14, RFC 2119, 334 DOI 10.17487/RFC2119, March 1997, 335 . 337 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 338 Resource Identifier (URI): Generic Syntax", STD 66, 339 RFC 3986, DOI 10.17487/RFC3986, January 2005, 340 . 342 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 343 RFC 6749, DOI 10.17487/RFC6749, October 2012, 344 . 346 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 347 Framework: Bearer Token Usage", RFC 6750, 348 DOI 10.17487/RFC6750, October 2012, 349 . 351 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 352 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 353 August 2013, . 355 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 356 Protocol (HTTP/1.1): Message Syntax and Routing", 357 RFC 7230, DOI 10.17487/RFC7230, June 2014, 358 . 360 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 361 DOI 10.17487/RFC7517, May 2015, 362 . 364 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 365 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 366 . 368 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 369 RFC 7662, DOI 10.17487/RFC7662, October 2015, 370 . 372 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 373 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 374 May 2018, . 376 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 377 Authorization Server Metadata", RFC 8414, 378 DOI 10.17487/RFC8414, June 2018, 379 . 381 Author's Address 383 Guillaume Pujol 384 Digital Security 385 France 387 Email: guill.p.linux@gmail.com