idnits 2.17.1 draft-ietf-oauth-distributed-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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 2 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 2015 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' ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) Summary: 3 errors (**), 0 flaws (~~), 2 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-01 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 per 123 [RFC6125] section 6, and fetches each OAuth Server Metadata URI and 124 per [OASM] discovers one or more 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 as a resource parameter per [OARI] 131 2.1. The authorization servers provides an access token that is 132 associated to the "resource_uri" value. 134 3) An authenticated request (E) to the resource server that confirms 135 the "resource_uri" linked to the access token matches expected value. 137 2. Authorization Server Discovery 139 Figure 1, step (A) 141 To access a protected resource, the client needs to learn the 142 authorization servers or issuers that can issue access tokens that 143 are acceptable to the protected resource. There may be one or more 144 issuers that can issue access tokens for the protected resource. To 145 discover the issuers, the client attempts to make a call to the 146 protected resource URI as defined in [RFC6750] section 2.1, except 147 with an invalid access token or no HTTP "Authorization" request 148 header field. The client notes the hostname of the protected 149 resource that was confirmed by the TLS connection per [RFC6125] 150 section 6, and saves it as the "host" attribute. 152 Figure 1, step (B) 154 The resource server responds with the "WWW-Authenticate" HTTP header 155 that includes the "error" attribute with a value of "invalid_token" 156 and MAY also include the "scope" and "realm" attribute per [RFC6750] 157 section 3, and a "Link" HTTP Header per [RFC8288] that MUST include 158 one link of relation type "resource_uri" and one or more links of 159 type "oauth_server_metadata_uri". 161 For example (with extra spaces and line breaks for display purposes 162 only): 164 HTTP/1.1 401 Unauthorized 165 WWW-Authenticate: Bearer realm="example_realm", 166 scope="example_scope", 167 error="invalid_token" 168 Link: ; 169 rel="resource_uri", 170 ; 171 rel="oauth_server_metadata_uri" 173 The client MUST confirm the host portion of the resource URI per 174 [RFC6125] section 6, as specified in the "resource_uri" link, 175 contains the "host" attribute obtained from the TLS connection in 176 step (A). The client MUST confirm the resource URI is contained in 177 the protected resource URI where access was attempted. The client 178 then retrieves one or more of the OAuth Server Metadata URIs to learn 179 how to interact with the associated authorization server per [OASM] 180 and create a list of one or more authorization server token endpoint 181 URLs. 183 3. Authorization Grant 185 The client obtains an authorization grant per any of the mechanisms 186 in [RFC6749] section 4. 188 4. Access Token Request 190 Figure 1, step (C) 192 The client makes an access token request to the authorization server 193 token endpoint URL, or if more than URL is available, a randomly 194 selected URL from the list. If the client is unable to connect to 195 the URL, then the client MAY try to connect to another URL from the 196 list. 198 The client SHOULD authenticate to the issuer using a proof of 199 possession mechanism such as mutual TLS or a signed token containing 200 the issuer as the audience. 202 Depending on the authorization grant mechanism used per [RFC6749] 203 section 4, the client makes the access token request and MUST include 204 "resource" as an additional parameter with the value of the resource 205 URI. For example, if using the [RFC6749] section 4.4, Client 206 Credentials Grant, the request would be (with extra spaces and line 207 breaks for display purposes only): 209 POST /token HTTP/1.1 210 Host: issuer.example.com 211 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 212 Content-Type: application/x-www-form-urlencoded 214 grant_type=client_credentials 215 &scope=example_scope 216 &resource=https%3A%2F%2Fapi.example.com%2Fresource 218 Figure 1, step (D) 220 The authorization server MUST associate the resource URI with the 221 issued access token in a way that can be accessed and verified by the 222 protected resource. For JWT [RFC7519] formatted access tokens, the 223 "aud" claim MUST be used to convey the resource URI. When Token 224 Introspection [RFC7662] is used, the introspection response MUST 225 containe the "aud" member with the resource URI as its value. 227 5. Accessing Protected Resource 229 Figure 1, step (E) 231 The client accesses the protected resource per [RFC6750] section 2.1. 232 The Distributed OAuth Profile MUST only use the authorization request 233 header field for passing the access token. 235 Figure 1, step (F) 237 The protected resource MUST verify the resource URI in or referenced 238 by the access token is the protected resource's resource URI. 240 6. Security Considerations 242 Three new threats emerge when the client is dynamically discovering 243 the authorization server and the request attributes: access token 244 reuse, resource server impersonation, and malicious issuer. 246 6.1. Access Token Reuse 248 A malicious resource server impersonates the client and reuses the 249 access token provided by the client to the malicious resource server 250 with another resource server. 252 This is mitigated by constraining the access token to a specific 253 audience, or to a specific client. 255 Audience restricting the access token is described in this document 256 where the resource URI is associated to the access token by inclusion 257 or reference, so that only access tokens with the correct resource 258 URI are accepted at a resource server. 260 Sender constraining the access token can be done through [MTLS], 261 [OATB], or any other mechanism that the resource can use to associate 262 the access token with the client. 264 6.2. Resource Server Impersonation 266 A malicious resource server tells a client to obtain an access token 267 that can be used at a different resource server. When the client 268 presents the access token, the malicious resource server uses the 269 access token to access another resource server. 271 This is mitigated by the client obtaining the "host" value from the 272 TLS certificate of the resource server, and the client verifying the 273 "host" value is contained in the host portion of the resource URI, 274 rather than the resource URI being any value declared by the resource 275 server. 277 6.3. Malicious Issuer 279 A malicious resource server could redirect the client to a malicious 280 issuer, or the issuer may be malicious. The malicious issuer may 281 replay the client credentials with a valid issuer and obtain a valid 282 access token for a protected resource. 284 This attack is mitigated by the client using a proof of possession 285 authentication mechanism with the issuer such as [MTLS] or a signed 286 token containing the issuer as the audience. 288 7. IANA Considerations 290 Pursuant to [RFC5988], the following link type registrations will be 291 registered by mail to link-relations@ietf.org. 293 o Relation Name: oauth_server_metadata_uri 295 o Description: An OAuth 2.0 Server Metadata URI. 297 o Reference: This specification 299 o Relation Name: resource_uri 301 o Description: An OAuth 2.0 Resource Endpoint specified in [RFC6750] 302 section 3.2. 304 o Reference: This specification 306 8. Acknowledgements 308 TBD. 310 9. Normative References 312 [MTLS] Jones, M., Campbell, B., Bradley, J., and W. Denniss, 313 "OAuth 2.0 Mutual TLS Client Authentication and 314 Certificate Bound Access Tokens", October 2018, 315 . 317 [OARI] Campbell, B. and J. Bradley, "OAuth Resource Indicators", 318 October 2018, . 321 [OASM] Jones, M., Campbell, B., and J. Bradley, "OAuth 2.0 322 Authorization Server Metadata", October 2018, 323 . 326 [OATB] Jones, M., Campbell, B., Bradley, J., and W. Denniss, 327 "OAuth 2.0 Token Binding", October 2018, 328 . 331 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 332 Requirement Levels", BCP 14, RFC 2119, 333 DOI 10.17487/RFC2119, March 1997, 334 . 336 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 337 DOI 10.17487/RFC5988, October 2010, 338 . 340 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 341 Verification of Domain-Based Application Service Identity 342 within Internet Public Key Infrastructure Using X.509 343 (PKIX) Certificates in the Context of Transport Layer 344 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 345 2011, . 347 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 348 RFC 6749, DOI 10.17487/RFC6749, October 2012, 349 . 351 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 352 Framework: Bearer Token Usage", RFC 6750, 353 DOI 10.17487/RFC6750, October 2012, 354 . 356 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 357 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 358 . 360 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 361 RFC 7662, DOI 10.17487/RFC7662, October 2015, 362 . 364 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 365 DOI 10.17487/RFC8288, October 2017, 366 . 368 Appendix A. Document History 370 [[ to be removed by the RFC Editor before publication as an RFC ]] 372 draft-ietf-oauth-distributed-01 374 o added reference to OAuth Resource Indicators draft 376 o added reference to RFC 6125 for matching host 378 draft-ietf-oauth-distributed-00 380 o Initial version adopted from draft-hardt-oauth-distributed-02 382 Authors' Addresses 384 Dick Hardt 385 Amazon 387 Email: dick.hardt@gmail.com 389 Brian Campbell 390 Ping Identity 392 Email: brian.d.campbell@gmail.com 394 Nat Sakimura 395 NRI 397 Email: n-sakimura@nri.co.jp