idnits 2.17.1 draft-hardt-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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. 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 (November 14, 2017) is 2348 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) No issues found here. Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Hardt 3 Internet-Draft Amazon 4 Intended status: Standards Track November 14, 2017 5 Expires: May 18, 2018 7 Distributed OAuth 8 draft-hardt-oauth-distributed-00 10 Abstract 12 The OAuth client credentials grant The Distributed OAuth profile 13 enables an OAuth client using the client credentials grant to 14 discover what authorization server to use for a given resource 15 server, and what attribute values to provide in the access token 16 request. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on May 18, 2018. 35 Copyright Notice 37 Copyright (c) 2017 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 1. Introduction 52 In [RFC6749], there is a single resource server and authorization 53 server. In more complex and distributed systems, a clients may 54 access many different resource servers, which have different 55 authorization servers managing access. For example, a client may be 56 accessing two different resources that provides similar 57 funcationility, but each is in a different geopolitical region, which 58 requires authorization from authorization servers located in each 59 geopolitical region. 61 A priori knownledge by the client of the relationships between 62 resource servers and authorizations servers is not practical as the 63 number of resource servers and authorization servers scales up. The 64 client needs to discover on-demand which authorization server to 65 request authorization for a given resource, and what attributes to 66 pass. Being able to discover how to access a protected resource also 67 enables more flexible software development as changes to the scopes, 68 realms and authorization servers can happen dynamically with no 69 change to client code. 71 1.1. Notational Conventions 73 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 74 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 75 and "OPTIONAL" are to be interpreted as described in BCP 14, 76 [RFC2119]. 78 1.2. Terminology 80 Issuer: the party issuing the access token, also known as the 81 authorization server. 83 All other terms are as defined in [RFC6749] and [RFC6750] 85 1.3. Protocol Overview 87 Figure 1 shows an abstract flow of distributed OAuth. 89 +--------+ +---------------+ 90 | |--(A)-- Discovery Request ---->| Resource | 91 | | | Server | 92 | |<-(B)-- Discovery Response ----| | 93 | | +---------------+ 94 | | 95 | | +---------------+ 96 | |--(C)- Authorization Request ->| Authorization | 97 | Client | | Server | 98 | |<-(D)----- Access Token -------| | 99 | | +---------------+ 100 | | 101 | | +---------------+ 102 | |--(E)----- Access Token ------>| Resource | 103 | | | Server | 104 | |<-(F)--- Protected Resource ---| | 105 +--------+ +---------------+ 107 Figure 1: Abstract Protocol Flow 109 There are three steps where there are changes from the OAuth client 110 credential grant: 112 1) A discovery request (A) and discovery resopnse (B) where the 113 client discovers what is required to make an authenticated request. 114 The client makes a request to the protected resource without 115 supplying the Authorization header. The resource server responds 116 with a HTTP 401 response code and the "iss" attribute in the "WWW- 117 Authenticate" header. The client notes the "host" value from the TLS 119 2) An authorization request (C) to an authorization server listed in 120 the "iss" attribute and includes the "host" attribute. The 121 authorization servers provides an access token that includes the 122 "host" value. 124 3) An authenticated request (E) to the resource server that confirms 125 the "host" matches expected values. 127 2. Authorization Server Discovery 129 Figure 1, step (A) 131 To access a protected resource, the client needs to learn the 132 authorization servers or issuers that can issue access tokens that 133 are acceptable to the protected resource. There may be one or more 134 issuers that can issue access tokens for the protected resource. To 135 discover the issuers, the client makes an unauthenticated call to the 136 protected resource, with no HTTP "Authorization" request header field 137 as defined in [RFC6750] section 2.1. The client notes the hostname 138 of the protected resource that was confirmed by the TLS connection, 139 and saves it as the "host" attribute. 141 Figure 1, step (B) 143 The resource server responds with the "WWW-Authenticate" HTTP header 144 that MAY incldue the "scope" and "realm" attribute per [RFC6750] 145 section 3, and MUST include the "iss" attribute. The "iss" attribute 146 has one or more space delimited URLs. 148 For example (with extra line breaks for display purposes only): 150 HTTP/1.1 401 Unauthorized 151 WWW-Authenticate: Bearer realm="example_realm", 152 iss="http://issuer.example.com/token", 153 scope="example_scope", 154 error="invalid_token" 156 3. Access Token Request 158 Figure 1, step (C) 160 The client makes an access token request to the issuer URL specified 161 by the "iss" attribute, or if more than one value, a randomly 162 selected URL from the list. If the client is unable to connect to 163 the issuer, then the client MAY try to connect to another URL from 164 the list. 166 The client SHOULD authenticate to the issuer using a proof of 167 possession mechanism such as mutual TLS or a signed token containing 168 the issuer as the audience 170 The client makes the access token request per [RFC6749] section 4.4, 171 Client Credentials Grant and MUST include the "host" attribute, for 172 example (with extra line breaks for display purposes only): 174 POST /token HTTP/1.1 175 Host: issuer.example.com 176 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 177 Content-Type: application/x-www-form-urlencoded 179 grant_type=client_credentials 180 &scope="example scope" 181 &host=resource.example.com 182 &realm="example_realm" 184 Figure 1, step (D) 185 The authorization server returns an access token that MUST include 186 the "host" attribute or a reference that includes the "host" 187 attribute. 189 4. Accessing Protected Resource 191 Figure 1, step (E) 193 The client access the protected resource per [RFC6750] section 2.1. 194 The distributed oauth profile SHALL only use the authorization 195 request header field for passing the access token. 197 Figure 1, step (F) 199 The protected resource MUST verify the "host" attribute is the host 200 of the resource server the protected resource is hosted. 202 5. New Threats 204 THree new threats emerge when the client is dynamically discovering 205 the authorization server and the request attributes: access token 206 reuse, resource server impersonation, and malicious issuer. 208 5.1. Access Token Reuse 210 A malicious resource server impersonates the client and reuses the 211 access token provided by the client to the malicious resource server 212 with another resource server. 214 This is mitigated by inclusion of the "host" property in the acces 215 token, so that only the access token is only accepted at the intended 216 host. 218 5.2. Resource Server Impersonation 220 A malicious resource server tells a client to obtain an access token 221 that can be used at a different resource server. When the client 222 presents the acces token, the malicious resource server uses the 223 access token to access another resource server. 225 This is mitigated by the client obtaining the "host" value from the 226 TLS certificate rather than being declared by the resource server. 228 5.3. Malicious Issuer 230 A malicious resource server could redirect the client to a malicious 231 issuer, or the issuer may be malicious. The malicious issuer may 232 replay the client credentials with a valid issuer and obtain a valid 233 access token for a protected resource. 235 This attack is mitigated by the client using a proof of possion 236 authentication mechanism with the issuer such as mutual TLS or a 237 signed token containing the issuer as the audience. 239 6. IANA Considerations 241 TBD. 243 7. Acknowledgements 245 TBD. 247 8. Normative References 249 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 250 Requirement Levels", BCP 14, RFC 2119, 251 DOI 10.17487/RFC2119, March 1997, 252 . 254 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 255 RFC 6749, DOI 10.17487/RFC6749, October 2012, 256 . 258 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 259 Framework: Bearer Token Usage", RFC 6750, 260 DOI 10.17487/RFC6750, October 2012, 261 . 263 Appendix A. Document History 265 A.1. draft-hardt-oauth-distributed-00 267 o Initial version. 269 Author's Address 271 Dick Hardt 272 Amazon 274 Email: dick.hardt@gmail.com