idnits 2.17.1 draft-jones-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 (January 28, 2014) is 3740 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 1, 2014 Microsoft 6 J. Bradley 7 Ping Identity 8 M. Machulak 9 Newcastle University 10 January 28, 2014 12 OAuth 2.0 Dynamic Client Registration Metadata 13 draft-jones-oauth-dyn-reg-metadata-00 15 Abstract 17 This specification defines client metadata values used to describe 18 attributes of dynamically registered OAuth 2.0 clients. 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 http://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 August 1, 2014. 37 Copyright Notice 39 Copyright (c) 2014 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 (http://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 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 56 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 3 58 2.1. Human Readable Client Metadata . . . . . . . . . . . . . . 5 59 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 60 3.1. OAuth Registration Client Metadata Registration . . . . . 6 61 3.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 6 62 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 63 5. Normative References . . . . . . . . . . . . . . . . . . . . . 8 64 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 9 65 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . . 9 66 Appendix C. Document History . . . . . . . . . . . . . . . . . . 10 67 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 69 1. Introduction 71 In order for an OAuth 2.0 client to utilize an OAuth 2.0 72 authorization server, the client needs specific information to 73 interact with the server, including an OAuth 2.0 Client ID to use at 74 that server. The OAuth 2.0 Dynamic Client Registration Core Protocol 75 [OAuth.Registration] specification describes how an OAuth 2.0 client 76 can be dynamically registered with an authorization server to obtain 77 this information and how metadata about the client can be registered 78 with the server. 80 This specification extends the core registration specification by 81 defining a specific set of client metadata values that can be used to 82 describe additional attributes of dynamically registered OAuth 2.0 83 clients beyond those defined in the core registration specification. 85 1.1. Notational Conventions 87 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 88 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 89 document are to be interpreted as described in [RFC2119]. 91 Unless otherwise noted, all the protocol parameter names and values 92 are case sensitive. 94 1.2. Terminology 96 This specification uses the terms "Access Token", "Refresh Token", 97 "Authorization Code", "Authorization Grant", "Authorization Server", 98 "Authorization Endpoint", "Client", "Client Identifier", "Client 99 Secret", "Protected Resource", "Resource Owner", "Resource Server", 100 "Response Type", and "Token Endpoint" defined by OAuth 2.0 [RFC6749] 101 and the terms defined by the OAuth 2.0 Client Dynamic Registration 102 Core Protocol [OAuth.Registration]. 104 2. Client Metadata 106 Registering client metadata values with an authorization server may 107 be necessary or useful to facilitate usage of the authorization 108 server by the client. This specification extends the list of client 109 metadata values defined in OAuth 2.0 Client Dynamic Registration Core 110 Protocol [OAuth.Registration] with the following fields: 112 client_name Human-readable name of the client to be presented to the 113 user. If omitted, the authorization server MAY display the raw 114 "client_id" value to the user instead. It is RECOMMENDED that 115 clients always send this field. The value of this field MAY be 116 internationalized, as described in Section 2.1. 118 client_uri URL of the homepage of the client. If present, the 119 server SHOULD display this URL to the end user in a clickable 120 fashion. It is RECOMMENDED that clients always send this field. 121 The value of this field MUST point to a valid web page. The value 122 of this field MAY be internationalized, as described in 123 Section 2.1. 125 logo_uri URL that references a logo for the client. If present, the 126 server SHOULD display this image to the end user during approval. 127 The value of this field MUST point to a valid image file. The 128 value of this field MAY be internationalized, as described in 129 Section 2.1. 131 scope Space separated list of scope values (as described in OAuth 132 2.0 Section 3.3 [RFC6749]) that the client can use when requesting 133 access tokens. The semantics of values in this list is service 134 specific. If omitted, an authorization server MAY register a 135 Client with a default set of scopes. 137 contacts Array of email addresses for people responsible for this 138 client. The authorization server MAY make these addresses 139 available to end users for support requests for the client. An 140 authorization server MAY use these email addresses as identifiers 141 for an administrative page for this client. 143 tos_uri URL that points to a human-readable Terms of Service 144 document for the client. The Authorization Server SHOULD display 145 this URL to the end-user if it is given. The Terms of Service 146 usually describe a contractual relationship between the end-user 147 and the client that the end-user accepts when authorizing the 148 client. The value of this field MUST point to a valid web page. 149 The value of this field MAY be internationalized, as described in 150 Section 2.1. 152 policy_uri URL that points to a human-readable Policy document for 153 the client. The authorization server SHOULD display this URL to 154 the end-user if it is given. The policy usually describes how an 155 end-user's data will be used by the client. The value of this 156 field MUST point to a valid web page. The value of this field MAY 157 be internationalized, as described in Section 2.1. 159 jwks_uri URL for the Client's JSON Web Key Set [JWK] document 160 representing the client's public keys. The value of this field 161 MUST point to a valid JWK Set. These keys MAY be used for higher 162 level protocols that require signing or encryption. 164 software_id Identifier for the software that comprises a client. 165 Unlike "client_id", which is issued by the authorization server 166 and generally varies between instances, the "software_id" is 167 asserted by the client software and is intended to be shared 168 between all copies of the client software. The value for this 169 field MAY be a UUID [RFC4122]. The identifier SHOULD NOT change 170 when software version changes or when a new installation instance 171 is detected. Authorization servers MUST treat this field as self- 172 asserted by the client and MUST NOT make any trusted decisions on 173 the value of this field alone. 175 software_version Version identifier for the software that comprises 176 a client. The value of this field is a string that is intended to 177 be compared using string equality matching. The value of the 178 "software_version" SHOULD change on any update to the client 179 software. Authorization servers MUST treat this field as self- 180 asserted by the client and MUST NOT make any trusted decisions on 181 the value of this field alone. 183 2.1. Human Readable Client Metadata 185 Human-readable client metadata values and client metadata values that 186 reference human-readable values MAY be represented in multiple 187 languages and scripts. For example, the values of fields such as 188 "client_name", "tos_uri", "policy_uri", "logo_uri", and "client_uri" 189 might have multiple locale-specific values in some client 190 registrations. 192 To specify the languages and scripts, BCP47 [RFC5646] language tags 193 are added to client metadata member names, delimited by a # 194 character. Since JSON member names are case sensitive, it is 195 RECOMMENDED that language tag values used in Claim Names be spelled 196 using the character case with which they are registered in the IANA 197 Language Subtag Registry [IANA.Language]. In particular, normally 198 language names are spelled with lowercase characters, region names 199 are spelled with uppercase characters, and languages are spelled with 200 mixed case characters. However, since BCP47 language tag values are 201 case insensitive, implementations SHOULD interpret the language tag 202 values supplied in a case insensitive manner. Per the 203 recommendations in BCP47, language tag values used in metadata member 204 names should only be as specific as necessary. For instance, using 205 "fr" might be sufficient in many contexts, rather than "fr-CA" or 206 "fr-FR". 208 For example, a client could represent its name in English as 209 ""client_name#en": "My Client"" and its name in Japanese as 210 ""client_name#ja-Jpan-JP": 211 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D"" within the same 212 registration request. The authorization server MAY display any or 213 all of these names to the resource owner during the authorization 214 step, choosing which name to display based on system configuration, 215 user preferences or other factors. 217 If any human-readable field is sent without a language tag, parties 218 using it MUST NOT make any assumptions about the language, character 219 set, or script of the string value, and the string value MUST be used 220 as-is wherever it is presented in a user interface. To facilitate 221 interoperability, it is RECOMMENDED that clients and servers use a 222 human-readable field without any language tags in addition to any 223 language-specific fields, and it is RECOMMENDED that any human- 224 readable fields sent without language tags contain values suitable 225 for display on a wide variety of systems. 227 Implementer's Note: Many JSON libraries make it possible to reference 228 members of a JSON object as members of an object construct in the 229 native programming environment of the library. However, while the 230 "#" character is a valid character inside of a JSON object's member 231 names, it is not a valid character for use in an object member name 232 in many programming environments. Therefore, implementations will 233 need to use alternative access forms for these claims. For instance, 234 in JavaScript, if one parses the JSON as follows, "var j = 235 JSON.parse(json);", then the member "client_name#en-us" can be 236 accessed using the JavaScript syntax "j["client_name#en-us"]". 238 3. IANA Considerations 240 3.1. OAuth Registration Client Metadata Registration 242 This specification registers the Client Metadata values defined in 243 Section 2 in the IANA OAuth Registration Client Metadata registry 244 defined in [OAuth.Registration]. 246 3.1.1. Registry Contents 248 o Client Metadata Name: "client_name" 249 o Client Metadata Description: Human-readable name of the client to 250 be presented to the user 251 o Change Controller: IESG 252 o Specification Document(s): [[ this document ]] 253 o Client Metadata Name: "client_uri" 254 o Client Metadata Description: URL of the homepage of the client 255 o Change Controller: IESG 256 o Specification Document(s): [[ this document ]] 258 o Client Metadata Name: "logo_uri" 259 o Client Metadata Description: URL that references a logo for the 260 client 261 o Change Controller: IESG 262 o Specification Document(s): [[ this document ]] 264 o Client Metadata Name: "scope" 265 o Client Metadata Description: Space separated list of scope values 266 o Change Controller: IESG 267 o Specification Document(s): [[ this document ]] 269 o Client Metadata Name: "contacts" 270 o Client Metadata Description: Array of email addresses for people 271 responsible for this client 272 o Change Controller: IESG 273 o Specification document(s): [[ this document ]] 275 o Client Metadata Name: "tos_uri" 276 o Client Metadata Description: URL that points to a human-readable 277 Terms of Service document for the client 278 o Change Controller: IESG 279 o Specification Document(s): [[ this document ]] 281 o Client Metadata Name: "policy_uri" 282 o Client Metadata Description: URL that points to a human-readable 283 Policy document for the client 284 o Change Controller: IESG 285 o Specification Document(s): [[ this document ]] 287 o Client Metadata Name: "jwks_uri" 288 o Client Metadata Description: URL for the Client's JSON Web Key Set 289 [JWK] document representing the client's public keys 290 o Change Controller: IESG 291 o Specification Document(s): [[ this document ]] 293 o Client Metadata Name: "software_id" 294 o Client Metadata Description: Identifier for the software that 295 comprises a client 296 o Change Controller: IESG 297 o Specification Document(s): [[ this document ]] 298 o Client Metadata Name: "software_version" 299 o Client Metadata Description: Version identifier for the software 300 that comprises a client 301 o Change Controller: IESG 302 o Specification Document(s): [[ this document ]] 304 4. Security Considerations 306 The authorization server MUST treat all client metadata as self- 307 asserted. For instance, a rogue client might use the name and logo 308 for the legitimate client which it is trying to impersonate. 309 Additionally, a rogue client might try to use the software identifier 310 or software version of a legitimate client to attempt to associate 311 itself on the authorization server instances of the legitimate 312 client. To counteract this, an authorization server needs to take 313 steps to mitigate this phishing risk by looking at the entire 314 registration request and client configuration. For instance, an 315 authorization server could warn if the domain/site of the logo 316 doesn't match the domain/site of redirect URIs. An authorization 317 server could also refuse registration from a known software 318 identifier that is requesting different redirect URIs or a different 319 client homepage uri. An authorization server can also present 320 warning messages to end users about dynamically registered clients in 321 all cases, especially if such clients have been recently registered 322 or have not been trusted by any users at the authorization server 323 before. 325 In a situation where the authorization server is supporting open 326 client registration, it must be extremely careful with any URL 327 provided by the client that will be displayed to the user (e.g. 328 "logo_uri", "tos_uri", "client_uri", and "policy_uri"). For 329 instance, a rogue client could specify a registration request with a 330 reference to a drive-by download in the "policy_uri". The 331 authorization server SHOULD check to see if the "logo_uri", 332 "tos_uri", "client_uri", and "policy_uri" have the same host and 333 scheme as the those defined in the array of "redirect_uris" and that 334 all of these resolve to valid web pages. 336 5. Normative References 338 [IANA.Language] 339 Internet Assigned Numbers Authority (IANA), "Language 340 Subtag Registry", 2005. 342 [JWK] Jones, M., "JSON Web Key (JWK)", 343 draft-ietf-jose-json-web-key (work in progress), 344 January 2014. 346 [OAuth.Registration] 347 Richer, J., Jones, M., Bradley, J., and M. Machulak, 348 "OAuth 2.0 Dynamic Client Registration Core Protocol", 349 draft-ietf-oauth-dyn-reg (work in progress), January 2014. 351 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 352 Requirement Levels", BCP 14, RFC 2119, March 1997. 354 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 355 Unique IDentifier (UUID) URN Namespace", RFC 4122, 356 July 2005. 358 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 359 Languages", BCP 47, RFC 5646, September 2009. 361 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 362 RFC 6749, October 2012. 364 Appendix A. Acknowledgments 366 The authors thank the OAuth Working Group, the User-Managed Access 367 Working Group, and the OpenID Connect Working Group participants for 368 their input to this document. In particular, the following 369 individuals have been instrumental in their review and contribution 370 to various versions of this document: Amanda Anganes, Derek Atkins, 371 Tim Bray, Domenico Catalano, Donald Coffin, Vladimir Dzhuvinov, 372 George Fletcher, Thomas Hardjono, Phil Hunt, William Kim, Torsten 373 Lodderstedt, Eve Maler, Josh Mandel, Nov Matake, Tony Nadalin, Nat 374 Sakimura, Christian Scholz, and Hannes Tschofenig. 376 Appendix B. Open Issues 378 o Should this specification become a working group document so that 379 the functionality defined in this document that was previously 380 defined in draft-ietf-oauth-dyn-reg-14 is retained in working 381 group drafts? 383 o Should this specification become a working group document so that 384 the functionality that was previously defined in 385 draft-ietf-oauth-dyn-reg-14 is retained in working group drafts? 387 Appendix C. Document History 389 [[ to be removed by the RFC editor before publication as an RFC ]] 391 -00 393 o Partitioned the Dynamic Client Registration specification into 394 core, metadata, and management specifications. This built on work 395 first published as draft-richer-oauth-dyn-reg-core-00 and 396 draft-richer-oauth-dyn-reg-management-00. 398 o Registered the Client Metadata values defined by this 399 specification in the IANA OAuth Registration Client Metadata 400 registry. 402 o Rewrote the introduction. 404 Authors' Addresses 406 Justin Richer 407 The MITRE Corporation 409 Email: jricher@mitre.org 411 Michael B. Jones 412 Microsoft 414 Email: mbj@microsoft.com 415 URI: http://self-issued.info/ 417 John Bradley 418 Ping Identity 420 Email: ve7jtb@ve7jtb.com 422 Maciej Machulak 423 Newcastle University 425 Email: m.p.machulak@ncl.ac.uk 426 URI: http://ncl.ac.uk/