idnits 2.17.1 draft-gpujol-oauth-atrl-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 == Line 106 has weird spacing: '... server this ...' == Line 112 has weird spacing: '... server this ...' -- The document date (September 10, 2018) is 2053 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 == Unused Reference: 'RFC8392' is defined on line 384, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 1 error (**), 0 flaws (~~), 5 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 September 10, 2018 5 Expires: March 14, 2019 7 OAuth 2.0 Token Revocation List 8 draft-gpujol-oauth-atrl-01 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 March 14, 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 . . . . . . . . . 7 63 8.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 7 64 9. Revision History . . . . . . . . . . . . . . . . . . . . . . 7 65 10. Normative References . . . . . . . . . . . . . . . . . . . . 8 66 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 68 1. Introduction 70 OAuth 2.0 Token Revocation [RFC7009] defines a way for OAuth 2.0 71 clients to revoke access tokens and refresh tokens issued by an OAuth 72 2.0 authorization server. While refresh token are typically only 73 used by the authorization server itself, access tokens on the other 74 hand are consumed by OAuth 2.0 resource servers; those are logically 75 separated from the authorization server, and must learn about the 76 revocation status of the access tokens they receive, if the local 77 security requirements mandates it. 79 Some deployments of OAuth 2.0 (or derived protocols) use signed JWT 80 as access tokens. Those access tokens are self-sufficient for 81 resource server to validate that the access token is currently not 82 expired, but provide no means for the resource server to obtain the 83 revocation status of the token. 85 OAuth 2.0 Token Introspection [RFC7662] defines a way for resource 86 servers to obtain the metadata attached to a given access token. For 87 performance reasons, this metadata may be put in cache by the 88 resource server, instead of calling the introspection endpoint 89 synchronously every time the same access token is received. This 90 voids the possibility for the resource server to be informed about a 91 revocation of an access token that occurs after the first call to the 92 introspection endpoint. 94 This specification defines a Token Revocation List (TRL), a document 95 exposed by the OAuth 2.0 authorization server, containing a list of 96 revoked access tokens identifiers. Resource servers can periodically 97 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 preferred 180 way to obtain the revocation status of access tokens, rather that 181 using 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_token_ids REQUIRED. a JSON list whose items are the identifiers 195 of the revoked and non-expired access tokens at the time the TRL 196 was generated. 198 The JWT payload MAY contain other claims. Claims not known or not 199 understood by resource servers MUST be ignored. 201 Token identifiers in the "rev_token_ids" MUST be unique token 202 identifiers, allowing resource server to unambiguously identify 203 revoked access tokens. For access tokens in JWT format, those 204 identifiers MUST match "jti" values of issued tokens. For access 205 tokens in CWT format, this must match the "cid" values. For access 206 tokens in other formats, "rev_token_ids" claim MAY include any kind 207 of token identifier, depending on the format of access tokens issued 208 by the authorisation server, as long as both resource servers and 209 authorization server have beforehand agreement on the identifier. 211 To allow resource servers to learn about the revocation status of a 212 token, the resource server must be able to obtain this unique token 213 identifier. This can be done either by reading the jti or cti claim 214 from access tokens that are in JWT or CWT formats, respectively, or 215 by reading the jti attribute as returned by the authorization server 216 introspection endpoint. 218 The TRL exposed by an OAuth authorization server at any given time 219 MUST always have an expiration date (exp) in the future and SHOULD 220 have an expiration date reasonably far away in the future. The exact 221 frequency for an authorization server to generate a new TRL and the 222 lifetime of generated TRLs is deployment specific and is out of scope 223 of this specification. Some authorization servers MAY choose to 224 generate a new TRL every time an access token is revoked, while 225 others MAY generate a new TRL periodically at a fixed time period. 226 Some MAY also choose to generate a new TRL only when an access token 227 considered as security sensitive is revoked (e.g. bound to a scope 228 that is internally flagged as sensitive). 230 A TRL SHOULD contain only a list of token identifiers that are 231 revoked and not expired at the time the TRL is generated. A TRL MUST 232 NOT contain a token identifier of a token that has not been revoked 233 before the TRL is generated. A TRL MAY contain some token 234 identifiers that have been revoked but are already expired at the 235 time the TRL is generated. 237 A TRL MUST be signed. That signature MUST use an asymmetric 238 algorithm, and the JWT header MUST contain both the "alg" and the 239 "kid" claims as defined in RFC7515 [RFC7515]; the JWK referenced by 240 this kid MUST be part of the JWKS [RFC7517] exposed by the 241 authorization server on its jwks_uri. 243 A TRL MUST NOT be encrypted. 245 5. Token Revocation List Request 247 An authorization server Token Revocation List MUST be queried using 248 an HTTP "GET" request [RFC7230] at the URL defined in the 249 authorization server metadata. 251 The following is a non-normative example TRL request (with line 252 breaks for display purposes only): 254 GET /token_revocation_list HTTP/1.1 255 Host: server.example.com 257 Once a resource server obtains a TRL and that TRL reaches its 258 expiration date, a resource server SHOULD obtain a new TRL from the 259 authorization server. A resource server MAY obtain a new TRL before 260 the last TRL in its possession is expired. The frequency at which 261 the resource server obtains updated TRLs is out of the scope of this 262 specification, and depends on the resource server security 263 requirements. 265 6. Token Revocation List Response 267 An authorization server responds to a Token Revocation List request 268 with the most recently available TRL and the Content-Type 269 "application/jwt". 271 The following is a non-normative example TRL response (with line 272 breaks for display purposes only): 274 200 OK 275 Content-Type: application/jwt 276 Content-Length: 542 278 eyJhbGciOiJSUzI1NiIsImtpZCI6IlRSTF8yMDE4MDcxMCJ9.eydleHAnOiAxNTM 279 xMzIzMDY4LjI3NzM2LCAnaWF0JzogMTUzMTMyMzAwOC4yNzczNiwgJ2lzcyc6ICd 280 zZXJ2ZXIuZXhhbXBsZS5jb20nLCAncmV2X3Rva2VuX2lkcyc6IFsnMTIzNDU2Nzk 281 wJywgJzIzNDU2Nzg5MDEnXX0.LdMV-QMRsXwHxI4ZfQvQEv5_wNe22VHBa5x6CIb 282 G-3H-0R2nMnB_tNeA8nngNNo_vdDRj6Z25Bu6wlTQOM8VufPbUGyAM1Q3LLjPU8p 283 cEnM79Z8LW305M09ILaumgg94HrFSTPyEnlIGkVFF_x2vYTf-FbYEFlz2he3WDat 284 oPXXXh9gVlfTeinPwVtEZv-k740nUHVJjoSLSS7f_ZVmRnT_wUF_Wisx5YRtrkcu 285 8bXJqEykswgYmrzxewCHsc03qEV3HwQPc15_MJBF8tQT9vLTwnYSdMXJh9J5uREz 286 IEFqBQpQyIAtbqVT7eD9OMQOttWfB5LVtlnAVHRRdFVkuWA 288 7. Security Considerations 290 The TRL is publicly exposed to anyone, not just authorized resource 291 servers. However the TRL does not contain security sensitive values, 292 just identifiers of tokens, that are not sufficient by themselves to 293 gain any unauthorized access to any protected resource. An 294 alternative would be to require some form of authentication of TRL 295 clients (which in this case, are themselves resource servers). 296 However, the added complexity, and performance impact (however small) 297 of managing that authentication would curb usage of the TRL. 299 The TRL MUST be signed by its issuer (the authorization server). The 300 resource servers MUST validate the signature before trusting the 301 contents of the TRL. This avoids misuse or denial of service when 302 the party controlling the https (server-side) connection (which, in 303 complex environments, may be different than the entity controlling 304 the authorization servers) removes revoked tokens from the TRL, and/ 305 or issues a TRL containing non-revoked tokens. To effectively 306 protect against such attacks, the jwks_uri exposing the public keys 307 must not be exposed by the same party as the the 308 token_revocation_list_uri. 310 8. IANA Considerations 312 8.1. OAuth 2.0 Authorization Server Metadata 314 This specification registers the following values in the IANA "OAuth 315 2.0 Authorization Server Metadata" registry [IANA.OAuth.Parameters] 316 established by [RFC8414]. 318 8.1.1. Registry Contents 320 o Metadata name: token_revocation_list_uri 321 o Metadata Description: The Token Revocation List Uri. 322 o Change controller: IESG 323 o Specification Document: Section 3 of [[ this specification ]] 325 9. Revision History 327 Note to the RFC Editor: Please remove this section from the final 328 RFC. 330 -01 332 o TRLs MUST be signed. 334 o Single TRL claim "rev_token_ids" for all kind of token identifiers 335 o Token IDs can include "jti" from JWTs, "cti" from CWT, or other 336 form of ids. 338 10. Normative References 340 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 341 Requirement Levels", BCP 14, RFC 2119, 342 DOI 10.17487/RFC2119, March 1997, 343 . 345 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 346 Resource Identifier (URI): Generic Syntax", STD 66, 347 RFC 3986, DOI 10.17487/RFC3986, January 2005, 348 . 350 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 351 RFC 6749, DOI 10.17487/RFC6749, October 2012, 352 . 354 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 355 Framework: Bearer Token Usage", RFC 6750, 356 DOI 10.17487/RFC6750, October 2012, 357 . 359 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 360 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 361 August 2013, . 363 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 364 Protocol (HTTP/1.1): Message Syntax and Routing", 365 RFC 7230, DOI 10.17487/RFC7230, June 2014, 366 . 368 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 369 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 370 2015, . 372 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 373 DOI 10.17487/RFC7517, May 2015, 374 . 376 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 377 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 378 . 380 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 381 RFC 7662, DOI 10.17487/RFC7662, October 2015, 382 . 384 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 385 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 386 May 2018, . 388 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 389 Authorization Server Metadata", RFC 8414, 390 DOI 10.17487/RFC8414, June 2018, 391 . 393 Author's Address 395 Guillaume Pujol 396 Digital Security 397 France 399 Email: guill.p.linux@gmail.com