idnits 2.17.1 draft-ietf-oauth-dyn-reg-metadata-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 : ---------------------------------------------------------------------------- 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 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 (February 6, 2014) is 3732 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: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group J. Richer 3 Internet-Draft The MITRE Corporation 4 Intended status: Standards Track M. Jones 5 Expires: August 10, 2014 Microsoft 6 J. Bradley 7 Ping Identity 8 M. Machulak 9 Newcastle University 10 P. Hunt 11 Oracle Corporation 12 February 6, 2014 14 OAuth 2.0 Dynamic Client Registration Metadata 15 draft-ietf-oauth-dyn-reg-metadata-00 17 Abstract 19 This specification defines client metadata values used to describe 20 attributes of dynamically registered OAuth 2.0 clients. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on August 10, 2014. 39 Copyright Notice 41 Copyright (c) 2014 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 58 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 3 60 2.1. Human Readable Client Metadata . . . . . . . . . . . . . . 5 61 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 62 3.1. OAuth Registration Client Metadata Registration . . . . . 6 63 3.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 6 64 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 65 5. Normative References . . . . . . . . . . . . . . . . . . . . . 8 66 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 9 67 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . . 9 68 Appendix C. Document History . . . . . . . . . . . . . . . . . . 9 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 71 1. Introduction 73 In order for an OAuth 2.0 client to utilize an OAuth 2.0 74 authorization server, the client needs specific information to 75 interact with the server, including an OAuth 2.0 Client ID to use at 76 that server. The OAuth 2.0 Dynamic Client Registration Core Protocol 77 [OAuth.Registration] specification describes how an OAuth 2.0 client 78 can be dynamically registered with an authorization server to obtain 79 this information and how metadata about the client can be registered 80 with the server. 82 This specification extends the core registration specification by 83 defining a specific set of client metadata values that can be used to 84 describe additional attributes of dynamically registered OAuth 2.0 85 clients beyond those defined in the core registration specification. 87 1.1. Notational Conventions 89 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 90 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 91 document are to be interpreted as described in [RFC2119]. 93 Unless otherwise noted, all the protocol parameter names and values 94 are case sensitive. 96 1.2. Terminology 98 This specification uses the terms "Access Token", "Refresh Token", 99 "Authorization Code", "Authorization Grant", "Authorization Server", 100 "Authorization Endpoint", "Client", "Client Identifier", "Client 101 Secret", "Protected Resource", "Resource Owner", "Resource Server", 102 "Response Type", and "Token Endpoint" defined by OAuth 2.0 [RFC6749] 103 and the terms defined by the OAuth 2.0 Client Dynamic Registration 104 Core Protocol [OAuth.Registration]. 106 2. Client Metadata 108 Registering client metadata values with an authorization server may 109 be necessary or useful to facilitate usage of the authorization 110 server by the client. This specification extends the list of client 111 metadata values defined in OAuth 2.0 Client Dynamic Registration Core 112 Protocol [OAuth.Registration] with the following fields: 114 client_name Human-readable name of the client to be presented to the 115 user. If omitted, the authorization server MAY display the raw 116 "client_id" value to the user instead. It is RECOMMENDED that 117 clients always send this field. The value of this field MAY be 118 internationalized, as described in Section 2.1. 120 client_uri URL of the homepage of the client. If present, the 121 server SHOULD display this URL to the end user in a clickable 122 fashion. It is RECOMMENDED that clients always send this field. 123 The value of this field MUST point to a valid web page. The value 124 of this field MAY be internationalized, as described in 125 Section 2.1. 127 logo_uri URL that references a logo for the client. If present, the 128 server SHOULD display this image to the end user during approval. 129 The value of this field MUST point to a valid image file. The 130 value of this field MAY be internationalized, as described in 131 Section 2.1. 133 scope Space separated list of scope values (as described in OAuth 134 2.0 Section 3.3 [RFC6749]) that the client can use when requesting 135 access tokens. The semantics of values in this list is service 136 specific. If omitted, an authorization server MAY register a 137 Client with a default set of scopes. 139 contacts Array of email addresses for people responsible for this 140 client. The authorization server MAY make these addresses 141 available to end users for support requests for the client. An 142 authorization server MAY use these email addresses as identifiers 143 for an administrative page for this client. 145 tos_uri URL that points to a human-readable Terms of Service 146 document for the client. The Authorization Server SHOULD display 147 this URL to the end-user if it is given. The Terms of Service 148 usually describe a contractual relationship between the end-user 149 and the client that the end-user accepts when authorizing the 150 client. The value of this field MUST point to a valid web page. 151 The value of this field MAY be internationalized, as described in 152 Section 2.1. 154 policy_uri URL that points to a human-readable Policy document for 155 the client. The authorization server SHOULD display this URL to 156 the end-user if it is given. The policy usually describes how an 157 end-user's data will be used by the client. The value of this 158 field MUST point to a valid web page. The value of this field MAY 159 be internationalized, as described in Section 2.1. 161 jwks_uri URL for the Client's JSON Web Key Set [JWK] document 162 representing the client's public keys. The value of this field 163 MUST point to a valid JWK Set. These keys MAY be used for higher 164 level protocols that require signing or encryption. 166 software_id Identifier for the software that comprises a client. 167 Unlike "client_id", which is issued by the authorization server 168 and generally varies between instances, the "software_id" is 169 asserted by the client software and is intended to be shared 170 between all copies of the client software. The value for this 171 field MAY be a UUID [RFC4122]. The identifier SHOULD NOT change 172 when software version changes or when a new installation instance 173 is detected. Unless used as a claim in a signed software 174 statement, authorization servers MUST treat this field as self- 175 asserted by the client and MUST NOT make any trust decisions based 176 upon the value of this field alone. 178 software_version Version identifier for the software that comprises 179 a client. The value of this field is a string that is intended to 180 be compared using string equality matching. The value of the 181 "software_version" SHOULD change on any update to the client 182 software. Unless used as a claim in a signed software statement, 183 authorization servers MUST treat this field as self-asserted by 184 the client and MUST NOT make any trust decisions based upon the 185 value of this field alone. 187 2.1. Human Readable Client Metadata 189 Human-readable client metadata values and client metadata values that 190 reference human-readable values MAY be represented in multiple 191 languages and scripts. For example, the values of fields such as 192 "client_name", "tos_uri", "policy_uri", "logo_uri", and "client_uri" 193 might have multiple locale-specific values in some client 194 registrations. 196 To specify the languages and scripts, BCP47 [RFC5646] language tags 197 are added to client metadata member names, delimited by a # 198 character. Since JSON member names are case sensitive, it is 199 RECOMMENDED that language tag values used in Claim Names be spelled 200 using the character case with which they are registered in the IANA 201 Language Subtag Registry [IANA.Language]. In particular, normally 202 language names are spelled with lowercase characters, region names 203 are spelled with uppercase characters, and languages are spelled with 204 mixed case characters. However, since BCP47 language tag values are 205 case insensitive, implementations SHOULD interpret the language tag 206 values supplied in a case insensitive manner. Per the 207 recommendations in BCP47, language tag values used in metadata member 208 names should only be as specific as necessary. For instance, using 209 "fr" might be sufficient in many contexts, rather than "fr-CA" or 210 "fr-FR". 212 For example, a client could represent its name in English as 213 ""client_name#en": "My Client"" and its name in Japanese as 214 ""client_name#ja-Jpan-JP": 215 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D"" within the same 216 registration request. The authorization server MAY display any or 217 all of these names to the resource owner during the authorization 218 step, choosing which name to display based on system configuration, 219 user preferences or other factors. 221 If any human-readable field is sent without a language tag, parties 222 using it MUST NOT make any assumptions about the language, character 223 set, or script of the string value, and the string value MUST be used 224 as-is wherever it is presented in a user interface. To facilitate 225 interoperability, it is RECOMMENDED that clients and servers use a 226 human-readable field without any language tags in addition to any 227 language-specific fields, and it is RECOMMENDED that any human- 228 readable fields sent without language tags contain values suitable 229 for display on a wide variety of systems. 231 Implementer's Note: Many JSON libraries make it possible to reference 232 members of a JSON object as members of an object construct in the 233 native programming environment of the library. However, while the 234 "#" character is a valid character inside of a JSON object's member 235 names, it is not a valid character for use in an object member name 236 in many programming environments. Therefore, implementations will 237 need to use alternative access forms for these claims. For instance, 238 in JavaScript, if one parses the JSON as follows, "var j = 239 JSON.parse(json);", then the member "client_name#en-us" can be 240 accessed using the JavaScript syntax "j["client_name#en-us"]". 242 3. IANA Considerations 244 3.1. OAuth Registration Client Metadata Registration 246 This specification registers the Client Metadata values defined in 247 Section 2 in the IANA OAuth Registration Client Metadata registry 248 defined in [OAuth.Registration]. 250 3.1.1. Registry Contents 252 o Client Metadata Name: "client_name" 253 o Client Metadata Description: Human-readable name of the client to 254 be presented to the user 256 o Change Controller: IESG 257 o Specification Document(s): [[ this document ]] 259 o Client Metadata Name: "client_uri" 260 o Client Metadata Description: URL of the homepage of the client 261 o Change Controller: IESG 262 o Specification Document(s): [[ this document ]] 264 o Client Metadata Name: "logo_uri" 265 o Client Metadata Description: URL that references a logo for the 266 client 267 o Change Controller: IESG 268 o Specification Document(s): [[ this document ]] 270 o Client Metadata Name: "scope" 271 o Client Metadata Description: Space separated list of scope values 272 o Change Controller: IESG 273 o Specification Document(s): [[ this document ]] 275 o Client Metadata Name: "contacts" 276 o Client Metadata Description: Array of email addresses for people 277 responsible for this client 278 o Change Controller: IESG 279 o Specification document(s): [[ this document ]] 281 o Client Metadata Name: "tos_uri" 282 o Client Metadata Description: URL that points to a human-readable 283 Terms of Service document for the client 284 o Change Controller: IESG 285 o Specification Document(s): [[ this document ]] 287 o Client Metadata Name: "policy_uri" 288 o Client Metadata Description: URL that points to a human-readable 289 Policy document for the client 290 o Change Controller: IESG 291 o Specification Document(s): [[ this document ]] 293 o Client Metadata Name: "jwks_uri" 294 o Client Metadata Description: URL for the Client's JSON Web Key Set 295 [JWK] document representing the client's public keys 296 o Change Controller: IESG 297 o Specification Document(s): [[ this document ]] 299 o Client Metadata Name: "software_id" 300 o Client Metadata Description: Identifier for the software that 301 comprises a client 303 o Change Controller: IESG 304 o Specification Document(s): [[ this document ]] 306 o Client Metadata Name: "software_version" 307 o Client Metadata Description: Version identifier for the software 308 that comprises a client 309 o Change Controller: IESG 310 o Specification Document(s): [[ this document ]] 312 4. Security Considerations 314 Unless used as a claim in a signed software statement, the 315 authorization server MUST treat all client metadata as self-asserted. 316 For instance, a rogue client might use the name and logo for the 317 legitimate client which it is trying to impersonate. Additionally, a 318 rogue client might try to use the software identifier or software 319 version of a legitimate client to attempt to associate itself on the 320 authorization server instances of the legitimate client. To 321 counteract this, an authorization server needs to take steps to 322 mitigate this phishing risk by looking at the entire registration 323 request and client configuration. For instance, an authorization 324 server could warn if the domain/site of the logo doesn't match the 325 domain/site of redirect URIs. An authorization server could also 326 refuse registration from a known software identifier that is 327 requesting different redirect URIs or a different client homepage 328 URI. An authorization server can also present warning messages to 329 end users about dynamically registered clients in all cases, 330 especially if such clients have been recently registered or have not 331 been trusted by any users at the authorization server before. 333 In a situation where the authorization server is supporting open 334 client registration, it must be extremely careful with any URL 335 provided by the client that will be displayed to the user (e.g. 336 "logo_uri", "tos_uri", "client_uri", and "policy_uri"). For 337 instance, a rogue client could specify a registration request with a 338 reference to a drive-by download in the "policy_uri". The 339 authorization server SHOULD check to see if the "logo_uri", 340 "tos_uri", "client_uri", and "policy_uri" have the same host and 341 scheme as the those defined in the array of "redirect_uris" and that 342 all of these resolve to valid web pages. 344 5. Normative References 346 [IANA.Language] 347 Internet Assigned Numbers Authority (IANA), "Language 348 Subtag Registry", 2005. 350 [JWK] Jones, M., "JSON Web Key (JWK)", 351 draft-ietf-jose-json-web-key (work in progress), 352 January 2014. 354 [OAuth.Registration] 355 Richer, J., Jones, M., Bradley, J., Machulak, M., and P. 356 Hunt, "OAuth 2.0 Dynamic Client Registration Core 357 Protocol", draft-ietf-oauth-dyn-reg (work in progress), 358 February 2014. 360 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 361 Requirement Levels", BCP 14, RFC 2119, March 1997. 363 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 364 Unique IDentifier (UUID) URN Namespace", RFC 4122, 365 July 2005. 367 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 368 Languages", BCP 47, RFC 5646, September 2009. 370 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 371 RFC 6749, October 2012. 373 Appendix A. Acknowledgments 375 The authors thank the OAuth Working Group, the User-Managed Access 376 Working Group, and the OpenID Connect Working Group participants for 377 their input to this document. In particular, the following 378 individuals have been instrumental in their review and contribution 379 to various versions of this document: Amanda Anganes, Derek Atkins, 380 Tim Bray, Domenico Catalano, Donald Coffin, Vladimir Dzhuvinov, 381 George Fletcher, Thomas Hardjono, Phil Hunt, William Kim, Torsten 382 Lodderstedt, Eve Maler, Josh Mandel, Nov Matake, Tony Nadalin, Nat 383 Sakimura, Christian Scholz, and Hannes Tschofenig. 385 Appendix B. Open Issues 387 o Should some or all of the metadata values defined in this 388 specification be moved into draft-ietf-oauth-dyn-reg? 390 Appendix C. Document History 392 [[ to be removed by the RFC editor before publication as an RFC ]] 394 -00 395 o Created from draft-jones-oauth-dyn-reg-metadata-00. 397 Authors' Addresses 399 Justin Richer 400 The MITRE Corporation 402 Email: jricher@mitre.org 404 Michael B. Jones 405 Microsoft 407 Email: mbj@microsoft.com 408 URI: http://self-issued.info/ 410 John Bradley 411 Ping Identity 413 Email: ve7jtb@ve7jtb.com 415 Maciej Machulak 416 Newcastle University 418 Email: m.p.machulak@ncl.ac.uk 419 URI: http://ncl.ac.uk/ 421 Phil Hunt 422 Oracle Corporation 424 Email: phil.hunt@yahoo.com