idnits 2.17.00 (12 Aug 2021) /tmp/idnits43012/draft-ietf-oauth-distributed-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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 34 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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (October 19, 2018) is 1310 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'MTLS' == Outdated reference: draft-ietf-oauth-discovery has been published as RFC 8414 ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group D. Hardt 3 Internet-Draft Amazon 4 Intended status: Standards Track B. Campbell 5 Expires: April 22, 2019 Ping Identity 6 N. Sakimura 7 NRI 8 October 19, 2018 10 Distributed OAuth 11 draft-ietf-oauth-distributed-00 13 Abstract 15 The Distributed OAuth profile enables an OAuth client to discover 16 what authorization server or servers may be used to obtain access 17 tokens for a given resource, and what parameter values to provide in 18 the access token request. 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 April 22, 2019. 37 Copyright Notice 39 Copyright (c) 2018 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 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 1. Introduction 54 In [RFC6749], there is a single resource server and authorization 55 server. In more complex and distributed systems, a clients may 56 access many different resource servers, which have different 57 authorization servers managing access. For example, a client may be 58 accessing two different resources that provides similar 59 functionality, but each is in a different geopolitical region, which 60 requires authorization from authorization servers located in each 61 geopolitical region. 63 A priori knowledge by the client of the relationships between 64 resource servers and authorizations servers is not practical as the 65 number of resource servers and authorization servers scales up. The 66 client needs to discover on-demand which authorization server to 67 request authorization for a given resource, and what parameters to 68 pass. Being able to discover how to access a protected resource also 69 enables more flexible software development as changes to the scopes, 70 realms and authorization servers can happen dynamically with no 71 change to client code. 73 1.1. Notational Conventions 75 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 76 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 77 and "OPTIONAL" are to be interpreted as described in BCP 14, 78 [RFC2119]. 80 1.2. Terminology 82 Issuer: the party issuing the access token, also known as the 83 authorization server. 85 All other terms are as defined in [RFC6749] and [RFC6750] 87 1.3. Protocol Overview 89 Figure 1 shows an abstract flow of distributed OAuth. 91 +--------+ +---------------+ 92 | |--(A)-- Discovery Request ---->| Resource | 93 | | | Server | 94 | |<-(B)-- Discovery Response ----| | 95 | | +---------------+ 96 | | 97 | | (client obtains authorization grant) 98 | | 99 | | +---------------+ 100 | |--(C)- Authorization Request ->| Authorization | 101 | Client | | Server | 102 | |<-(D)----- Access Token -------| | 103 | | +---------------+ 104 | | 105 | | +---------------+ 106 | |--(E)----- Access Token ------>| Resource | 107 | | | Server | 108 | |<-(F)--- Protected Resource ---| | 109 +--------+ +---------------+ 111 Figure 1: Abstract Protocol Flow 113 There are three steps where there are changes from the OAuth flow: 115 1) A discovery request (A) and discovery response (B) where the 116 client discovers what is required to make an authenticated request. 117 The client makes a request to the protected resource without 118 supplying the Authorization header, or supplying an invalid access 119 token. The resource server responds with a HTTP 401 response code 120 and links of relation types "resource_uri" and the 121 "oauth_server_metadata_uri". The client confirms the "host" value 122 from the TLS connection is contained in the resource URI, and fetches 123 each OAuth Server Metadata URI and per [OASM] discovers one or more 124 authorization server end point URIs. 126 The client then obtains an authorization grant per one of the grant 127 types in [RFC6749] section 4. 129 2) An authorization request (C) to an authorization server and 130 includes the "resource_uri" link. The authorization servers provides 131 an access token that is associated to the "resource_uri" value. 133 3) An authenticated request (E) to the resource server that confirms 134 the "resource_uri" linked to the access token matches expected value. 136 2. Authorization Server Discovery 138 Figure 1, step (A) 140 To access a protected resource, the client needs to learn the 141 authorization servers or issuers that can issue access tokens that 142 are acceptable to the protected resource. There may be one or more 143 issuers that can issue access tokens for the protected resource. To 144 discover the issuers, the client attempts to make a call to the 145 protected resource URI as defined in [RFC6750] section 2.1, except 146 with an invalid access token or no HTTP "Authorization" request 147 header field. The client notes the hostname of the protected 148 resource that was confirmed by the TLS connection, and saves it as 149 the "host" attribute. 151 Figure 1, step (B) 153 The resource server responds with the "WWW-Authenticate" HTTP header 154 that includes the "error" attribute with a value of "invalid_token" 155 and MAY also include the "scope" and "realm" attribute per [RFC6750] 156 section 3, and a "Link" HTTP Header per [RFC8288] that MUST include 157 one link of relation type "resource_uri" and one or more links of 158 type "oauth_server_metadata_uri". 160 For example (with extra spaces and line breaks for display purposes 161 only): 163 HTTP/1.1 401 Unauthorized 164 WWW-Authenticate: Bearer realm="example_realm", 165 scope="example_scope", 166 error="invalid_token" 167 Link: ; rel="resource_uri", 168 ; rel="oauth_server_metadata_uri" 170 The client MUST confirm the host portion of the resource URI, as 171 specified in the "resource_uri" link, contains the "host" attribute 172 obtained from the TLS connection in step (A). The client MUST 173 confirm the resource URI is contained in the protected resource URI 174 where access was attempted. The client then retrieves one or more of 175 the OAuth Server Metadata URIs to learn how to interact with the 176 associated authorization server per [OASM] and create a list of one 177 or more authorization server token endpoint URLs. 179 3. Authorization Grant 181 The client obtains an authorization grant per any of the mechanisms 182 in [RFC6749] section 4. 184 4. Access Token Request 186 Figure 1, step (C) 188 The client makes an access token request to the authorization server 189 token endpoint URL, or if more than URL is available, a randomly 190 selected URL from the list. If the client is unable to connect to 191 the URL, then the client MAY try to connect to another URL from the 192 list. 194 The client SHOULD authenticate to the issuer using a proof of 195 possession mechanism such as mutual TLS or a signed token containing 196 the issuer as the audience. 198 Depending on the authorization grant mechanism used per [RFC6749] 199 section 4, the client makes the access token request and MUST include 200 "resource" as an additional parameter with the value of the resource 201 URI. For example, if using the [RFC6749] section 4.4, Client 202 Credentials Grant, the request would be (with extra spaces and line 203 breaks for display purposes only): 205 POST /token HTTP/1.1 206 Host: issuer.example.com 207 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 208 Content-Type: application/x-www-form-urlencoded 210 grant_type=client_credentials 211 &scope=example_scope 212 &resource=https%3A%2F%2Fapi.example.com%2Fresource 214 Figure 1, step (D) 216 The authorization server MUST associate the resource URI with the 217 issued access token in a way that can be accessed and verified by the 218 protected resource. For JWT [RFC7519] formatted access tokens, the 219 "aud" claim MUST be used to convey the resource URI. When Token 220 Introspection [RFC7662] is used, the introspection response MUST 221 containe the "aud" member with the resource URI as its value. 223 5. Accessing Protected Resource 225 Figure 1, step (E) 227 The client accesses the protected resource per [RFC6750] section 2.1. 228 The Distributed OAuth Profile MUST only use the authorization request 229 header field for passing the access token. 231 Figure 1, step (F) 232 The protected resource MUST verify the resource URI in or referenced 233 by the access token is the protected resource's resource URI. 235 6. Security Considerations 237 Three new threats emerge when the client is dynamically discovering 238 the authorization server and the request attributes: access token 239 reuse, resource server impersonation, and malicious issuer. 241 6.1. Access Token Reuse 243 A malicious resource server impersonates the client and reuses the 244 access token provided by the client to the malicious resource server 245 with another resource server. 247 This is mitigated by constraining the access token to a specific 248 audience, or to a specific client. 250 Audience restricting the access token is described in this document 251 where the the resource URI is associated to the access token by 252 inclusion or reference, so that only access tokens with the correct 253 resource URI are accepted at a resource server. 255 Sender constraining the access token can be done through [MTLS], 256 [OATB], or any other mechanism that the resource can use to associate 257 the access token with the client. 259 6.2. Resource Server Impersonation 261 A malicious resource server tells a client to obtain an access token 262 that can be used at a different resource server. When the client 263 presents the access token, the malicious resource server uses the 264 access token to access another resource server. 266 This is mitigated by the client obtaining the "host" value from the 267 TLS certificate of the resource server, and the client verifying the 268 "host" value is contained in the host portion of the resource URI, 269 rather than the resource URI being any value declared by the resource 270 server. 272 6.3. Malicious Issuer 274 A malicious resource server could redirect the client to a malicious 275 issuer, or the issuer may be malicious. The malicious issuer may 276 replay the client credentials with a valid issuer and obtain a valid 277 access token for a protected resource. 279 This attack is mitigated by the client using a proof of possession 280 authentication mechanism with the issuer such as [MTLS] or a signed 281 token containing the issuer as the audience. 283 7. IANA Considerations 285 Pursuant to [RFC5988], the following link type registrations will be 286 registered by mail to link-relations@ietf.org. 288 o Relation Name: oauth_server_metadata_uri 290 o Description: An OAuth 2.0 Server Metadata URI. 292 o Reference: This specification 294 o Relation Name: resource_uri 296 o Description: An OAuth 2.0 Resource Endpoint specified in [RFC6750] 297 section 3.2. 299 o Reference: This specification 301 8. Acknowledgements 303 TBD. 305 9. Normative References 307 [MTLS] Jones, M., Campbell, B., Bradley, J., and W. Denniss, 308 "OAuth 2.0 Mutual TLS Client Authentication and 309 Certificate Bound Access Tokens", October 2018, 310 . 312 [OASM] Jones, M., Campbell, B., and J. Bradley, "OAuth 2.0 313 Authorization Server Metadata", October 2018, 314 . 317 [OATB] Campbell, B., Bradley, J., Sakimora, N., and T. 318 Lodderstedt, "OAuth 2.0 Token Binding", October 2018, 319 . 322 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 323 Requirement Levels", BCP 14, RFC 2119, 324 DOI 10.17487/RFC2119, March 1997, 325 . 327 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 328 DOI 10.17487/RFC5988, October 2010, 329 . 331 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 332 RFC 6749, DOI 10.17487/RFC6749, October 2012, 333 . 335 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 336 Framework: Bearer Token Usage", RFC 6750, 337 DOI 10.17487/RFC6750, October 2012, 338 . 340 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 341 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 342 . 344 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 345 RFC 7662, DOI 10.17487/RFC7662, October 2015, 346 . 348 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 349 DOI 10.17487/RFC8288, October 2017, 350 . 352 Appendix A. Document History 354 [[ to be removed by the RFC Editor before publication as an RFC ]] 356 draft-ietf-oauth-distributed-00 358 o Initial version adopted from draft-hardt-oauth-distributed-02 360 Authors' Addresses 362 Dick Hardt 363 Amazon 365 Email: dick.hardt@gmail.com 367 Brian Campbell 368 Ping Identity 370 Email: brian.d.campbell@gmail.com 371 Nat Sakimura 372 NRI 374 Email: n-sakimura@nri.co.jp