idnits 2.17.1 draft-meyerzuselhausen-oauth-iss-auth-resp-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 -- The document date (1 November 2020) is 1272 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) ** Downref: Normative reference to an Informational RFC: RFC 6479 == Outdated reference: A later version (-26) exists of draft-ietf-oauth-security-topics-16 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: 5 May 2021 yes.com 6 1 November 2020 8 OAuth 2.0 Authorization Server Issuer Identifier in Authorization 9 Response 10 draft-meyerzuselhausen-oauth-iss-auth-resp-01 12 Abstract 14 This document specifies a new parameter "iss" that is used to 15 explicitly include the issuer identifier of the authorization server 16 in the authorization response of an OAuth authorization flow. If 17 implemented correctly, the "iss" parameter serves as an effective 18 countermeasure to "mix-up attacks". 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on 5 May 2021. 37 Copyright Notice 39 Copyright (c) 2020 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 44 license-info) in effect on the date of publication of this document. 45 Please review these documents carefully, as they describe your rights 46 and restrictions with respect to this document. Code Components 47 extracted from this document must include Simplified BSD License text 48 as described in Section 4.e of the Trust Legal Provisions and are 49 provided without warranty as described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 3 55 2. Response Parameter "iss" . . . . . . . . . . . . . . . . . . 4 56 2.1. Example Authorization Response . . . . . . . . . . . . . 4 57 2.2. Providing the Issuer Identifier "iss" . . . . . . . . . . 4 58 2.3. Validation of the Issuer Identifier "iss" . . . . . . . . 5 59 3. Authorization Server Metadata . . . . . . . . . . . . . . . . 5 60 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 61 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 62 5.1. OAuth Authorization Server Metadata . . . . . . . . . . . 7 63 5.2. OAuth Parameters Registration . . . . . . . . . . . . . . 7 64 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 65 7. Normative References . . . . . . . . . . . . . . . . . . . . 7 66 8. Informative References . . . . . . . . . . . . . . . . . . . 8 67 Appendix A. Document History . . . . . . . . . . . . . . . . . . 9 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 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 80 [RFC6479] 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. The lack of certainty about 84 the origin of the response benefits a class of attacks called "mix-up 85 attacks". 87 This type of attack is a threat to all OAuth clients that interact 88 with multiple authorization servers when at least one of these 89 authorization servers is under an attacker's control. There are 90 multiple ways in which an attacker can gain control over an 91 authorization server supported by the client: For example, an 92 authorization server could become compromised, or the attacker could 93 register their own authorization server if the client supports 94 multiple authorization servers and dynamic client registration 95 ([RFC7591]). 97 OAuth clients that interact with only one authorization server are 98 not vulnerable to mix-up attacks. However, when such clients decide 99 to add support for a second authorization server in the future they 100 become vulnerable and need to apply countermeasures to mix-up 101 attacks. 103 Mix-up attacks aim to steal an authorization code or access token by 104 tricking the client into sending the authorization code or access 105 token to the attacker instead of the honest authorization or resource 106 server. This marks a severe threat to the confidentiality and 107 integrity of resources whose access is managed with OAuth. A 108 detailed description and different variants of the mix-up attack 109 class can be found in Section 4.4. of the OAuth Security Best Current 110 Practices [I-D.ietf-oauth-security-topics]. 112 This document defines a new parameter in the authorization response 113 called "iss". The "iss" parameter allows the authorization server to 114 include its identity in the authorization response explicitly. The 115 client can compare the value of the "iss" parameter to the issuer 116 identifier of the authorization server (e.g., retrieved from its 117 metadata) it believes it is interacting with. The "iss" parameter 118 gives the client certainty about the authorization server's identity 119 and enables it to send credentials such as authorization codes and 120 access tokens only to the intended recipients. Therefore, the 121 implementation of the "iss" parameter serves as an effective 122 countermeasure to mix-up attacks. 124 1.1. Conventions and Terminology 126 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 127 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 128 "OPTIONAL" in this document are to be interpreted as described in BCP 129 14 [RFC2119] [RFC8174] when, and only when, they appear in all 130 capitals, as shown here. 132 This specification uses the terms "access token", "authorization 133 code", "authorization code grant", "authorization server", "resource 134 server", "authorization response", "grant type", and "client" defined 135 by the OAuth 2.0 Authorization Framework [RFC6749] and the term 136 "issuer identifier" defined by OAuth 2.0 Authorization Server 137 Metadata [RFC8414]. 139 2. Response Parameter "iss" 141 In authorization responses to the client, an authorization server 142 supporting this specification MUST indicate its identity by including 143 the "iss" parameter in the response. 145 The "iss" parameter value is the issuer identifier of the 146 authorization server which created the authorization response, as 147 defined in [RFC8414]. Its value MUST be a URL that uses the "https" 148 scheme without any query or fragment components. If the 149 authorization server provides metadata as defined in [RFC8414], the 150 value of the parameter "iss" MUST be identical to the authorization 151 server metadata value "issuer". 153 2.1. Example Authorization Response 155 The following example shows an authorization response from the 156 authorization server whose issuer identifier is 157 "https://honest.as.example" (extra line breaks and indentation are 158 for display purposes only): 160 HTTP/1.1 302 Found 161 Location: https://client.example/cb? 162 code=x1848ZT64p4IirMPT0R-X3141MFPTuBX-VFL_cvaplMH58 163 &state=ZWVlNDBlYzA1NjdkMDNhYjg3ZjUxZjAyNGQzMTM2NzI 164 &iss=https://honest.as.example 166 2.2. Providing the Issuer Identifier "iss" 168 Authorization servers supporting this specification MUST provide 169 their issuer identifier to enable clients to validate the "iss" 170 parameter effectively. 172 For authorization servers publishing metadata according to [RFC8414], 173 the following rules apply: 175 * The issuer identifier included in the server's metadata value 176 "issuer" MUST be identical to the "iss" parameter's value. 178 * The server MUST indicate its support for the "iss" parameter by 179 setting the metadata parameter 180 "authorization_response_iss_parameter_supported", defined in 181 Section 3, to "true". 183 Authorization servers MAY additionally provide the issuer identifier 184 to clients by any other mechanism which is outside of the scope of 185 this specification. 187 2.3. Validation of the Issuer Identifier "iss" 189 Clients that support this specification MUST extract the value of the 190 "iss" parameter from authorization responses they receive if the 191 parameter is present. Clients MUST compare the extracted and URL- 192 decoded value to the issuer identifier of the authorization server 193 where the authorization request was sent to. This comparison MUST 194 use simple string comparison as defined in Section 6.2.1. of 195 [RFC3986]. If the value does not match the expected issuer 196 identifier, clients MUST reject the authorization response and MUST 197 NOT proceed with the authorization grant. 199 More precisely, clients that interact with authorization servers 200 supporting OAuth metadata [RFC8414] MUST compare the "iss" parameter 201 value to the "issuer" value in the server's metadata document. If 202 OAuth metadata is not used, clients MUST use deployment-specific 203 ways, for example a static configuration, to decide if the returned 204 "iss" value is the expected value in the current flow (see also 205 Section 4). 207 If clients interact with both authorization servers supporting this 208 specification and authorization servers not supporting this 209 specification, clients SHOULD store the information which 210 authorization server supports the "iss" parameter. Clients MUST 211 reject authorization responses without the "iss" parameter from 212 authorization servers which do support the parameter according to the 213 client's configuration. 215 In general, clients that support this specification MAY accept 216 authorization responses that do not contain the "iss" parameter or 217 reject them and exclusively support authorization servers which 218 provide the "iss" parameter in the authorization response. This 219 decision is individual for every scenario and it is not in the scope 220 of this specification. 222 In OpenID Connect [OIDC.Core] flows where an ID Token is returned 223 from the authorization endpoint, the value in the "iss" parameter 224 MUST always be identical to the "iss" Claim in the ID Token. 226 Section 4.1.2. of [RFC6479] already mandates that clients that do not 227 support this specification MUST ignore the unrecognized "iss" 228 parameter. 230 3. Authorization Server Metadata 232 The following parameter for the authorization server metadata 233 [RFC8414] is introduced to signal the authorization server's support 234 for this specification: 236 "authorization_response_iss_parameter_supported" Boolean parameter 237 indicating whether the authorization server provides the "iss" 238 parameter in the authorization response as defined in Section 2. 239 If omitted, the default value is false. 241 4. Security Considerations 243 The authorization response parameter "iss" defined in this 244 specification serves as a countermeasure to mix-up attacks described 245 in Section 4.4. of the OAuth Security Best Current Practices 246 [I-D.ietf-oauth-security-topics] and in detail in "On the security of 247 modern Single Sign-On Protocols: Second-Order Vulnerabilities in 248 OpenID Connect" [arXiv.1508.04324] and "A Comprehensive Formal 249 Security Analysis of OAuth 2.0" [arXiv.1601.01229]. The latter 250 provides a formal proof of the effectiveness of the countermeasure. 252 Clients MUST validate the "iss" parameter precisely as described in 253 Section Section 2.3 and MUST NOT allow multiple authorization servers 254 to return the same issuer identifier during registration. 256 The "iss" parameter enables a client to decide if an authorization 257 server "expects" to be used in an OAuth flow together with a certain 258 token endpoint and potentially other endpoints, like the userinfo 259 endpoint ([OIDC.Core]). When OAuth metadata is used, the "iss" 260 parameter identifes the issuer and therefore the respective OAuth 261 metadata document which points to the other endpoints. When OAuth 262 metadata is not used, the client can use, for example, a statically 263 configured expected "iss" value for each configured authorization 264 server. 266 The issuer identifier contained in the authorization response is not 267 cryptographically protected against tampering. In general, 268 mechanisms such as JWTs (as specified in "JWT Secured Authorization 269 Response Mode for OAuth 2.0 (JARM)" [JARM]) could be used to protect 270 the integrity of the authorization response. However, in mix-up 271 attacks, the client generally receives the authorization response 272 from an uncompromised authorization server. If an attacker can 273 tamper this authorization response before it is received by the 274 client, the attacker would also have direct access to the 275 authorization code. The attacker does not need to execute a mix-up 276 attack to steal the authorization code. Therefore, integrity 277 protection for the authorization response is not necessary to defend 278 against mix-up attacks. 280 There are also alternative countermeasures to mix-up attacks. For 281 example, the authorization server's issuer identifier is included in 282 ID Tokens in OpenID Connect [OIDC.Core]. This inclusion enables 283 clients to rely on the "iss" Claim in the ID Token when an ID Token 284 is returned in the authorization response. These alternative 285 countermeasures are outside of the scope of this specification. 287 Mix-up attacks are only relevant to clients that interact with 288 multiple authorization servers. However, clients interacting with 289 only one authorization server might add support for a second 290 authorization server in the future. By supporting multiple 291 authorization servers they become vulnerable to mix-up attacks and 292 need to apply countermeasures. 294 5. IANA Considerations 296 5.1. OAuth Authorization Server Metadata 298 This specification requests registration of the following values in 299 the IANA "OAuth Authorization Server Metadata" registry of 300 [IANA.OAuth.Parameters] established by [RFC8414]. 302 Metadata Name: "authorization_response_iss_parameter_supported" 303 Metadata Description: Boolean value indicating whether the 304 authorization server provides the "iss" parameter in the 305 authorization response. 306 Change Controller: IESG 307 Specification Document(s): Section 3 of [[ this document ]] 309 5.2. OAuth Parameters Registration 311 This specification requests registration of the following values in 312 the IANA "OAuth Parameters" registry of [IANA.OAuth.Parameters] 313 established by [RFC6749]. 315 Parameter name: "iss" 316 Parameter usage location: authorization response 317 Change Controller: IESG 318 Specification Document(s): Section 2 of [[ this document ]] 320 6. Acknowledgements 322 TBD 324 7. Normative References 326 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 327 Resource Identifier (URI): Generic Syntax", STD 66, 328 RFC 3986, DOI 10.17487/RFC3986, January 2005, 329 . 331 [RFC6479] Zhang, X. and T. Tsou, "IPsec Anti-Replay Algorithm 332 without Bit Shifting", RFC 6479, DOI 10.17487/RFC6479, 333 January 2012, . 335 [I-D.ietf-oauth-security-topics] 336 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 337 "OAuth 2.0 Security Best Current Practice", Work in 338 Progress, Internet-Draft, draft-ietf-oauth-security- 339 topics-16, 5 October 2020, . 342 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 343 Authorization Server Metadata", RFC 8414, 344 DOI 10.17487/RFC8414, June 2018, 345 . 347 [IANA.OAuth.Parameters] 348 IANA, "OAuth Parameters", 349 . 351 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 352 RFC 6749, DOI 10.17487/RFC6749, October 2012, 353 . 355 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 356 Requirement Levels", BCP 14, RFC 2119, 357 DOI 10.17487/RFC2119, March 1997, 358 . 360 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 361 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 362 May 2017, . 364 8. Informative References 366 [arXiv.1508.04324] 367 Mainka, C., Mladenov, V., and J. Schwenk, "On the security 368 of modern Single Sign-On Protocols: Second-Order 369 Vulnerabilities in OpenID Connect", 18 August 2015, 370 . 372 [JARM] Lodderstedt, T. and B. Campbell, "Financial-grade API: JWT 373 Secured Authorization Response Mode for OAuth 2.0 (JARM)", 374 17 October 2018, 375 . 377 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 378 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 379 RFC 7591, DOI 10.17487/RFC7591, July 2015, 380 . 382 [OIDC.Core] 383 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 384 C. Mortimore, "OpenID Connect Core 1.0 incorporating 385 errata set 1", 8 November 2014, 386 . 388 [arXiv.1601.01229] 389 Fett, D., Kuesters, R., and G. Schmitz, "A Comprehensive 390 Formal Security Analysis of OAuth 2.0", 6 January 2016, 391 . 393 Appendix A. Document History 395 [[ To be removed from the final specification ]] 397 -01 399 * Incorporated first WG feedback 400 * Clarifications for use with OIDC 401 * Added note that clients supporting just one AS are not vulnerable 402 * Renamed metadata parameter 403 * Various editorial changes 405 -00 407 * initial draft 409 Authors' Addresses 411 Karsten Meyer zu Selhausen 412 Hackmanit 414 Email: karsten.meyerzuselhausen@hackmanit.de 416 Daniel Fett 417 yes.com 418 Email: mail@danielfett.de