idnits 2.17.1 draft-ietf-oauth-iss-auth-resp-05.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 : ---------------------------------------------------------------------------- ** There are 3 instances of too long lines in the document, the longest one being 22 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (11 January 2022) is 829 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 (-25) exists of draft-ietf-oauth-security-topics-19 Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Web Authorization Protocol K. Meyer zu Selhausen 3 Internet-Draft Hackmanit 4 Intended status: Standards Track D. Fett 5 Expires: 15 July 2022 yes.com 6 11 January 2022 8 OAuth 2.0 Authorization Server Issuer Identification 9 draft-ietf-oauth-iss-auth-resp-05 11 Abstract 13 This document specifies a new parameter "iss" that is used to 14 explicitly include the issuer identifier of the authorization server 15 in the authorization response of an OAuth authorization flow. The 16 "iss" parameter serves as an effective countermeasure to "mix-up 17 attacks". 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on 15 July 2022. 36 Copyright Notice 38 Copyright (c) 2022 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 43 license-info) in effect on the date of publication of this document. 44 Please review these documents carefully, as they describe your rights 45 and restrictions with respect to this document. Code Components 46 extracted from this document must include Simplified BSD License text 47 as described in Section 4.e of the Trust Legal Provisions and are 48 provided without warranty as described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 3 54 2. Response Parameter "iss" . . . . . . . . . . . . . . . . . . 4 55 2.1. Example Authorization Response . . . . . . . . . . . . . 4 56 2.2. Example Error Response . . . . . . . . . . . . . . . . . 4 57 2.3. Providing the Issuer Identifier "iss" . . . . . . . . . . 4 58 2.4. Validation of the Issuer Identifier "iss" . . . . . . . . 5 59 3. Authorization Server Metadata . . . . . . . . . . . . . . . . 6 60 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 61 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 62 5.1. OAuth Authorization Server Metadata . . . . . . . . . . . 7 63 5.2. OAuth Parameters Registration . . . . . . . . . . . . . . 8 64 6. Normative References . . . . . . . . . . . . . . . . . . . . 8 65 7. Informative References . . . . . . . . . . . . . . . . . . . 8 66 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10 67 Appendix B. Document History . . . . . . . . . . . . . . . . . . 10 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 70 1. Introduction 72 The OAuth authorization framework [RFC6749] allows clients to 73 interact with multiple independent authorization servers under the 74 control of separate entities. Some OAuth grant types utilize the 75 resource owner's user-agent to deliver the authorization server's 76 response to the OAuth client. One example of this pattern is the 77 authorization response of the authorization code grant. 79 The authorization response as specified in Section 4.1.2 of [RFC6749] 80 does not contain any information about the identity of the 81 authorization server which issued the response. Therefore, clients 82 receiving a response from the resource owner's user-agent cannot be 83 sure who initially issued the response and the secrets contained 84 therein. The lack of certainty about the origin of the response 85 enables a class of attacks called "mix-up attacks". 87 Mix-up attacks are a potential threat to all OAuth clients that 88 interact with multiple authorization servers. When at least one of 89 these authorization servers is under an attacker's control, the 90 attacker can launch a mix-up attack to acquire authorization codes or 91 access tokens issued by any one of the other authorization servers. 92 There are multiple ways in which an attacker can gain control over an 93 authorization server supported by the client: For instance, an 94 authorization server could become compromised, or the attacker could 95 register their own authorization server, for example, using dynamic 96 client registration ([RFC7591]). 98 OAuth clients that interact with only one authorization server are 99 not vulnerable to mix-up attacks. However, when such clients decide 100 to add support for a second authorization server in the future they 101 become vulnerable and need to apply countermeasures to mix-up 102 attacks. 104 Mix-up attacks aim to steal an authorization code or access token by 105 tricking the client into sending the authorization code or access 106 token to the attacker instead of the honest authorization or resource 107 server. This marks a severe threat to the confidentiality and 108 integrity of resources whose access is managed with OAuth. A 109 detailed description and different variants of the mix-up attack 110 class can be found in Section 4.4 of the OAuth Security Best Current 111 Practice [I-D.ietf-oauth-security-topics] as well as in the original 112 research first highlighting this attack class, "On the security of 113 modern Single Sign-On Protocols: Second-Order Vulnerabilities in 114 OpenID Connect" [arXiv.1508.04324] and "A Comprehensive Formal 115 Security Analysis of OAuth 2.0" [arXiv.1601.01229]. 117 This document defines a new parameter in the authorization response 118 called "iss". The "iss" parameter allows the authorization server to 119 include its identity in the authorization response explicitly. The 120 client can compare the value of the "iss" parameter to the issuer 121 identifier of the authorization server (e.g., retrieved from its 122 metadata) it believes it is interacting with. The "iss" parameter 123 gives the client certainty about the authorization server's identity 124 and enables it to send credentials such as authorization codes and 125 access tokens only to the intended recipients. 127 The effectiveness of the "iss" parameter against mix-up attacks was 128 analyzed and formally proven in "A Comprehensive Formal Security 129 Analysis of OAuth 2.0" [arXiv.1601.01229]. 131 1.1. Conventions and Terminology 133 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 134 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 135 "OPTIONAL" in this document are to be interpreted as described in BCP 136 14 [RFC2119] [RFC8174] when, and only when, they appear in all 137 capitals, as shown here. 139 This specification uses the terms "access token", "authorization 140 code", "authorization code grant", "authorization server", "resource 141 server", "authorization response", "grant type", and "client" defined 142 by the OAuth 2.0 Authorization Framework [RFC6749] and the term 143 "issuer identifier" defined by OAuth 2.0 Authorization Server 144 Metadata [RFC8414]. 146 2. Response Parameter "iss" 148 In authorization responses to the client, including error responses, 149 an authorization server supporting this specification MUST indicate 150 its identity by including the "iss" parameter in the response. 152 The "iss" parameter value is the issuer identifier of the 153 authorization server which created the authorization response, as 154 defined in [RFC8414]. Its value MUST be a URL that uses the "https" 155 scheme without any query or fragment components. 157 2.1. Example Authorization Response 159 The following example shows an authorization response from the 160 authorization server whose issuer identifier is 161 "https://honest.as.example" (extra line breaks and indentation are 162 for display purposes only): 164 HTTP/1.1 302 Found 165 Location: https://client.example/cb? 166 code=x1848ZT64p4IirMPT0R-X3141MFPTuBX-VFL_cvaplMH58 167 &state=ZWVlNDBlYzA1NjdkMDNhYjg3ZjUxZjAyNGQzMTM2NzI 168 &iss=https%3A%2F%2Fhonest.as.example 170 2.2. Example Error Response 172 The following example shows an error response from the same 173 authorization server (extra line breaks and indentation are for 174 display purposes only): 176 HTTP/1.1 302 Found 177 Location: https://client.example/cb? 178 error=access_denied 179 &state=N2JjNGJhY2JiZjRhYzA3MGJkMzNmMDE5OWJhZmJhZjA 180 &iss=https%3A%2F%2Fhonest.as.example 182 2.3. Providing the Issuer Identifier "iss" 184 Authorization servers supporting this specification MUST provide 185 their issuer identifier to enable clients to validate the "iss" 186 parameter effectively. 188 For authorization servers publishing metadata according to [RFC8414], 189 the following rules apply: 191 * The issuer identifier included in the server's metadata value 192 "issuer" MUST be identical to the "iss" parameter's value. 194 * The server MUST indicate its support for the "iss" parameter by 195 setting the metadata parameter 196 "authorization_response_iss_parameter_supported", defined in 197 Section 3, to "true". 199 Authorization servers MAY additionally provide the issuer identifier 200 to clients by any other mechanism which is outside of the scope of 201 this specification. 203 2.4. Validation of the Issuer Identifier "iss" 205 Clients that support this specification MUST extract the value of the 206 "iss" parameter from authorization responses they receive if the 207 parameter is present. Clients MUST then decode the value from its 208 "application/x-www-form-urlencoded" form according to [RFC6749], 209 Appendix B, and compare the result to the issuer identifier of the 210 authorization server where the authorization request was sent to. 211 This comparison MUST use simple string comparison as defined in 212 Section 6.2.1 of [RFC3986]. If the value does not match the expected 213 issuer identifier, clients MUST reject the authorization response and 214 MUST NOT proceed with the authorization grant. For error responses, 215 clients MUST NOT assume that the error originates from the intended 216 authorization server. 218 More precisely, clients that interact with authorization servers 219 supporting OAuth metadata [RFC8414] MUST compare the "iss" parameter 220 value to the "issuer" value in the server's metadata document. If 221 OAuth metadata is not used, clients MUST use deployment-specific 222 ways, for example a static configuration, to decide if the returned 223 "iss" value is the expected value in the current flow (see also 224 Section 4). 226 If clients interact with both authorization servers supporting this 227 specification and authorization servers not supporting this 228 specification, clients MUST retain state about whether each 229 authorization server supports the "iss" parameter. Clients MUST 230 reject authorization responses without the "iss" parameter from 231 authorization servers which do support the parameter according to the 232 client's configuration. Clients SHOULD discard authorization 233 responses with the "iss" parameter from authorization servers which 234 do not indicate their support for the parameter. However, there 235 might be legitimate authorization servers that provide the "iss" 236 parameter without indicating their support in their metadata. Local 237 policy or configuration can determine whether to accept such 238 responses and specific guidance is out of scope for this 239 specification. 241 In general, clients that support this specification MAY accept 242 authorization responses that do not contain the "iss" parameter or 243 reject them and exclusively support authorization servers which 244 provide the "iss" parameter in the authorization response. Local 245 policy or configuration can determine when to accept such responses 246 and specific guidance is out of scope for this specification. 248 In OpenID Connect [OIDC.Core] flows where an ID Token is returned 249 from the authorization endpoint, the value in the "iss" parameter 250 MUST always be identical to the "iss" claim in the ID Token. 252 Section 4.1.2 of [RFC6749] already mandates that clients that do not 253 support this specification MUST ignore the unrecognized "iss" 254 parameter. 256 Note: The "JWT Secured Authorization Response Mode for OAuth 2.0 257 (JARM)" [JARM] defines a mechanism that conveys all authorization 258 response parameters in a JWT. This JWT contains an "iss" claim that 259 provides the same protection if it is validated as described in 260 Section 2.4. Therefore, an additional "iss" parameter outside the 261 JWT is not necessary when JARM is used. 263 3. Authorization Server Metadata 265 The following parameter for the authorization server metadata 266 [RFC8414] is introduced to signal the authorization server's support 267 for this specification: 269 "authorization_response_iss_parameter_supported" Boolean parameter 270 indicating whether the authorization server provides the "iss" 271 parameter in the authorization response as defined in Section 2. 272 If omitted, the default value is false. 274 4. Security Considerations 276 Clients MUST validate the "iss" parameter precisely as described in 277 Section 2.4 and MUST NOT allow multiple authorization servers to use 278 the same issuer identifier. In particular, when authorization server 279 details can be manually configured in the client, the client MUST 280 ensure that the accepted "iss" values are unique for each 281 authorization server. 283 The "iss" parameter enables a client to decide if an authorization 284 server "expects" to be used in an OAuth flow together with a certain 285 token endpoint and potentially other endpoints, like the userinfo 286 endpoint ([OIDC.Core]). When OAuth metadata is used, the "iss" 287 parameter identifies the issuer and therefore the respective OAuth 288 metadata document which points to the other endpoints. When OAuth 289 metadata is not used, the client can use, for example, a statically 290 configured expected "iss" value for each configured authorization 291 server. 293 The issuer identifier contained in the authorization response is not 294 cryptographically protected against tampering. In general, 295 mechanisms such as JWTs (as specified in JARM [JARM]) could be used 296 to protect the integrity of the authorization response. However, in 297 mix-up attacks, the client generally receives the authorization 298 response from an uncompromised authorization server. If an attacker 299 can tamper this authorization response before it is received by the 300 client, the attacker would also have direct access to the 301 authorization code. The attacker does not need to execute a mix-up 302 attack to steal the authorization code. Therefore, integrity 303 protection for the authorization response is not necessary to defend 304 against mix-up attacks. 306 There are also alternative countermeasures to mix-up attacks. When 307 an authorization response already includes an authorization server's 308 issuer identifier by other means, and this identifier is checked as 309 laid out in Section 2.4, the use and verification of the "iss" 310 parameter is not necessary and MAY be omitted. This is the case when 311 OpenID Connect response types that return an ID token from the 312 authorization endpoint (e.g., "response_type=code id_token") or JARM 313 response mode are used, for example. However, if a client receives 314 an authorization response that contains multiple issuer identifiers, 315 the client MUST reject the response if these issuer identifiers do 316 not match. The details of alternative countermeasures are outside of 317 the scope of this specification. 319 Mix-up attacks are only relevant to clients that interact with 320 multiple authorization servers. However, clients interacting with 321 only one authorization server might add support for a second 322 authorization server in the future. By supporting multiple 323 authorization servers they become vulnerable to mix-up attacks and 324 need to apply countermeasures. 326 5. IANA Considerations 328 5.1. OAuth Authorization Server Metadata 330 This specification adds the following values to the IANA "OAuth 331 Authorization Server Metadata" registry of [IANA.OAuth.Parameters] 332 established by [RFC8414]. 334 Metadata Name: "authorization_response_iss_parameter_supported" 335 Metadata Description: Boolean value indicating whether the 336 authorization server provides the "iss" parameter in the 337 authorization response. 338 Change Controller: IETF 339 Specification Document(s): Section 3 of [[ this document ]] 341 5.2. OAuth Parameters Registration 343 This specification updates the "iss" entry in the IANA "OAuth 344 Parameters" registry of [IANA.OAuth.Parameters] established by 345 [RFC6749]. 347 Parameter name: "iss" 348 Parameter usage location: authorization request, authorization 349 response 350 Change Controller: IETF 351 Specification Document(s): Section 2 of [[ this document ]], 352 [RFC9101], and Section 4.1.1 of [RFC7519]. 354 6. Normative References 356 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 357 Requirement Levels", BCP 14, RFC 2119, 358 DOI 10.17487/RFC2119, March 1997, 359 . 361 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 362 RFC 6749, DOI 10.17487/RFC6749, October 2012, 363 . 365 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 366 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 367 May 2017, . 369 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 370 Resource Identifier (URI): Generic Syntax", STD 66, 371 RFC 3986, DOI 10.17487/RFC3986, January 2005, 372 . 374 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 375 Authorization Server Metadata", RFC 8414, 376 DOI 10.17487/RFC8414, June 2018, 377 . 379 7. Informative References 381 [RFC9101] Sakimura, N., Bradley, J., and M. Jones, "The OAuth 2.0 382 Authorization Framework: JWT-Secured Authorization Request 383 (JAR)", RFC 9101, DOI 10.17487/RFC9101, August 2021, 384 . 386 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 387 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 388 . 390 [I-D.ietf-oauth-security-topics] 391 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 392 "OAuth 2.0 Security Best Current Practice", Work in 393 Progress, Internet-Draft, draft-ietf-oauth-security- 394 topics-19, 16 December 2021, . 397 [arXiv.1601.01229] 398 Fett, D., Kuesters, R., and G. Schmitz, "A Comprehensive 399 Formal Security Analysis of OAuth 2.0", 6 January 2016, 400 . 402 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 403 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 404 RFC 7591, DOI 10.17487/RFC7591, July 2015, 405 . 407 [IANA.OAuth.Parameters] 408 IANA, "OAuth Parameters", 409 . 411 [OIDC.Core] 412 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 413 C. Mortimore, "OpenID Connect Core 1.0 incorporating 414 errata set 1", 8 November 2014, 415 . 417 [JARM] Lodderstedt, T. and B. Campbell, "Financial-grade API: JWT 418 Secured Authorization Response Mode for OAuth 2.0 (JARM)", 419 17 October 2018, 420 . 422 [arXiv.1508.04324] 423 Mainka, C., Mladenov, V., and J. Schwenk, "On the security 424 of modern Single Sign-On Protocols: Second-Order 425 Vulnerabilities in OpenID Connect", 18 August 2015, 426 . 428 Appendix A. Acknowledgements 430 We would like to thank Brian Campbell, Roman Danyliw, Vladimir 431 Dzhuvinov, Joseph Heenan, Takahiko Kawasaki, Torsten Lodderstedt, 432 Christian Mainka, Vladislav Mladenov, Warren Parad, Aaron Parecki, 433 and Rifaat Shekh-Yusef for their valuable feedback on this document. 435 Appendix B. Document History 437 [[ To be removed from the final specification ]] 439 -05 [[ Working Group Draft ]] 440 * Changed reference to OAuth Security Best Current Practices from normative to informative 442 -04 [[ Working Group Draft ]] 443 * Incorporated feedback from Lars Eggert 444 * Incorporated feedback from Francesca Palombini (IANA registrations) 445 * Incorporated feedback from Benjamin Kaduk 447 -03 [[ Working Group Draft ]] 448 * Incorporated feedback from AD review 449 * Incorporated feedback from artart and secdir reviews 451 -02 [[ Working Group Draft ]] 452 * Incorporated feedback from shepherd review 453 * Changed SHOULD to MUST (clients MUST store which AS support `iss` parameter) 454 * Added note for clients receiving unexpected `iss` parameter 455 * Editorial changes 457 -01 [[ Working Group Draft ]] 458 * Incorporated WG feedback 459 * Changed title of the draft to make it shorter 460 * Clarified mix-up attacks in introduction 461 * Improved note on JARM in validation section 463 -00 [[ Working Group Draft ]] 464 * Working group draft 466 -02 467 * Incorporated WG feedback 468 * Clarifications for unique issuer identifier 469 * Clarifications when multiple issuer identifier could be present 470 * Added note that iss parameter MUST NOT be used with JARM 471 * Added note on error responses and example for error response 472 * Editorial changes 474 -01 475 * Incorporated first WG feedback 476 * Clarifications for use with OIDC 477 * Added note that clients supporting just one AS are not vulnerable 478 * Renamed metadata parameter 479 * Various editorial changes 481 -00 483 * initial draft 485 Authors' Addresses 487 Karsten Meyer zu Selhausen 488 Hackmanit 490 Email: karsten.meyerzuselhausen@hackmanit.de 492 Daniel Fett 493 yes.com 495 Email: mail@danielfett.de