idnits 2.17.1 draft-ietf-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 (8 June 2021) is 1051 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-18 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: 10 December 2021 yes.com 6 8 June 2021 8 OAuth 2.0 Authorization Server Issuer Identification 9 draft-ietf-oauth-iss-auth-resp-01 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 10 December 2021. 36 Copyright Notice 38 Copyright (c) 2021 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" . . . . . . . . . . . . . . . . . . 3 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. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8 65 7. Normative References . . . . . . . . . . . . . . . . . . . . 8 66 8. Informative References . . . . . . . . . . . . . . . . . . . 9 67 Appendix A. Document History . . . . . . . . . . . . . . . . . . 9 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 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 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]. 113 This document defines a new parameter in the authorization response 114 called "iss". The "iss" parameter allows the authorization server to 115 include its identity in the authorization response explicitly. The 116 client can compare the value of the "iss" parameter to the issuer 117 identifier of the authorization server (e.g., retrieved from its 118 metadata) it believes it is interacting with. The "iss" parameter 119 gives the client certainty about the authorization server's identity 120 and enables it to send credentials such as authorization codes and 121 access tokens only to the intended recipients. Therefore, the 122 implementation of the "iss" parameter serves as an effective 123 countermeasure to mix-up attacks. 125 1.1. Conventions and Terminology 127 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 128 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 129 "OPTIONAL" in this document are to be interpreted as described in BCP 130 14 [RFC2119] [RFC8174] when, and only when, they appear in all 131 capitals, as shown here. 133 This specification uses the terms "access token", "authorization 134 code", "authorization code grant", "authorization server", "resource 135 server", "authorization response", "grant type", and "client" defined 136 by the OAuth 2.0 Authorization Framework [RFC6749] and the term 137 "issuer identifier" defined by OAuth 2.0 Authorization Server 138 Metadata [RFC8414]. 140 2. Response Parameter "iss" 142 In authorization responses to the client, including error responses, 143 an authorization server supporting this specification MUST indicate 144 its identity by including the "iss" parameter in the response. 146 The "iss" parameter value is the issuer identifier of the 147 authorization server which created the authorization response, as 148 defined in [RFC8414]. Its value MUST be a URL that uses the "https" 149 scheme without any query or fragment components. If the 150 authorization server provides metadata as defined in [RFC8414], the 151 value of the parameter "iss" MUST be identical to the authorization 152 server metadata value "issuer". 154 2.1. Example Authorization Response 156 The following example shows an authorization response from the 157 authorization server whose issuer identifier is 158 "https://honest.as.example" (extra line breaks and indentation are 159 for display purposes only): 161 HTTP/1.1 302 Found 162 Location: https://client.example/cb? 163 code=x1848ZT64p4IirMPT0R-X3141MFPTuBX-VFL_cvaplMH58 164 &state=ZWVlNDBlYzA1NjdkMDNhYjg3ZjUxZjAyNGQzMTM2NzI 165 &iss=https%3A%2F%2Fhonest.as.example 167 2.2. Example Error Response 169 The following example shows an error response from the same 170 authorization server (extra line breaks and indentation are for 171 display purposes only): 173 HTTP/1.1 302 Found 174 Location: https://client.example/cb? 175 error=access_denied 176 &state=ZWVlNDBlYzA1NjdkMDNhYjg3ZjUxZjAyNGQzMTM2NzI 177 &iss=https%3A%2F%2Fhonest.as.example 179 2.3. Providing the Issuer Identifier "iss" 181 Authorization servers supporting this specification MUST provide 182 their issuer identifier to enable clients to validate the "iss" 183 parameter effectively. 185 For authorization servers publishing metadata according to [RFC8414], 186 the following rules apply: 188 * The issuer identifier included in the server's metadata value 189 "issuer" MUST be identical to the "iss" parameter's value. 191 * The server MUST indicate its support for the "iss" parameter by 192 setting the metadata parameter 193 "authorization_response_iss_parameter_supported", defined in 194 Section 3, to "true". 196 Authorization servers MAY additionally provide the issuer identifier 197 to clients by any other mechanism which is outside of the scope of 198 this specification. 200 2.4. Validation of the Issuer Identifier "iss" 202 Clients that support this specification MUST extract the value of the 203 "iss" parameter from authorization responses they receive if the 204 parameter is present. Clients MUST compare the extracted and URL- 205 decoded value to the issuer identifier of the authorization server 206 where the authorization request was sent to. This comparison MUST 207 use simple string comparison as defined in Section 6.2.1. of 208 [RFC3986]. If the value does not match the expected issuer 209 identifier, clients MUST reject the authorization response and MUST 210 NOT proceed with the authorization grant. For error responses, 211 clients MUST NOT assume that the error originates from the intended 212 authorization server. 214 More precisely, clients that interact with authorization servers 215 supporting OAuth metadata [RFC8414] MUST compare the "iss" parameter 216 value to the "issuer" value in the server's metadata document. If 217 OAuth metadata is not used, clients MUST use deployment-specific 218 ways, for example a static configuration, to decide if the returned 219 "iss" value is the expected value in the current flow (see also 220 Section 4). 222 If clients interact with both authorization servers supporting this 223 specification and authorization servers not supporting this 224 specification, clients SHOULD store the information which 225 authorization server supports the "iss" parameter. Clients MUST 226 reject authorization responses without the "iss" parameter from 227 authorization servers which do support the parameter according to the 228 client's configuration. 230 In general, clients that support this specification MAY accept 231 authorization responses that do not contain the "iss" parameter or 232 reject them and exclusively support authorization servers which 233 provide the "iss" parameter in the authorization response. This 234 decision is individual for every scenario and it is not in the scope 235 of this specification. 237 In OpenID Connect [OIDC.Core] flows where an ID Token is returned 238 from the authorization endpoint, the value in the "iss" parameter 239 MUST always be identical to the "iss" claim in the ID Token. 241 Section 4.1.2. of [RFC6479] already mandates that clients that do not 242 support this specification MUST ignore the unrecognized "iss" 243 parameter. 245 Note: The "JWT Secured Authorization Response Mode for OAuth 2.0 246 (JARM)" [JARM] defines a mechanism that conveys all authorization 247 response parameters in a JWT. This JWT contains an "iss" claim that 248 provides the same protection if it is validated as described in 249 Section 2.4. Therefore, an additional "iss" parameter outside the 250 JWT is not necessary when JARM is used. 252 3. Authorization Server Metadata 254 The following parameter for the authorization server metadata 255 [RFC8414] is introduced to signal the authorization server's support 256 for this specification: 258 "authorization_response_iss_parameter_supported" Boolean parameter 259 indicating whether the authorization server provides the "iss" 260 parameter in the authorization response as defined in Section 2. 261 If omitted, the default value is false. 263 4. Security Considerations 265 The authorization response parameter "iss" defined in this 266 specification serves as a countermeasure to mix-up attacks described 267 in Section 4.4. of the OAuth Security Best Current Practices 268 [I-D.ietf-oauth-security-topics] and in detail in "On the security of 269 modern Single Sign-On Protocols: Second-Order Vulnerabilities in 270 OpenID Connect" [arXiv.1508.04324] and "A Comprehensive Formal 271 Security Analysis of OAuth 2.0" [arXiv.1601.01229]. The latter 272 provides a formal proof of the effectiveness of the countermeasure. 274 Clients MUST validate the "iss" parameter precisely as described in 275 Section 2.4 and MUST NOT allow multiple authorization servers to use 276 the same issuer identifier. In particular, when authorization server 277 details can be manually configured in the client, the client MUST 278 ensure that the accepted "iss" values are unique for each 279 authorization server. 281 The "iss" parameter enables a client to decide if an authorization 282 server "expects" to be used in an OAuth flow together with a certain 283 token endpoint and potentially other endpoints, like the userinfo 284 endpoint ([OIDC.Core]). When OAuth metadata is used, the "iss" 285 parameter identifies the issuer and therefore the respective OAuth 286 metadata document which points to the other endpoints. When OAuth 287 metadata is not used, the client can use, for example, a statically 288 configured expected "iss" value for each configured authorization 289 server. 291 The issuer identifier contained in the authorization response is not 292 cryptographically protected against tampering. In general, 293 mechanisms such as JWTs (as specified in JARM [JARM]) could be used 294 to protect the integrity of the authorization response. However, in 295 mix-up attacks, the client generally receives the authorization 296 response from an uncompromised authorization server. If an attacker 297 can tamper this authorization response before it is received by the 298 client, the attacker would also have direct access to the 299 authorization code. The attacker does not need to execute a mix-up 300 attack to steal the authorization code. Therefore, integrity 301 protection for the authorization response is not necessary to defend 302 against mix-up attacks. 304 There are also alternative countermeasures to mix-up attacks. When 305 an authorization response already includes an authorization server's 306 issuer identifier by other means, and this identifier is checked as 307 laid out in Section 2.4, the use and verification of the "iss" 308 parameter is not necessary and MAY be omitted. This is the case when 309 OpenID Connect response types that return an ID token from the 310 authorization endpoint (e.g., "response_type=code id_token") or JARM 311 response mode are used, for example. However, if a client receives 312 an authorization response that contains multiple issuer identifiers, 313 the client MUST reject the response if these issuer identifiers do 314 not match. The details of alternative countermeasures are outside of 315 the scope of this specification. 317 Mix-up attacks are only relevant to clients that interact with 318 multiple authorization servers. However, clients interacting with 319 only one authorization server might add support for a second 320 authorization server in the future. By supporting multiple 321 authorization servers they become vulnerable to mix-up attacks and 322 need to apply countermeasures. 324 5. IANA Considerations 326 5.1. OAuth Authorization Server Metadata 328 This specification requests registration of the following values in 329 the IANA "OAuth Authorization Server Metadata" registry of 330 [IANA.OAuth.Parameters] established by [RFC8414]. 332 Metadata Name: "authorization_response_iss_parameter_supported" 333 Metadata Description: Boolean value indicating whether the 334 authorization server provides the "iss" parameter in the 335 authorization response. 336 Change Controller: IESG 337 Specification Document(s): Section 3 of [[ this document ]] 339 5.2. OAuth Parameters Registration 341 This specification requests registration of the following values in 342 the IANA "OAuth Parameters" registry of [IANA.OAuth.Parameters] 343 established by [RFC6749]. 345 Parameter name: "iss" 346 Parameter usage location: authorization response 347 Change Controller: IESG 348 Specification Document(s): Section 2 of [[ this document ]] 350 6. Acknowledgements 352 TBD 354 7. Normative References 356 [RFC6479] Zhang, X. and T. Tsou, "IPsec Anti-Replay Algorithm 357 without Bit Shifting", RFC 6479, DOI 10.17487/RFC6479, 358 January 2012, . 360 [I-D.ietf-oauth-security-topics] 361 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 362 "OAuth 2.0 Security Best Current Practice", Work in 363 Progress, Internet-Draft, draft-ietf-oauth-security- 364 topics-18, 13 April 2021, . 367 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 368 Requirement Levels", BCP 14, RFC 2119, 369 DOI 10.17487/RFC2119, March 1997, 370 . 372 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 373 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 374 May 2017, . 376 [IANA.OAuth.Parameters] 377 IANA, "OAuth Parameters", 378 . 380 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 381 RFC 6749, DOI 10.17487/RFC6749, October 2012, 382 . 384 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 385 Authorization Server Metadata", RFC 8414, 386 DOI 10.17487/RFC8414, June 2018, 387 . 389 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 390 Resource Identifier (URI): Generic Syntax", STD 66, 391 RFC 3986, DOI 10.17487/RFC3986, January 2005, 392 . 394 8. Informative References 396 [arXiv.1601.01229] 397 Fett, D., Kuesters, R., and G. Schmitz, "A Comprehensive 398 Formal Security Analysis of OAuth 2.0", 6 January 2016, 399 . 401 [OIDC.Core] 402 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 403 C. Mortimore, "OpenID Connect Core 1.0 incorporating 404 errata set 1", 8 November 2014, 405 . 407 [JARM] Lodderstedt, T. and B. Campbell, "Financial-grade API: JWT 408 Secured Authorization Response Mode for OAuth 2.0 (JARM)", 409 17 October 2018, 410 . 412 [arXiv.1508.04324] 413 Mainka, C., Mladenov, V., and J. Schwenk, "On the security 414 of modern Single Sign-On Protocols: Second-Order 415 Vulnerabilities in OpenID Connect", 18 August 2015, 416 . 418 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 419 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 420 RFC 7591, DOI 10.17487/RFC7591, July 2015, 421 . 423 Appendix A. Document History 425 [[ To be removed from the final specification ]] 427 -01 [[ Working Group Draft ]] 428 * Incorporated WG feedback 429 * Changed title of the draft to make it shorter 430 * Clarified mix-up attacks in introduction 431 * Improved note on JARM in validation section 433 -00 [[ Working Group Draft ]] 434 * Working group draft 436 -02 437 * Incorporated WG feedback 438 * Clarifications for unique issuer identifier 439 * Clarifications when multiple issuer identifier could be present 440 * Added note that iss parameter MUST NOT be used with JARM 441 * Added note on error responses and example for error response 442 * Editorial changes 444 -01 446 * Incorporated first WG feedback 447 * Clarifications for use with OIDC 448 * Added note that clients supporting just one AS are not vulnerable 449 * Renamed metadata parameter 450 * Various editorial changes 452 -00 454 * initial draft 456 Authors' Addresses 458 Karsten Meyer zu Selhausen 459 Hackmanit 461 Email: karsten.meyerzuselhausen@hackmanit.de 463 Daniel Fett 464 yes.com 466 Email: mail@danielfett.de