idnits 2.17.1 draft-ietf-oauth-step-up-authn-challenge-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 -- The document date (11 May 2022) is 687 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) == Outdated reference: A later version (-16) exists of draft-ietf-oauth-dpop-08 Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Web Authorization Protocol V. Bertocci 3 Internet-Draft Auth0/Okta 4 Intended status: Standards Track B. Campbell 5 Expires: 12 November 2022 Ping Identity 6 11 May 2022 8 OAuth 2.0 Step-up Authentication Challenge Protocol 9 draft-ietf-oauth-step-up-authn-challenge-00 11 Abstract 13 It is not uncommon for resource servers to require different 14 authentication strengths or freshness according to the 15 characteristics of a request. This document introduces a mechanism 16 for a resource server to signal to a client that the authentication 17 event associated with the access token of the current request doesn't 18 meet its authentication requirements and specify how to meet them. 19 This document also codifies a mechanism for a client to request that 20 an authorization server achieve a specific authentication strength or 21 freshness when processing an authorization request. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on 12 November 2022. 40 Copyright Notice 42 Copyright (c) 2022 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 47 license-info) in effect on the date of publication of this document. 48 Please review these documents carefully, as they describe your rights 49 and restrictions with respect to this document. Code Components 50 extracted from this document must include Revised BSD License text as 51 described in Section 4.e of the Trust Legal Provisions and are 52 provided without warranty as described in the Revised BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 1.1. Conventions and Definitions . . . . . . . . . . . . . . . 3 58 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 3 59 3. Authentication Requirements Challenge . . . . . . . . . . . . 4 60 4. Authorization Request . . . . . . . . . . . . . . . . . . . . 5 61 5. Authorization Response . . . . . . . . . . . . . . . . . . . 6 62 6. Authentication Information Conveyed via Access Token . . . . 7 63 6.1. JWT Access Tokens . . . . . . . . . . . . . . . . . . . . 7 64 6.2. OAuth 2.0 Token Introspection . . . . . . . . . . . . . . 8 65 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 66 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 67 9. Normative References . . . . . . . . . . . . . . . . . . . . 9 68 10. Informative References . . . . . . . . . . . . . . . . . . . 9 69 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10 70 Appendix B. Document History . . . . . . . . . . . . . . . . . . 10 71 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 73 1. Introduction 75 In simple API authorization scenarios, an authorization server will 76 statically determine what authentication technique to use to handle a 77 given request on the basis of aspects such as the scopes requested, 78 the resource, the identity of the client and other characteristics 79 known at provisioning time. Although the approach is viable in many 80 situations, it falls short in several important circumstances. 81 Consider, for instance, an eCommerce API requiring different 82 authentication strengths depending on whether the item being 83 purchased exceeds a certain threshold, dynamically estimated by the 84 API itself using a logic that is opaque to the authorization server. 85 An API might also determine that a more recent user authentication is 86 required based on its own risk evaluation of the API request. 88 This document extends the error codes collection defined by [RFC6750] 89 with a new value, insufficient_user_authentication, which can be used 90 by resource servers to signal to the client that the authentication 91 event associated with the access token presented with the request 92 doesn't meet the authentication requirements of the resource server. 93 This document also introduces acr_values and max_age parameters for 94 the WWW-Authenticate response header defined by [RFC6750], which the 95 resource server can use to explicitly communicate to the client the 96 required authentication strength or recentness. 98 The client can use that information to reach back to the 99 authorization server with an authorization request specifying the 100 authentication requirements indicated by protected resource, by 101 including the acr_values or max_age parameter as defined in [OIDC]. 103 Those extensions will make it possible to implement interoperable 104 step up authentication with minimal work from resource servers, 105 clients and authorization servers. 107 1.1. Conventions and Definitions 109 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 110 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 111 "OPTIONAL" in this document are to be interpreted as described in BCP 112 14 [RFC2119] [RFC8174] when, and only when, they appear in all 113 capitals, as shown here. 115 2. Protocol Overview 117 Following is an end-to-end sequence of a typical step-up 118 authentication scenario implemented according to this specification. 119 The scenario assumes that, before the sequence described below takes 120 place, the client already obtained an access token for the protected 121 resource. 123 +----------+ +--------------+ 124 | | | | 125 | |-----(1) resource request------>| | 126 | | | | 127 | |<-------(2) challenge ----------| Resource | 128 | | | Server | 129 | | | | 130 | |-----(5) resource request ----->| | 131 | | | | 132 | |<---(6) protected resource -----| | 133 | | +--------------+ 134 | Client | 135 | | 136 | | +---------------+ 137 | | | | 138 | |---(3) authorization request--->| | 139 | | | | 140 | |<-------------...-------------->| Authorization | 141 | | | Server | 142 | |<------ (4) access token -------| | 143 | | | | 144 +----------+ +---------------+ 145 Figure 1: Abstract protocol flow 147 1. The client requests a protected resource, presenting an access 148 token. 149 2. The resource server determines that the circumstances in which 150 the presented access token was obtained offer insufficient 151 authentication strength and/or freshness, hence it denies the 152 request and returns a challenge describing (using a combination 153 of acr_values and max_age) what authentication requirements must 154 be met for the resource server to authorize a request. 155 3. The client directs the user agent to the authorization server 156 with an authorization request that includes the acr_values and/or 157 max_age indicated by the resource server in the previous step. 158 4. After whatever sequence required by the grant of choice plays 159 out, which will include the necessary steps to authenticate the 160 user in accordance with the acr_values and/or max_age values of 161 the authorization request, the authorization server returns a new 162 access token to the client. The access token contains or 163 references information about the authentication event. 164 5. The client repeats the request from step 1, presenting the newly 165 obtained access token. 166 6. The resource server finds that the user authentication performed 167 during the acquisition of the new access token complies with its 168 requirements, and returns the requested protected resource. 170 The validation operations mentioned in step 2 and 6 imply that the 171 resource server has a way of evaluating the authentication level by 172 which the access token was obtained. This document will describe how 173 the resource server can perform that determination when the access 174 token is a JWT Access token [RFC9068] or is validated via 175 introspection [RFC7662]. Other methods of determining the 176 authentication level by which the access token was obtained are 177 possible, per agreement by the authorization server and the protected 178 resource, but are beyond the scope of this specification. 180 3. Authentication Requirements Challenge 182 This specification introduces a new error code value for the error 183 parameter of [RFC6750] or authentication schemes, such as 184 [I-D.ietf-oauth-dpop], which use the error parameter: 186 insufficient_user_authentication The authentication event associated 187 with the access token presented with the request doesn't meet the 188 authentication requirements of the protected resource. 190 Note: the logic through which the resource server determines that the 191 current request doesn't meet the authentication requirements of the 192 protected resource, and associated functionality (such as expressing, 193 deploying and publishing such requirements) is out of scope for this 194 document. 196 Furthermore, this specification defines additional WWW-Authenticate 197 auth-param values to convey the authentication requirements back to 198 the client. 200 acr_values A space-separated string indicating, in order of 201 preference, the authentication context class reference values that 202 the protected resource requires the authentication event 203 associated with the access token. 204 max_age Indicates the allowable elapsed time in seconds since the 205 last active authentication event associated with the access token. 207 Below you can find an example of WWW-Authenticate header using the 208 insufficient_user_authentication error code value to inform the 209 client that the access token presented isn't sufficient to gain 210 access to the protected resource, and the acr_values parameter to let 211 the client know that the expected authentication level corresponds to 212 the authentication context class reference identified by myACR. 214 HTTP/1.1 401 Unauthorized 215 WWW-Authenticate: Bearer error="insufficient_user_authentication", 216 error_description="A different authentication level is required", 217 acr_values="myACR" 219 Figure 2 221 If the resource server determines that the request is also lacking 222 the scopes required by the requested resource, it MAY include the 223 scope attribute with the scope necessary to access the protected 224 resource, as described in section 3.1 of [RFC6750]. 226 4. Authorization Request 228 A client receiving an authorization error from the resource server 229 carrying the error code insufficient_user_authentication MAY parse 230 the WWW-Authenticate header for acr_values and max_age and use them, 231 if present, in a request to the authorization server to obtain a new 232 access token complying with the corresponding requirements. Both 233 acr_values and max_age authorization request parameters are OPTIONAL 234 parameters defined in Section 3.1.2.1. of [OIDC]. This document does 235 not introduce any changes in the authorization server behavior 236 defined in [OIDC] for precessing those parameters, hence any 237 authorization server implementing OpenID Connect will be able to 238 participate in the flow described here with little or no changes. 239 See Section Section 5 for more details. 241 The example request below indicates to the authorization server that 242 the client would like the authentication to occur according to the 243 authentication context class reference identified by myACR. 245 GET https://as.example.net/authorize?client_id=s6BhdRkqt3 246 &response_type=code&scope=purchase&acr_values=myACR 248 Figure 3 250 5. Authorization Response 252 Section 5.5.1.1 of [OIDC] establishes that an authorization server 253 receiving a request containing the acr_values parameter MAY attempt 254 to authenticate the user in a manner that satisfies the requested 255 Authentication Context Class Reference, and include the corresponding 256 value in the acr claim in the resulting ID Token. The same section 257 also establishes that in case the desired authentication level cannot 258 be met, the authorization server SHOULD include in the acr claim a 259 value reflecting the authentication level of the current session (if 260 any). The same section also states that if a request includes thee 261 max_age parameter, the authorization server MUST include the 262 auth_time claim in the issued ID Token. An authorization server 263 complying with this specification will react to the presence of the 264 acr_values and max_age parameters by including acr and auth_time in 265 the access token (see Section 6 for details). Although [OIDC] leaves 266 the authorization server free to decide how to handle the inclusion 267 of acr in ID Token when requested via acr_values, when it comes to 268 access tokens in this specification it is RECOMMENDED that the 269 requested acr value is treated as required for successfully 270 fulfilling the request. That is, the requested acr value is included 271 in the access token if the authentication operation successfully met 272 its requirements, or that the authorization request fails in all 273 other cases, returning unmet_authentication_requirements as defined 274 in [OIDCUAR]. The recommended behavior will help prevent clients 275 getting stuck in a loop where the authorization server keeps 276 returning tokens that the resource server already identified as not 277 meeting its requirements hence known to be rejected as well. 279 6. Authentication Information Conveyed via Access Token 281 To evaluate whether an access token meets the protected resource's 282 requirements, the resource servers needs a way of accessing 283 information about the authentication event by which that access token 284 was obtained. This specification provides guidance on how to convey 285 that information in conjunction with two common access token 286 validation methods: the one described in [RFC9068], where the access 287 token is encoded in JWT format and verified via a set of validation 288 rules, and the one described in [RFC7662], where the token is 289 validated and decoded by sending it to an introspection endpoint. 290 Authorization servers and resource servers MAY elect to use other 291 encoding and validation methods, however those are out of scope for 292 this document. 294 6.1. JWT Access Tokens 296 When access tokens are represented as JSON Web Tokens (JWT) 297 [RFC7519], the auth_time and acr claims (per Section 2.2.1 of 298 [RFC9068]) are used to convey the time and context of the user 299 authentication event that the authentication server performed during 300 the course of obtaining the access token. It is useful to bear in 301 mind that the values of those two parameters are established at user 302 authentication time and won't change in the event of access token 303 renewals. See the aforementioned Section 2.2.1 of [RFC9068] for 304 details. The following is a conceptual example showing the decoded 305 content of such a JWT access token. 307 Header: 309 {"typ":"at+JWT","alg":"RS256","kid":"LTacESbw"} 311 Claims: 313 { 314 "iss": "https://as.example.net", 315 "sub": "someone@example.net", 316 "aud": "https://rs.example.com", 317 "exp": 1646343000, 318 "iat": 1646340200, 319 "jti" : "e1j3V_bKic8-LAEB_lccD0G", 320 "client_id": "s6BhdRkqt3", 321 "scope": "purchase", 322 "auth_time": 1646340198, 323 "acr": "myACR" 324 } 326 Figure 4 328 6.2. OAuth 2.0 Token Introspection 330 OAuth 2.0 Token Introspection [RFC7662] defines a method for a 331 protected resource to query an authorization server about the active 332 state of an access token as well as to determine metainformation 333 about the token. The following two top-level introspection response 334 members are defined to convey information about the user 335 authentication event that the authentication server performed during 336 the course of obtaining the access token. 338 acr Authentication Context Class Reference. String specifying an 339 Authentication Context Class Reference value that identifies the 340 Authentication Context Class that the user authentication 341 performed satisfied. 342 auth_time Time when the user authentication occurred. A JSON 343 numeric value representing the number of seconds from 344 1970-01-01T00:00:00Z UTC until the time of date/time of the 345 authentication event. 347 The following example shows an introspection response with 348 information about the user authentication event by which the access 349 token was obtained. 351 HTTP/1.1 200 OK 352 Content-Type: application/json 354 { 355 "active": true, 356 "client_id": "s6BhdRkqt3", 357 "scope": "purchase", 358 "sub": "someone@example.net", 359 "aud": "https://rs.example.com", 360 "iss": "https://as.example.net", 361 "exp": 1639528912, 362 "iat": 1618354090, 363 "auth_time": 1646340198, 364 "acr": "myACR" 365 } 367 Figure 5 369 7. Security Considerations 371 [[TBD]] 372 Remember that oauth is not authN, you need a layer like OIDC to 373 handle that part. This is not an encouragement to abuse oauth. This 374 is about the authentication event of the user to the AS by which the 375 access token was obtained. 377 8. IANA Considerations 379 [[TBD]] 381 The insufficient_user_authentication error code in the "OAuth 382 Extensions Error" registry [IANA.OAuth.Params]. 384 Section 6.2 for acr and auth_time as top-level members of the 385 introspection response in the "OAuth Token Introspection Response" 386 registry [IANA.OAuth.Params]. 388 The acr_values and max_age WWW-Authenticate auth-params are "new" but 389 doesn't seem like any registration is needed or possible. 391 9. Normative References 393 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 394 Requirement Levels", BCP 14, RFC 2119, 395 DOI 10.17487/RFC2119, March 1997, 396 . 398 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 399 Framework: Bearer Token Usage", RFC 6750, 400 DOI 10.17487/RFC6750, October 2012, 401 . 403 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 404 RFC 7662, DOI 10.17487/RFC7662, October 2015, 405 . 407 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 408 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 409 May 2017, . 411 [RFC9068] Bertocci, V., "JSON Web Token (JWT) Profile for OAuth 2.0 412 Access Tokens", RFC 9068, DOI 10.17487/RFC9068, October 413 2021, . 415 10. Informative References 417 [I-D.abr-twitter-reply] 418 Roach, A., "A reply to a specific tweet", Work in 419 Progress, Internet-Draft, draft-abr-twitter-reply-00, 7 420 September 2018, . 423 [I-D.ietf-oauth-dpop] 424 Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., 425 Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof- 426 of-Possession at the Application Layer (DPoP)", Work in 427 Progress, Internet-Draft, draft-ietf-oauth-dpop-08, 2 May 428 2022, . 431 [IANA.OAuth.Params] 432 IANA, "OAuth Parameters", 433 . 435 [OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 436 C. Mortimore, "OpenID Connect Core 1.0 incorporating 437 errata set 1", 8 November 2014, 438 . 440 [OIDCUAR] Lodderstedt, T., "OpenID Connect Core Error Code 441 unmet_authentication_requirements", 8 May 2019, 442 . 445 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 446 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 447 . 449 Appendix A. Acknowledgements 451 I wanted to thank the Academy, the viewers at home, the shampoo 452 manufacturers, etc.. 454 Initially (kinda) discussed at the OAuth Security Workshop 2021 456 A number of others already but haven't kept track... 458 Appendix B. Document History 460 [[ To be removed from the final specification ]] 462 -00 (Working Group Draft) 463 * Initial WG revision (content unchanged from draft-bertocci-oauth- 464 step-up-authn-challenge-01) 466 -01 468 * Fixed example 469 * Clarified/noted that scope can also be in the WWW-Authenticate/401 471 -00 473 * Initial Individual Draft (with all the authority thereby bestowed 474 [I-D.abr-twitter-reply]). 476 Authors' Addresses 478 Vittorio Bertocci 479 Auth0/Okta 480 Email: vittorio@auth0.com 482 Brian Campbell 483 Ping Identity 484 Email: bcampbell@pingidentity.com