idnits 2.17.1 draft-ietf-oauth-dyn-reg-14.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 are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. 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 (July 29, 2013) is 3922 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) ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) Summary: 6 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group J. Richer, Ed. 3 Internet-Draft The MITRE Corporation 4 Intended status: Standards Track J. Bradley 5 Expires: January 30, 2014 Ping Identity 6 M. Jones 7 Microsoft 8 M. Machulak 9 Newcastle University 10 July 29, 2013 12 OAuth 2.0 Dynamic Client Registration Protocol 13 draft-ietf-oauth-dyn-reg-14 15 Abstract 17 This specification defines an endpoint and protocol for dynamic 18 registration of OAuth 2.0 clients at an authorization server and 19 methods for the dynamically registered client to manage its 20 registration through an OAuth 2.0 protected web API. 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 January 30, 2014. 39 Copyright Notice 41 Copyright (c) 2013 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 57 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 58 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.3. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 4 60 1.4. Registration Tokens and Client Credentials . . . . . . . 6 61 1.4.1. Credential Rotation . . . . . . . . . . . . . . . . . 7 62 2. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 7 63 2.1. Relationship Between Grant Types and Response Types . . . 11 64 2.2. Human Readable Client Metadata . . . . . . . . . . . . . 11 65 3. Client Registration Endpoint . . . . . . . . . . . . . . . . 13 66 3.1. Client Registration Request . . . . . . . . . . . . . . . 13 67 3.2. Client Registration Response . . . . . . . . . . . . . . 15 68 4. Client Configuration Endpoint . . . . . . . . . . . . . . . . 15 69 4.1. Forming the Client Configuration Endpoint URL . . . . . . 16 70 4.2. Client Read Request . . . . . . . . . . . . . . . . . . . 16 71 4.3. Client Update Request . . . . . . . . . . . . . . . . . . 17 72 4.4. Client Delete Request . . . . . . . . . . . . . . . . . . 19 73 5. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 20 74 5.1. Client Information Response . . . . . . . . . . . . . . . 20 75 5.2. Client Registration Error Response . . . . . . . . . . . 22 76 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 77 6.1. OAuth Token Endpoint Authentication Methods Registry . . 23 78 6.1.1. Registration Template . . . . . . . . . . . . . . . . 24 79 6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 24 80 7. Security Considerations . . . . . . . . . . . . . . . . . . . 25 81 8. Normative References . . . . . . . . . . . . . . . . . . . . 27 82 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 28 83 Appendix B. Client Lifecycle Examples . . . . . . . . . . . . . 28 84 B.1. Open Registration . . . . . . . . . . . . . . . . . . . . 29 85 B.2. Protected Registration . . . . . . . . . . . . . . . . . 30 86 B.3. Developer Automation . . . . . . . . . . . . . . . . . . 31 87 Appendix C. Document History . . . . . . . . . . . . . . . . . . 33 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 90 1. Introduction 92 In some use-case scenarios, it is desirable or necessary to allow 93 OAuth 2.0 clients to obtain authorization from an OAuth 2.0 94 authorization server without requiring the two parties to interact 95 beforehand. Nevertheless, for the authorization server to accurately 96 and securely represent to end-users which client is seeking 97 authorization to access the end-user's resources, a method for 98 automatic and unique registration of clients is needed. The OAuth 99 2.0 authorization framework does not define how the relationship 100 between the client and the authorization server is initialized, or 101 how a given client is assigned a unique client identifier. 102 Historically, this has happened out-of-band from the OAuth 2.0 103 protocol. This draft provides a mechanism for a client to register 104 itself with the authorization server, which can be used to 105 dynamically provision a client identifier, and optionally a client 106 secret. Additionally, the mechanisms in this draft may can be used 107 by a client developer to register the client with the authorization 108 server in a programmatic fashion. 110 As part of the registration process, this specification also defines 111 a mechanism for the client to present the authorization server with a 112 set of metadata, such as a display name and icon to be presented to 113 the user during the authorization step. This draft also provides a 114 mechanism for the client to read and update this information after 115 the initial registration action. This draft protects these actions 116 through the use of an OAuth 2.0 bearer access token that is issued to 117 the client during registration explicitly for this purpose. 119 1.1. Notational Conventions 121 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 122 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 123 document are to be interpreted as described in [RFC2119]. 125 Unless otherwise noted, all the protocol parameter names and values 126 are case sensitive. 128 1.2. Terminology 130 This specification uses the terms "Access Token", "Refresh Token", 131 "Authorization Code", "Authorization Grant", "Authorization Server", 132 "Authorization Endpoint", "Client", "Client Identifier", "Client 133 Secret", "Protected Resource", "Resource Owner", "Resource Server", 134 and "Token Endpoint" defined by OAuth 2.0 [RFC6749]. 136 This specification defines the following additional terms: 138 Client Registration Endpoint OAuth 2.0 endpoint through which a 139 client can be registered at an authorization server. The means by 140 which the URL for this endpoint are obtained are out of scope for 141 this specification. 143 Client Configuration Endpoint OAuth 2.0 endpoint through which 144 registration information for a registered client can be managed. 145 This URL for this endpoint is returned by the authorization server 146 in the client information response. 147 Registration Access Token OAuth 2.0 bearer token issued by the 148 authorization server through the client registration endpoint that 149 is used to authenticate the caller when accessing the client's 150 registration information at the client configuration endpoint. 151 This access token is associated with a particular registered 152 client. 153 Initial Access Token OAuth 2.0 access token optionally issued by an 154 Authorization Server and used to authorize calls to the client 155 registration endpoint. The type and format of this token are 156 likely service-specific and are out of scope for this 157 specification. The means by which the authorization server issues 158 this token as well as the means by which the registration endpoint 159 validates this token are out of scope for this specification. 161 1.3. Protocol Flow 163 (preamble) 165 +--------(A)- Initial Access Token 166 | 167 v 168 +-----------+ +---------------+ 169 | |--(B)- Client Registration Request -->| Client | 170 | | | Registration | 171 | |<-(C)- Client Information Response ---| Endpoint | 172 | | +---------------+ 173 | | 174 | | +---------------+ 175 | Client or |--(D)- Read or Update Request ------->| | 176 | Developer | | | 177 | |<-(E)- Client Information Response ---| Client | 178 | | | Configuration | 179 | | | Endpoint | 180 | | | | 181 | |--(F)- Delete Request --------------->| | 182 | | | | 183 | |<-(G)- Delete Confirmation -----------| | 184 +-----------+ +---------------+ 186 Figure 1: Abstract Protocol Flow 187 The abstract OAuth 2.0 Client dynamic registration flow illustrated 188 in Figure 1 describes the interaction between the client or developer 189 and the two endpoints defined in this specification. This figure 190 does not demonstrate error conditions. This flow includes the 191 following steps: 193 (A) 194 Optionally, the client or developer is issued an initial access 195 token for use with the client registration endpoint. The method 196 by which the initial access token is issued to the client or 197 developer is out of scope for this specification. 198 (B) 199 The client or developer calls the client registration endpoint 200 with its desired registration metadata, optionally including the 201 initial access token from (A) if one is required by the 202 authorization server. 203 (C) 204 The authorization server registers the client and returns the 205 client's registered metadata, a client identifier that is unique 206 at the server, a set of client credentials such as a client secret 207 if applicable for this client, a URI pointing to the client 208 configuration endpoint, and a registration access token to be used 209 when calling the client configuration endpoint. 210 (D) 211 The client or developer optionally calls the client configuration 212 endpoint with a read or update request using the registration 213 access token issued in (C). An update request contains all of the 214 client's registered metadata. 215 (E) 216 The authorization server responds with the client's current 217 configuration, potentially including a new registration access 218 token and a new set of client credentials such as a client secret 219 if applicable for this client. If a new registration access token 220 is issued, it replaces the token issued in (C) for all subsequent 221 calls to the client configuration endpoint. 222 (F) 223 The client or developer optionally calls the client configuration 224 endpoint with a delete request using the registration access token 225 issued in (C). 226 (G) 227 The authorization server deprovisions the client and responds with 228 a confirmation that the deletion has taken place. 230 Further discussion of possible example lifecycles are found in the 231 Appendix to this specification, Client Lifecycle Examples 232 (Appendix B). 234 1.4. Registration Tokens and Client Credentials 236 Throughout the course of the dynamic registration protocol, there are 237 three different classes of credentials in play, each with different 238 properties and targets. 240 o The initial access token is optionally used by the client or 241 developer at the registration endpoint. This is an OAuth 2.0 242 token that is used to authorize the initial client registration 243 request. The content, structure, generation, and validation of 244 this token are out of scope for this specification. The 245 authorization server can use this token to verify that the 246 presenter is allowed to dynamically register new clients. This 247 token may be shared between multiple instances of a client to 248 allow them to each register separately, thereby letting the 249 authorization server use this token to tie multiple instances of 250 registered clients (each with their own distinct client 251 identifier) back to the party to whom the initial access token was 252 issued, usually an application developer. This token should be 253 used only at the client registration endpoint. 254 o The registration access token is used by the client or developer 255 at the client configuration endpoint and represents the holder's 256 authorization to manage the registration of a client. This is an 257 OAuth 2.0 bearer token that is issued from the client registration 258 endpoint in response to a client registration request and is 259 returned in a client information response. The registration 260 access token is uniquely bound to the client identifier and is 261 required to be presented with all calls to the client 262 configuration endpoint. The registration access token should be 263 protected and should not be shared between instances of a client 264 (otherwise, one instance could change or delete registration 265 values for all instances of the client). The registration access 266 token can be rotated through the use of the client read and update 267 methods on the client configuration endpoint. The registration 268 access token should be used only at the client configuration 269 endpoint. 270 o The client credentials (such as "client_secret") are optional 271 depending on the type of client and are used to retrieve OAuth 272 tokens. Client credentials are most often bound to particular 273 instances of a client and should not be shared between instances. 274 Note that since not all types of clients have client credentials, 275 they cannot be used to manage client registrations at the client 276 configuration endpoint. The client credentials can be rotated 277 through the use of the client read and update methods on the 278 client configuration endpoint. The client credentials can not be 279 used for authentication at the client registration endpoint or at 280 the client configuration endpoint. 282 1.4.1. Credential Rotation 284 The Authorization Server MAY rotate the client's registration access 285 token and/or client credentials (such as a "client_secret") 286 throughout the lifetime of the client. The client can discovery that 287 these values have changed by reading the client information response 288 returned from either a read or update request to the client 289 configuration endpoint. The client's current registration access 290 token and client credentials (if applicable) MUST be included in this 291 response. 293 The registration access token SHOULD be rotated only in response to a 294 read or update request to the client configuration endpoint, at which 295 point the new registration access token is returned to the client and 296 the old registration access token SHOULD be discarded by both 297 parties. If the registration access token to expire or be rotated 298 outside of such requests, the client or developer may be locked out 299 of managing the client's configuration. 301 2. Client Metadata 303 Clients generally have an array of metadata associated with their 304 unique client identifier at the authorization server. These can 305 range from human-facing display strings, such as a client name, to 306 items that impact the security of the protocol, such as the list of 307 valid redirect URIs. 309 The client metadata values serve two parallel purposes in the overall 310 OAuth 2.0 dynamic client registration protocol: 312 o the client requesting its desired values for each parameter to the 313 authorization server in a register (Section 3.1) or update 314 (Section 4.3) request, and 315 o the authorization server informing the client of the current 316 values of each parameter that the client has been registered to 317 use through a client information response (Section 5.1). 319 An authorization server MAY override any value that a client requests 320 during the registration process (including any omitted values) and 321 replace the requested value with a default at the server's 322 discretion. The authorization server SHOULD provide documentation 323 for any fields that it requires to be filled in by the client or to 324 have particular values or formats. An authorization server MAY 325 ignore the values provided by the client for any field in this list. 327 Extensions and profiles of this specification MAY expand this list, 328 and authorization servers MUST accept all fields in this list. The 329 authorization server MUST ignore any additional parameters sent by 330 the Client that it does not understand. 332 redirect_uris 333 Array of redirect URIs for use in redirect-based flows such as the 334 authorization code and implicit grant types. It is RECOMMENDED 335 that clients using these flows register this parameter, and an 336 authorization server SHOULD require registration of valid redirect 337 URIs for all clients that use these grant types to protect against 338 token and credential theft attacks. 339 client_name 340 Human-readable name of the client to be presented to the user. If 341 omitted, the authorization server MAY display the raw "client_id" 342 value to the user instead. It is RECOMMENDED that clients always 343 send this field. The value of this field MAY be internationalized 344 as described in Human Readable Client Metadata (Section 2.2). 345 client_uri 346 URL of the homepage of the client. If present, the server SHOULD 347 display this URL to the end user in a clickable fashion. It is 348 RECOMMENDED that clients always send this field. The value of 349 this field MUST point to a valid web page. The value of this 350 field MAY be internationalized as described in Human Readable 351 Client Metadata (Section 2.2). 352 logo_uri 353 URL that references a logo for the client. If present, the server 354 SHOULD display this image to the end user during approval. The 355 value of this field MUST point to a valid image file. The value 356 of this field MAY be internationalized as described in Human 357 Readable Client Metadata (Section 2.2). 358 contacts 359 Array of email addresses for people responsible for this client. 360 The authorization server MAY make these addresses available to end 361 users for support requests for the client. An authorization 362 server MAY use these email addresses as identifiers for an 363 administrative page for this client. 364 tos_uri 365 URL that points to a human-readable Terms of Service document for 366 the client. The Authorization Server SHOULD display this URL to 367 the end-user if it is given. The Terms of Service usually 368 describe a contractual relationship between the end-user and the 369 client that the end-user accepts when authorizing the client. The 370 value of this field MUST point to a valid web page. The value of 371 this field MAY be internationalized as described in Human Readable 372 Client Metadata (Section 2.2). 373 policy_uri 374 URL that points to a human-readable Policy document for the 375 client. The authorization server SHOULD display this URL to the 376 end-user if it is given. The policy usually describes how an end- 377 user's data will be used by the client. The value of this field 378 MUST point to a valid web page. The value of this field MAY be 379 internationalized as described in Human Readable Client Metadata 380 (Section 2.2). 381 token_endpoint_auth_method 382 The requested authentication method for the token endpoint. 383 Values defined by this specification are: 385 * "none": The client is a public client as defined in OAuth 2.0 386 and does not have a client secret. 387 * "client_secret_post": The client uses the HTTP POST parameters 388 defined in OAuth 2.0 section 2.3.1. 389 * "client_secret_basic": the client uses HTTP Basic defined in 390 OAuth 2.0 section 2.3.1 392 Additional values can be defined via the IANA OAuth Token Endpoint 393 Authentication Methods Registry Section 6.1. Absolute URIs can 394 also be used as values for this parameter without being 395 registered. If unspecified or omitted, the default is 396 "client_secret_basic", denoting HTTP Basic Authentication Scheme 397 as specified in Section 2.3.1 of OAuth 2.0. 398 scope 399 Space separated list of scope values (as described in OAuth 2.0 400 Section 3.3 [RFC6749]) that the client can use when requesting 401 access tokens. The semantics of values in this list is service 402 specific. If omitted, an authorization server MAY register a 403 Client with a default set of scopes. 404 grant_types 405 Array of OAuth 2.0 grant types that the Client may use. These 406 grant types are defined as follows: 408 * "authorization_code": The Authorization Code Grant described in 409 OAuth 2.0 Section 4.1 410 * "implicit": The Implicit Grant described in OAuth 2.0 411 Section 4.2 412 * "password": The Resource Owner Password Credentials Grant 413 described in OAuth 2.0 Section 4.3 414 * "client_credentials": The Client Credentials Grant described in 415 OAuth 2.0 Section 4.4 416 * "refresh_token": The Refresh Token Grant described in OAuth 2.0 417 Section 6. 418 * "urn:ietf:params:oauth:grant-type:jwt-bearer": The JWT Bearer 419 Grant defined in OAuth JWT Bearer Token Profiles [OAuth.JWT]. 421 * "urn:ietf:params:oauth:grant-type:saml2-bearer": The SAML 2 422 Bearer Grant defined in OAuth SAML 2 Bearer Token Profiles 423 [OAuth.SAML2]. 425 Authorization Servers MAY allow for other values as defined in 426 grant type extensions to OAuth 2.0. The extension process is 427 described in OAuth 2.0 Section 2.5. If the token endpoint is used 428 in the grant type, the value of this parameter MUST be the same as 429 the value of the "grant_type" parameter passed to the token 430 endpoint defined in the extension. 431 response_types 432 Array of the OAuth 2.0 response types that the Client may use. 433 These response types are defined as follows: 435 * "code": The Authorization Code response described in OAuth 2.0 436 Section 4.1. 437 * "token": The Implicit response described in OAuth 2.0 438 Section 4.2. 440 Authorization servers MAY allow for other values as defined in 441 response type extensions to OAuth 2.0. The extension process is 442 described in OAuth 2.0 Section 2.5. If the authorization endpoint 443 is used by the grant type, the value of this parameter MUST be the 444 same as the value of the "response_type" parameter passed to the 445 authorization endpoint defined in the extension. 446 jwks_uri 447 URL for the Client's JSON Web Key Set [JWK] document representing 448 the client's public keys. The value of this field MUST point to a 449 valid JWK Set. These keys MAY be used for higher level protocols 450 that require signing or encryption. 451 software_id 452 A identifier for the software that comprises a client. Unlike 453 "client_id", which is issued by the authorization server and 454 generally varies between instances, the "software_id" is asserted 455 by the client software and is intended to be shared between all 456 copies of the client software. The value for this field MAY be a 457 UUID [RFC4122]. The identifier SHOULD NOT change when software 458 version changes or when a new installation instance is detected. 459 Authorization servers MUST treat this field as self-asserted by 460 the client and MUST NOT make any trusted decisions on the value of 461 this field alone. 462 software_version 463 A version identifier for the software that comprises a client. 464 The value of this field is a string that is intended to be 465 compared using string equality matching. The value of the 466 "software_version" SHOULD change on any update to the client 467 software. Authorization servers MUST treat this field as self- 468 asserted by the client and MUST NOT make any trusted decisions on 469 the value of this field alone. 471 2.1. Relationship Between Grant Types and Response Types 473 The "grant_types" and "response_types" values described above are 474 partially orthogonal, as they refer to arguments passed to different 475 endpoints in the OAuth protocol. However, they are related in that 476 the "grant_types" available to a client influence the 477 "response_types" that the client is allowed to use, and vice versa. 478 For instance, a "grant_types" value that includes 479 "authorization_code" implies a "response_types" value that includes 480 "code", as both values are defined as part of the OAuth 2.0 481 authorization code grant. As such, a server supporting these fields 482 SHOULD take steps to ensure that a client cannot register itself into 483 an inconsistent state. 485 The correlation between the two fields is listed in the table below. 487 +-------------------------------------------------+-----------------+ 488 | grant_types value includes: | response_types | 489 | | value includes: | 490 +-------------------------------------------------+-----------------+ 491 | authorization_code | code | 492 | implicit | token | 493 | password | (none) | 494 | client_credentials | (none) | 495 | refresh_token | (none) | 496 | urn:ietf:params:oauth:grant-type:jwt-bearer | (none) | 497 | urn:ietf:params:oauth:grant-type:saml2-bearer | (none) | 498 +-------------------------------------------------+-----------------+ 500 Extensions and profiles of this document that introduce new values to 501 either the "grant_types" or "response_types" parameter MUST document 502 all correspondences between these two parameter types. 504 2.2. Human Readable Client Metadata 506 Human-readable client metadata values and client metadata values that 507 reference human-readable values MAY be represented in multiple 508 languages and scripts. For example, the values of fields such as 509 "client_name", "tos_uri", "policy_uri", "logo_uri", and "client_uri" 510 might have multiple locale-specific values in some client 511 registrations. 513 To specify the languages and scripts, BCP47 [RFC5646] language tags 514 are added to client metadata member names, delimited by a # 515 character. Since JSON member names are case sensitive, it is 516 RECOMMENDED that language tag values used in Claim Names be spelled 517 using the character case with which they are registered in the IANA 518 Language Subtag Registry [IANA.Language]. In particular, normally 519 language names are spelled with lowercase characters, region names 520 are spelled with uppercase characters, and languages are spelled with 521 mixed case characters. However, since BCP47 language tag values are 522 case insensitive, implementations SHOULD interpret the language tag 523 values supplied in a case insensitive manner. Per the 524 recommendations in BCP47, language tag values used in metadata member 525 names should only be as specific as necessary. For instance, using 526 "fr" might be sufficient in many contexts, rather than "fr-CA" or 527 "fr-FR". 529 For example, a client could represent its name in English as 530 ""client_name#en": "My Client"" and its name in Japanese as 531 ""client_name#ja-Jpan-JP": 532 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D"" within the same 533 registration request. The authorization server MAY display any or 534 all of these names to the resource owner during the authorization 535 step, choosing which name to display based on system configuration, 536 user preferences or other factors. 538 If any human-readable field is sent without a language tag, parties 539 using it MUST NOT make any assumptions about the language, character 540 set, or script of the string value, and the string value MUST be used 541 as-is wherever it is presented in a user interface. To facilitate 542 interoperability, it is RECOMMENDED that clients and servers use a 543 human-readable field without any language tags in addition to any 544 language-specific fields, and it is RECOMMENDED that any human- 545 readable fields sent without language tags contain values suitable 546 for display on a wide variety of systems. 548 Implementer's Note: Many JSON libraries make it possible to reference 549 members of a JSON object as members of an object construct in the 550 native programming environment of the library. However, while the 551 "#" character is a valid character inside of a JSON object's member 552 names, it is not a valid character for use in an object member name 553 in many programming environments. Therefore, implementations will 554 need to use alternative access forms for these claims. For instance, 555 in JavaScript, if one parses the JSON as follows, "var j = 556 JSON.parse(json);", then the member "client_name#en-us" can be 557 accessed using the JavaScript syntax "j["client_name#en-us"]". 559 3. Client Registration Endpoint 561 The client registration endpoint is an OAuth 2.0 endpoint defined in 562 this document that is designed to allow a client to be registered 563 with the authorization server. The client registration endpoint MUST 564 accept HTTP POST messages with request parameters encoded in the 565 entity body using the "application/json" format. The client 566 registration endpoint MUST be protected by a transport-layer security 567 mechanism, and the server MUST support TLS 1.2 RFC 5246 [RFC5246] and 568 /or TLS 1.0 [RFC2246] and MAY support additional transport-layer 569 mechanisms meeting its security requirements. When using TLS, the 570 Client MUST perform a TLS/SSL server certificate check, per RFC 6125 571 [RFC6125]. 573 The client registration endpoint MAY be an OAuth 2.0 protected 574 resource and accept an initial access token in the form of an OAuth 575 2.0 [RFC6749] access token to limit registration to only previously 576 authorized parties. The method by which the initial access token is 577 obtained by the registrant is generally out-of-band and is out of 578 scope for this specification. The method by which the initial access 579 token is verified and validated by the client registration endpoint 580 is out of scope for this specification. 582 To support open registration and facilitate wider interoperability, 583 the client registration endpoint SHOULD allow initial registration 584 requests with no authorization (which is to say, with no OAuth 2.0 585 access token in the request). These requests MAY be rate-limited or 586 otherwise limited to prevent a denial-of-service attack on the client 587 registration endpoint. 589 To allow the registrant to manage the client's information, the 590 client registration endpoint issues a request access token as an 591 OAuth 2.0 Bearer Token [RFC6750] to securely authorize calls to the 592 client configuration endpoint (Section 4). 594 The client registration endpoint MUST ignore all parameters it does 595 not understand. 597 3.1. Client Registration Request 599 This operation registers a new client to the authorization server. 600 The authorization server assigns this client a unique client 601 identifier, optionally assigns a client secret, and associates the 602 metadata given in the request with the issued client identifier. The 603 request includes any parameters described in Client Metadata 604 (Section 2) that the client wishes to specify for itself during the 605 registration. The authorization server MAY provision default values 606 for any items omitted in the client metadata. 608 To register, the client or developer sends an HTTP POST to the client 609 registration endpoint with a content type of "application/json". The 610 HTTP Entity Payload is a JSON [RFC4627] document consisting of a JSON 611 object and all parameters as top-level members of that JSON object. 613 For example, if the server supports open registration (with no 614 initial access token), the client could send the following 615 registration request to the client registration endpoint: 617 Following is a non-normative example request (with line wraps for 618 display purposes only): 620 POST /register HTTP/1.1 621 Content-Type: application/json 622 Accept: application/json 623 Host: server.example.com 625 { 626 "redirect_uris":["https://client.example.org/callback", 627 "https://client.example.org/callback2"], 628 "client_name":"My Example Client", 629 "client_name#ja-Jpan-JP": 630 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", 631 "token_endpoint_auth_method":"client_secret_basic", 632 "scope":"read write dolphin", 633 "logo_uri":"https://client.example.org/logo.png", 634 "jwks_uri":"https://client.example.org/my_public_keys.jwks" 635 } 637 Alternatively, if the server supports authorized registration, the 638 developer or the client will be provisioned with an initial access 639 token (the method by which the initial access token is obtained is 640 out of scope for this specification). The developer or client sends 641 the following authorized registration request to the client 642 registration endpoint. Note that the initial access token sent in 643 this example as an OAuth 2.0 Bearer Token [RFC6750], but any OAuth 644 2.0 token type could be used by an authorization server: 646 Following is a non-normative example request (with line wraps for 647 display purposes only): 649 POST /register HTTP/1.1 650 Content-Type: application/json 651 Accept: application/json 652 Authorization: Bearer ey23f2.adfj230.af32-developer321 653 Host: server.example.com 655 { 656 "redirect_uris":["https://client.example.org/callback", 657 "https://client.example.org/callback2"], 658 "client_name":"My Example Client", 659 "client_name#ja-Jpan-JP": 660 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", 661 "token_endpoint_auth_method":"client_secret_basic", 662 "scope":"read write dolphin", 663 "logo_uri":"https://client.example.org/logo.png", 664 "jwks_uri":"https://client.example.org/my_public_keys.jwks" 665 } 667 3.2. Client Registration Response 669 Upon successful registration, the authorization server generates a 670 new client identifier for the client. This client identifier MUST be 671 unique at the server and MUST NOT be in use by any other client. The 672 server responds with an HTTP 201 Created code and a body of type 673 "application/json" with content described in Client Information 674 Response (Section 5.1). 676 Upon an unsuccessful registration, the authorization server responds 677 with an error as described in Client Registration Error 678 (Section 5.2). 680 4. Client Configuration Endpoint 682 The client configuration endpoint is an OAuth 2.0 protected resource 683 that is provisioned by the server to facilitate viewing, updating, 684 and deleting a client's registered information. The location of this 685 endpoint is communicated to the client through the 686 "registration_client_uri" member of the Client Information Response 687 (Section 5.1). The client MUST use its registration access token in 688 all calls to this endpoint as an OAuth 2.0 Bearer Token [RFC6750]. 690 Operations on this endpoint are switched through the use of different 691 HTTP methods [RFC2616]. If an authorization server does not support 692 a particular method on the client configuration endpoint, it MUST 693 respond with the appropriate error code. 695 4.1. Forming the Client Configuration Endpoint URL 697 The authorization server MUST provide the client with the fully 698 qualified URL in the "registration_client_uri" element of the Client 699 Information Response (Section 5.1). The authorization server MUST 700 NOT expect the client to construct or discover this URL on its own. 701 The client MUST use the URL as given by the server and MUST NOT 702 construct this URL from component pieces. 704 Depending on deployment characteristics, the client configuration 705 endpoint URL may take any number of forms. It is RECOMMENDED that 706 this endpoint URL be formed through the use of a server-constructed 707 URL string which combines the client registration endpoint's URL and 708 the issued "client_id" for this client, with the latter as either a 709 path parameter or a query parameter. For example, a client with the 710 client identifier "s6BhdRkqt3" could be given a client configuration 711 endpoint URL of "https://server.example.com/register/s6BhdRkqt3" 712 (path parameter) or of "https://server.example.com/ 713 register?client_id=s6BhdRkqt3" (query parameter). In both of these 714 cases, the client simply uses the URL as given by the authorization 715 server. 717 These common patterns can help the server to more easily determine 718 the client to which the request pertains, which MUST be matched 719 against the client to which the registration access token was issued. 720 If desired, the server MAY simply return the client registration 721 endpoint URL as the client configuration endpoint URL and change 722 behavior based on the authentication context provided by the 723 registration access token. 725 4.2. Client Read Request 727 To read the current configuration of the client on the authorization 728 server, the client makes an HTTP GET request to the client 729 configuration endpoint, authenticating with its registration access 730 token. 732 Following is a non-normative example request (with line wraps for 733 display purposes only): 735 GET /register/s6BhdRkqt3 HTTP/1.1 736 Accept: application/json 737 Host: server.example.com 738 Authorization: Bearer reg-23410913-abewfq.123483 739 Upon successful read of the information for a currently active 740 client, the authorization server responds with an HTTP 200 OK with 741 content type of "application/json" and a payload as described in 742 Client Information Response (Section 5.1). Some values in the 743 response, including the "client_secret" and 744 "registration_access_token", MAY be different from those in the 745 initial registration response. If the authorization server includes 746 a new client secret and/or registration access token in its response, 747 the client MUST immediately discard its previous client secret and/or 748 registration access token. The value of the "client_id" MUST NOT 749 change from the initial registration response. 751 If the registration access token used to make this request is not 752 valid, the server MUST respond with an error as described in OAuth 753 Bearer Token Usage [RFC6750]. 755 If the client does not exist on this server, the server MUST respond 756 with HTTP 401 Unauthorized and the registration access token used to 757 make this request SHOULD be immediately revoked. 759 If the client does not have permission to read its record, the server 760 MUST return an HTTP 403 Forbidden. 762 4.3. Client Update Request 764 This operation updates a previously-registered client with new 765 metadata at the authorization server. This request is authenticated 766 by the registration access token issued to the client. 768 The client sends an HTTP PUT to the client configuration endpoint 769 with a content type of "application/json". The HTTP entity payload 770 is a JSON [RFC4627] document consisting of a JSON object and all 771 parameters as top- level members of that JSON object. 773 This request MUST include all fields described in Client Metadata 774 (Section 2) as returned to the client from a previous register, read, 775 or update operation. The client MUST NOT include the 776 "registration_access_token", "registration_client_uri", 777 "client_secret_expires_at", or "client_id_issued_at" fields described 778 in Client Information Response (Section 5.1). 780 Valid values of client metadata fields in this request MUST replace, 781 not augment, the values previously associated with this client. 782 Omitted fields MUST be treated as null or empty values by the server. 784 The client MUST include its "client_id" field in the request, and it 785 MUST be the same as its currently-issued client identifier. If the 786 client includes the "client_secret" field in the request, the value 787 of this field MUST match the currently-issued client secret for that 788 client. The client MUST NOT be allowed to overwrite its existing 789 client secret with its own chosen value. 791 For all metadata fields, the authorization server MAY replace any 792 invalid values with suitable default values, and it MUST return any 793 such fields to the client in the response. 795 For example, a client could send the following request to the client 796 registration endpoint to update the client registration in the above 797 example with new information: 799 Following is a non-normative example request (with line wraps for 800 display purposes only): 802 PUT /register/s6BhdRkqt3 HTTP/1.1 803 Accept: application/json 804 Host: server.example.com 805 Authorization: Bearer reg-23410913-abewfq.123483 807 { 808 "client_id":"s6BhdRkqt3", 809 "client_secret": "cf136dc3c1fc93f31185e5885805d", 810 "redirect_uris":["https://client.example.org/callback", 811 "https://client.example.org/alt"], 812 "scope": "read write dolphin", 813 "grant_types": ["authorization_code", "refresh_token"] 814 "token_endpoint_auth_method": "client_secret_basic", 815 "jwks_uri": "https://client.example.org/my_public_keys.jwks" 816 "client_name":"My New Example", 817 "client_name#fr":"Mon Nouvel Exemple", 818 "logo_uri":"https://client.example.org/newlogo.png" 819 "logo_uri#fr":"https://client.example.org/fr/newlogo.png" 820 } 822 Upon successful update, the authorization server responds with an 823 HTTP 200 OK Message with content type "application/json" and a 824 payload as described in Client Information Response (Section 5.1). 825 Some values in the response, including the "client_secret" and 826 r"egistration_access_token", MAY be different from those in the 827 initial registration response. If the authorization server includes 828 a new client secret and/or registration access token in its response, 829 the client MUST immediately discard its previous client secret and/or 830 registration access token. The value of the "client_id" MUST NOT 831 change from the initial registration response. 833 If the registration access token used to make this request is not 834 valid, the server MUST respond with an error as described in OAuth 835 Bearer Token Usage [RFC6750]. 837 If the client does not exist on this server, the server MUST respond 838 with HTTP 401 Unauthorized, and the registration access token used to 839 make this request SHOULD be immediately revoked. 841 If the client is not allowed to update its records, the server MUST 842 respond with HTTP 403 Forbidden. 844 If the client attempts to set an invalid metadata field and the 845 authorization server does not set a default value, the authorization 846 server responds with an error as described in Client Registration 847 Error Response (Section 5.2). 849 4.4. Client Delete Request 851 To deprovision itself on the authorization server, the client makes 852 an HTTP DELETE request to the client configuration endpoint. This 853 request is authenticated by the registration access token issued to 854 the client. 856 Following is a non-normative example request (with line wraps for 857 display purposes only): 859 DELETE /register/s6BhdRkqt3 HTTP/1.1 860 Host: server.example.com 861 Authorization: Bearer reg-23410913-abewfq.123483 863 A successful delete action will invalidate the "client_id", 864 "client_secret", and "registration_access_token" for this client, 865 thereby preventing the "client_id" from being used at either the 866 authorization endpoint or token endpoint of the authorization server. 867 The authorization server SHOULD immediately invalidate all existing 868 authorization grants and currently-active tokens associated with this 869 client. 871 If a client has been successfully deprovisioned, the authorization 872 server responds with an HTTP 204 No Content message. 874 If the server does not support the delete method, the server MUST 875 respond with an HTTP 405 Not Supported. 877 If the registration access token used to make this request is not 878 valid, the server MUST respond with an error as described in OAuth 879 Bearer Token Usage [RFC6750]. 881 If the client does not exist on this server, the server MUST respond 882 with HTTP 401 Unauthorized and the registration access token used to 883 make this request SHOULD be immediately revoked. 885 If the client is not allowed to delete itself, the server MUST 886 respond with HTTP 403 Forbidden. 888 Following is a non-normative example response: 890 HTTP/1.1 204 No Content 891 Cache-Control: no-store 892 Pragma: no-cache 894 5. Responses 896 In response to certain requests from the client to either the client 897 registration endpoint or the client configuration endpoint as 898 described in this specification, the authorization server sends the 899 following response bodies. 901 5.1. Client Information Response 903 The response contains the client identifier as well as the client 904 secret, if the client is a confidential client. The response also 905 contains the fully qualified URL of the client configuration endpoint 906 for this specific client that the client may use to obtain and update 907 information about itself. The response also contains a registration 908 access token that is to be used by the client to perform subsequent 909 operations at the client configuration endpoint. 911 client_id 912 REQUIRED. The unique client identifier, MUST NOT be currently 913 valid for any other registered client. 914 client_secret 915 OPTIONAL. The client secret. If issued, this MUST be unique for 916 each "client_id". This value is used by confidential clients to 917 authenticate to the token endpoint as described in OAuth 2.0 918 [RFC6749] Section 2.3.1. 919 client_id_issued_at 920 OPTIONAL. Time at which the Client Identifier was issued. The 921 time is represented as the number of seconds from 922 1970-01-01T0:0:0Z as measured in UTC until the date/time. 924 client_secret_expires_at 925 REQUIRED if "client_secret" is issued. Time at which the 926 "client_secret" will expire or 0 if it will not expire. The time 927 is represented as the number of seconds from 1970-01-01T0:0:0Z as 928 measured in UTC until the date/time. 929 registration_access_token 930 REQUIRED. Access token that is used at the client configuration 931 endpoint to perform subsequent operations upon the client 932 registration. 933 registration_client_uri 934 REQUIRED. The fully qualified URL of the client configuration 935 endpoint for this client. The client MUST use this URL as given 936 when communicating with the client configuration endpoint. 938 Additionally, the Authorization Server MUST return all registered 939 metadata (Section 2) about this client, including any fields 940 provisioned by the authorization server itself. The authorization 941 server MAY reject or replace any of the client's requested metadata 942 values submitted during the registration or update requests and 943 substitute them with suitable values. 945 The response is an "application/json" document with all parameters as 946 top-level members of a JSON object [RFC4627]. 948 Following is a non-normative example response: 950 HTTP/1.1 200 OK 951 Content-Type: application/json 952 Cache-Control: no-store 953 Pragma: no-cache 955 { 956 "registration_access_token": "reg-23410913-abewfq.123483", 957 "registration_client_uri": 958 "https://server.example.com/register/s6BhdRkqt3", 959 "client_id":"s6BhdRkqt3", 960 "client_secret": "cf136dc3c1fc93f31185e5885805d", 961 "client_id_issued_at":2893256800 962 "client_secret_expires_at":2893276800 963 "client_name":"My Example Client", 964 "client_name#ja-Jpan-JP": 965 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", 966 "redirect_uris":["https://client.example.org/callback", 967 "https://client.example.org/callback2"] 968 "scope": "read write dolphin", 969 "grant_types": ["authorization_code", "refresh_token"] 970 "token_endpoint_auth_method": "client_secret_basic", 971 "logo_uri": "https://client.example.org/logo.png", 972 "jwks_uri": "https://client.example.org/my_public_keys.jwks" 973 } 975 5.2. Client Registration Error Response 977 When an OAuth 2.0 error condition occurs, such as the client 978 presenting an invalid registration access token, the authorization 979 server returns an error response appropriate to the OAuth 2.0 token 980 type. For the registration access token, which is an OAuth 2.0 981 bearer token, this error response is defined in Section 3 of OAuth 982 2.0 Bearer Token Usage [RFC6750]. 984 When a registration error condition occurs, the authorization server 985 returns an HTTP 400 status code (unless otherwise specified) with 986 content type "application/json" consisting of a JSON object [RFC4627] 987 describing the error in the response body. 989 The JSON object contains two members: 991 error 992 The error code, a single ASCII string. 993 error_description 994 A human-readable text description of the error for debugging. 996 This specification defines the following error codes: 998 invalid_redirect_uri 999 The value of one or more "redirect_uris" is invalid. 1000 invalid_client_metadata 1001 The value of one of the client metadata (Section 2) fields is 1002 invalid and the server has rejected this request. Note that an 1003 Authorization server MAY choose to substitute a valid value for 1004 any requested parameter of a client's metadata. 1005 invalid_client_id 1006 The value of "client_id" does not match the one assigned to this 1007 client. 1009 Following is a non-normative example of an error response (with line 1010 wraps for display purposes only): 1012 HTTP/1.1 400 Bad Request 1013 Content-Type: application/json 1014 Cache-Control: no-store 1015 Pragma: no-cache 1017 { 1018 "error":"invalid_redirect_uri", 1019 "error_description":"The redirect URI of http://sketchy.example.com 1020 is not allowed for this server." 1021 } 1023 6. IANA Considerations 1025 6.1. OAuth Token Endpoint Authentication Methods Registry 1027 This specification establishes the OAuth Token Endpoint 1028 Authentication Methods registry. 1030 Additional values for use as "token_endpoint_auth_method" metadata 1031 values are registered with a Specification Required ([RFC5226]) after 1032 a two-week review period on the oauth-ext-review@ietf.org mailing 1033 list, on the advice of one or more Designated Experts. However, to 1034 allow for the allocation of values prior to publication, the 1035 Designated Expert(s) may approve registration once they are satisfied 1036 that such a specification will be published. 1038 Registration requests must be sent to the oauth-ext-review@ietf.org 1039 mailing list for review and comment, with an appropriate subject 1040 (e.g., "Request to register token_endpoint_auth_method value: 1041 example"). 1043 Within the review period, the Designated Expert(s) will either 1044 approve or deny the registration request, communicating this decision 1045 to the review list and IANA. Denials should include an explanation 1046 and, if applicable, suggestions as to how to make the request 1047 successful. 1049 IANA must only accept registry updates from the Designated Expert(s) 1050 and should direct all requests for registration to the review mailing 1051 list. 1053 6.1.1. Registration Template 1055 Token Endpoint Authorization Method name: 1056 The name requested (e.g., "example"). This name is case 1057 sensitive. Names that match other registered names in a case 1058 insensitive manner SHOULD NOT be accepted. 1060 Change controller: 1061 For Standards Track RFCs, state "IETF". For others, give the name 1062 of the responsible party. Other details (e.g., postal address, 1063 email address, home page URI) may also be included. 1065 Specification document(s): 1066 Reference to the document(s) that specify the token endpoint 1067 authorization method, preferably including a URI that can be used 1068 to retrieve a copy of the document(s). An indication of the 1069 relevant sections may also be included but is not required. 1071 6.1.2. Initial Registry Contents 1073 The OAuth Token Endpoint Authentication Methods registry's initial 1074 contents are: 1076 o Token Endpoint Authorization Method name: "none" 1077 o Change controller: IETF 1078 o Specification document(s): [[ this document ]] 1080 o Token Endpoint Authorization Method name: "client_secret_post" 1081 o Change controller: IETF 1082 o Specification document(s): [[ this document ]] 1084 o Token Endpoint Authorization Method name: "client_secret_basic" 1085 o Change controller: IETF 1086 o Specification document(s): [[ this document ]] 1088 7. Security Considerations 1090 Since requests to the client registration endpoint result in the 1091 transmission of clear-text credentials (in the HTTP request and 1092 response), the Authorization Server MUST require the use of a 1093 transport-layer security mechanism when sending requests to the 1094 registration endpoint. The server MUST support TLS 1.2 RFC 5246 1095 [RFC5246] and/or TLS 1.0 [RFC2246] and MAY support additional 1096 transport-layer mechanisms meeting its security requirements. When 1097 using TLS, the Client MUST perform a TLS/SSL server certificate 1098 check, per RFC 6125 [RFC6125]. 1100 Since the client configuration endpoint is an OAuth 2.0 protected 1101 resource, it SHOULD have some rate limiting on failures to prevent 1102 the registration access token from being disclosed though repeated 1103 access attempts. 1105 For clients that use redirect-based grant types such as 1106 "authorization_code" and "implicit", authorization servers SHOULD 1107 require clients to register their "redirect_uris". Requiring clients 1108 to do so can help mitigate attacks where rogue actors inject and 1109 impersonate a validly registered client and intercept its 1110 authorization code or tokens through an invalid redirect URI. 1112 The authorization server MUST treat all client metadata as self- 1113 asserted. For instance, a rogue client might use the name and logo 1114 for the legitimate client which it is trying to impersonate. 1115 Additionally, a rogue client might try to use the software identifier 1116 or software version of a legitimate client to attempt to associate 1117 itself on the authorization server instances of the legitimate 1118 client. To counteract this, an authorization server needs to take 1119 steps to mitigate this phishing risk by looking at the entire 1120 registration request and client configuration. For instance, an 1121 authorization server could warn if the domain/site of the logo 1122 doesn't match the domain/site of redirect URIs. An authorization 1123 server could also refuse registration from a known software 1124 identifier that is requesting different redirect URIs or a different 1125 client homepage uri. An authorization server can also present 1126 warning messages to end users about dynamically registered clients in 1127 all cases, especially if such clients have been recently registered 1128 or have not been trusted by any users at the authorization server 1129 before. 1131 In a situation where the authorization server is supporting open 1132 client registration, it must be extremely careful with any URL 1133 provided by the client that will be displayed to the user (e.g. 1134 "logo_uri", "tos_uri", "client_uri", and "policy_uri"). For 1135 instance, a rogue client could specify a registration request with a 1136 reference to a drive-by download in the "policy_uri". The 1137 authorization server SHOULD check to see if the "logo_uri", 1138 "tos_uri", "client_uri", and "policy_uri" have the same host and 1139 scheme as the those defined in the array of "redirect_uris" and that 1140 all of these resolve to valid web pages. 1142 While the client secret can expire, the registration access token 1143 should not expire while a client is still actively registered. If 1144 this token were to expire, a developer or client could be left in a 1145 situation where they have no means of retrieving or updating the 1146 client's registration information. Were that the case, a new 1147 registration would be required, thereby generating a new client 1148 identifier. However, to limit the exposure surface of the 1149 registration access token, the registration access token MAY be 1150 rotated when the developer or client does a read or update operation 1151 on the client's client configuration endpoint. As the registration 1152 access tokens are relatively long-term credentials, and since the 1153 registration access token is a Bearer token and acts as the sole 1154 authentication for use at the client configuration endpoint, it MUST 1155 be protected by the developer or client as described in OAuth 2.0 1156 Bearer Token Usage [RFC6750]. 1158 If a client is deprovisioned from a server, any outstanding 1159 registration access token for that client MUST be invalidated at the 1160 same time. Otherwise, this can lead to an inconsistent state wherein 1161 a client could make requests to the client configuration endpoint 1162 where the authentication would succeed but the action would fail 1163 because the client is no longer valid. To prevent accidental 1164 disclosure from such an erroneous situation, the authorization server 1165 MUST treat all such requests as if the registration access token was 1166 invalid (by returning an HTTP 401 Unauthorized error, as described). 1168 Public clients MAY register with an authorization server using this 1169 protocol, if the authorization server's policy allows them. Public 1170 clients use a "none" value for the "token_endpoint_auth_method" 1171 metadata field and are generally used with the "implicit" grant type. 1172 Often these clients will be short-lived in-browser applications 1173 requesting access to a user's resources and access is tied to a 1174 user's active session at the authorization server. Since such 1175 clients often do not have long-term storage, it's possible that such 1176 clients would need to re-register every time the browser application 1177 is loaded. Additionally, such clients may not have ample opportunity 1178 to unregister themselves using the delete action before the browser 1179 closes. To avoid the resulting proliferation of dead client 1180 identifiers, an authorization server MAY decide to expire 1181 registrations for existing clients meeting certain criteria after a 1182 period of time has elapsed. 1184 Since different OAuth 2.0 grant types have different security and 1185 usage parameters, an authorization server MAY require separate 1186 registrations for a piece of software to support multiple grant 1187 types. For instance, an authorization server might require that all 1188 clients using the "authorization_code" grant type make use of a 1189 client secret for the "token_endpoint_auth_method", but any clients 1190 using the "implicit" grant type do not use any authentication at the 1191 token endpoint. In such a situation, a server MAY disallow clients 1192 from registering for both the "authorization_code" and "implicit" 1193 grant types simultaneously. Similarly, the "authorization_code" 1194 grant type is used to represent access on behalf of an end user, but 1195 the "client_credentials" grant type represents access on behalf of 1196 the client itself. For security reasons, an authorization server 1197 could require that different scopes be used for these different use 1198 cases, and as a consequence it MAY disallow these two grant types 1199 from being registered together by the same client. In all of these 1200 cases, the authorization server would respond with an 1201 "invalid_client_metadata" error response (Section 5.2). 1203 8. Normative References 1205 [IANA.Language] 1206 Internet Assigned Numbers Authority (IANA), "Language 1207 Subtag Registry", 2005. 1209 [JWK] Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web- 1210 key (work in progress), May 2013. 1212 [OAuth.JWT] 1213 Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 1214 (JWT) Bearer Token Profiles for OAuth 2.0", draft-ietf- 1215 oauth-jwt-bearer (work in progress), March 2013. 1217 [OAuth.SAML2] 1218 Campbell, B., Mortimore, C., and M. Jones, "SAML 2.0 1219 Bearer Assertion Profiles for OAuth 2.0", draft-ietf- 1220 oauth-saml2-bearer (work in progress), March 2013. 1222 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1223 Requirement Levels", BCP 14, RFC 2119, March 1997. 1225 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 1226 RFC 2246, January 1999. 1228 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1229 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1230 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1232 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1233 Unique IDentifier (UUID) URN Namespace", RFC 4122, July 1234 2005. 1236 [RFC4627] Crockford, D., "The application/json Media Type for 1237 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1239 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1240 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1241 May 2008. 1243 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1244 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1246 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 1247 Languages", BCP 47, RFC 5646, September 2009. 1249 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1250 Verification of Domain-Based Application Service Identity 1251 within Internet Public Key Infrastructure Using X.509 1252 (PKIX) Certificates in the Context of Transport Layer 1253 Security (TLS)", RFC 6125, March 2011. 1255 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 1256 6749, October 2012. 1258 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1259 Framework: Bearer Token Usage", RFC 6750, October 2012. 1261 Appendix A. Acknowledgments 1263 The authors thank the OAuth Working Group, the User-Managed Access 1264 Working Group, and the OpenID Connect Working Group participants for 1265 their input to this document. In particular, the following 1266 individuals have been instrumental in their review and contribution 1267 to various versions of this document: Amanda Anganes, Derek Atkins, 1268 Tim Bray, Domenico Catalano, Donald Coffin, Vladimir Dzhuvinov, 1269 George Fletcher, Thomas Hardjono, Phil Hunt, William Kim, Torsten 1270 Lodderstedt, Eve Maler, Josh Mandel, Nov Matake, Nat Sakimura, 1271 Christian Scholz, and Hannes Tschofenig. 1273 Appendix B. Client Lifecycle Examples 1275 In the OAuth 2.0 specification [RFC6749], a client is identified by 1276 its own unique Client identifier ("client_id") at each authorization 1277 server that it associates with. Dynamic registration as defined in 1278 this document is one way for a client to get a client identifier and 1279 associate a set of metadata with that identifier. Lack of such a 1280 client identifier is the expected trigger for a client registration 1281 operation. 1283 In many cases, this client identifier is a unique, pairwise 1284 association between a particular running instance of a piece of 1285 client software and a particular running instance of an authorization 1286 server software. In particular: 1288 o A single instance of client software (such as a Web server) 1289 talking to multiple authorization servers will need to register 1290 with each authorization server separately, creating a distinct 1291 client identifier with each authorization server. The client can 1292 not make any assumption that the authorization servers are 1293 correlating separate registrations of the client software together 1294 without further profiles and extensions to this specification 1295 document. The means by which a client discovers and 1296 differentiates between multiple authorization servers is out of 1297 scope for this specification. 1298 o Multiple instances of client software (such as a native 1299 application installed on multiple devices simultaneously) talking 1300 to the same authorization server will need to each register with 1301 that authorization server separately, creating a distinct client 1302 identifier for each copy of the application. The authorization 1303 server cannot make any assumption of correlation between these 1304 clients without further specifications, profiles, and extensions 1305 to this specification. The client can not make any assumption 1306 that the authorization server will correlate separate 1307 registrations of the client software together without further 1308 profiles and extensions to this specification document. 1310 A client identifier (and its associated credentials) could also be 1311 shared between multiple instances of a client. Mechanisms for 1312 sharing client identifiers between multiple instances of a piece of 1313 software (either client or authorization server) are outside the 1314 scope of this specification, as it is expected that every successful 1315 registration request (Section 3.1) results in the issuance of a new 1316 client identifier. 1318 There are several patterns of OAuth client registration that dynamic 1319 registration protocol can enable. The following non-normative 1320 example lifecycle descriptions are not intended to be an exhaustive 1321 list. It is assumed that the authorization server supports the 1322 dynamic registration protocol and that all necessary discovery steps 1323 (which are out of scope for this specification) have already been 1324 performed. 1326 B.1. Open Registration 1327 Open registration, with no authorization required on the client 1328 registration endpoint, works as follows: 1330 a. A client needs to get OAuth 2.0 tokens from an authorization 1331 server, but the client does not have a client identifier for that 1332 authorization server. 1333 b. The client sends an HTTP POST request to the client registration 1334 endpoint at the authorization server and includes its metadata. 1335 c. The authorization server issues a client identifier and returns 1336 it to the client along with a registration access token and a 1337 reference to the client's client configuration endpoint. 1338 d. The client stores the returned response from the authorization 1339 server. At a minimum, it should remember the values of 1340 "client_id", "client_secret" (if present), 1341 "registration_access_token", and "registration_client_uri". 1342 e. The client uses the its "client_id" and "client_secret" (if 1343 provided) to request OAuth 2.0 tokens using any valid OAuth 2.0 1344 flow for which it is authorized. 1345 f. If the client's "client_secret" expires or otherwise stops 1346 working, the client sends an HTTP GET request to the 1347 "registration_client_uri" with the "registration_access_token" as 1348 its authorization. This response will contain the client's 1349 refreshed "client_secret" along with any changed metadata values. 1350 Its "client_id" will remain the same. 1351 g. If the client needs to update its configuration on the 1352 authorization server, it sends an HTTP PUT request to the 1353 "registration_client_uri" with the "registration_access_token" as 1354 its authorization. This response will contain the client's 1355 changed metadata values. Its "client_id" will remain the same. 1356 h. If the client is uninstalled or otherwise deprovisioned, it can 1357 send an HTTP DELETE request to the "registration_client_uri" with 1358 the "registration_access_token" as its authorization. This will 1359 effectively deprovision the client from the authorization server. 1361 B.2. Protected Registration 1363 An authorization server may require an initial access token for 1364 requests to its registration endpoint. While the method by which a 1365 client receives this initial Access token and the method by which the 1366 authorization server validates this initial access token are out of 1367 scope for this specification, a common approach is for the developer 1368 to use a manual pre-registration portal at the authorization server 1369 that issues an initial access token to the developer. This allows 1370 the developer to package the initial access token with different 1371 instances of the client application. While each copy of the 1372 application would get its own client identifier (and registration 1373 access token), all instances of the application would be tied back to 1374 the developer by their shared use of this initial access token. 1376 a. A developer is creating a client to use an authorization server 1377 and knows that instances of the client will dynamically register 1378 at runtime, but that the authorization server requires 1379 authorization at the registration endpoint. 1380 b. The developer visits a manual pre-registration page at the 1381 authorization server and is issued an initial access token in the 1382 form of an OAuth 2.0 Bearer Token [RFC6750]. 1383 c. The developer packages that token with all instances of the 1384 client application. 1385 d. The client needs to get OAuth 2.0 tokens from an authorization 1386 server, but the client does not have a client identifier for that 1387 authorization server. 1388 e. The client sends an HTTP POST request to the client registration 1389 endpoint at the authorization server with its metadata, and the 1390 initial access token as its authorization. 1391 f. The authorization server issues a client identifier and returns 1392 it to the client along with a registration access token and a 1393 reference to the client's client configuration endpoint. 1394 g. The client stores the returned response from the authorization 1395 server. At a minimum, it should know the values of "client_id", 1396 "client_secret" (if present), "registration_access_token", and 1397 "registration_client_uri". 1398 h. The client uses the its "client_id" and "client_secret" (if 1399 provided) to request OAuth 2.0 tokens using any supported OAuth 1400 2.0 flow for which this client is authorized. 1401 i. If the client's "client_secret" expires or otherwise stops 1402 working, the client sends an HTTP GET request to the 1403 "registration_client_uri" with the "registration_access_token" as 1404 its authorization. This response will contain the client's 1405 refreshed "client_secret" along with any metadata values 1406 registered to that client, some of which may have changed. Its 1407 "client_id" will remain the same. 1408 j. If the client needs to update its configuration on the 1409 authorization server, it sends an HTTP PUT request to the 1410 "registration_client_uri" with the "registration_access_token" as 1411 its authorization. The response will contain the client's 1412 changed metadata values. Its "client_id" will remain the same. 1413 k. If the client is uninstalled or otherwise deprovisioned, it can 1414 send an HTTP DELETE request to the "registration_client_uri" with 1415 the "registration_access_token" as its authorization. This will 1416 effectively deprovision the client from the Authorization Server. 1418 B.3. Developer Automation 1420 The dynamic registration protocol can also be used in place of a 1421 manual registration portal, for instance as part of an automated 1422 build and deployment process. In this scenario, the authorization 1423 server may require an initial access token for requests to its 1424 registration endpoint, as described in Protected Registration 1425 (Appendix B.2). However, here the developer manages the client's 1426 registration instead of the client itself. Therefore, the initial 1427 registration token and registration access token all remain with the 1428 developer. The developer packages the client identifier with the 1429 client as part of the client's build process. 1431 a. A developer is creating a client to use an authorization server 1432 and knows that instances of the client will not dynamically 1433 register at runtime. 1434 b. If required for registrations at the authorization server, the 1435 developer performs an OAuth 2.0 authorization of his build 1436 environment against the authorization server using any valid 1437 OAuth 2.0 flow. The authorization server and is issues an 1438 initial access token to the developer's build environment in the 1439 form of an OAuth 2.0 Bearer Token [RFC6750]. 1440 c. The developer configures his build environment to send an HTTP 1441 POST request to the client registration endpoint at the 1442 authorization server with the client's metadata, using the 1443 initial access token obtained the previous step as an OAuth 2.0 1444 Bearer Token [RFC6750]. 1445 d. The authorization server issues a client identifier and returns 1446 it to the developer along with a registration access token and a 1447 reference to the client's client configuration endpoint. 1448 e. The developer packages the client identifier with the client and 1449 stores the "registration_access_token", and 1450 "registration_client_uri" in the deployment system. 1451 f. The client uses the its "client_id" and "client_secret" (if 1452 provided) to request OAuth 2.0 tokens using any supported OAuth 1453 2.0 flow. 1454 g. If the client's "client_secret" expires or otherwise stops 1455 working, the developer's deployment system sends an HTTP GET 1456 request to the "registration_client_uri" with the 1457 "registration_access_token" as its authorization. This response 1458 will contain the client's refreshed "client_secret" along with 1459 any changed metadata values. Its "client_id" will remain the 1460 same. These new values will then be packaged and shipped to or 1461 retrieved by instances of the client, if necessary. 1462 h. If the developer needs to update its configuration on the 1463 authorization server, the deployment system sends an HTTP PUT 1464 request to the "registration_client_uri" with the 1465 "registration_access_token" as its authorization. This response 1466 will contain the client's changed metadata values. Its 1467 "client_id" will remain the same. These new values will then be 1468 packaged and shipped to or retrieved by instances of the client, 1469 if necessary. 1470 i. If the client is deprovisioned, the developer's deployment system 1471 can send an HTTP DELETE request to the "registration_client_uri" 1472 with the "registration_access_token" as its authorization. This 1473 will effectively deprovision the client from the authorization 1474 server and prevent any instances of the client from functioning. 1476 Appendix C. Document History 1478 [[ to be removed by the RFC editor before publication as an RFC ]] 1480 -14 1482 o Added software_id and software_version metadata fields 1483 o Added direct references to RFC6750 errors in read/update/delete 1484 methods 1486 -13 1488 o Fixed broken example text in registration request and in delete 1489 request 1490 o Added security discussion of separating clients of different grant 1491 types 1492 o Fixed error reference to point to RFC6750 instead of RFC6749 1493 o Clarified that servers must respond to all requests to 1494 configuration endpoint, even if it's just an error code 1495 o Lowercased all Terms to conform to style used in RFC6750 1497 -12 1499 o Improved definition of Initial Access Token 1500 o Changed developer registration scenario to have the Initial Access 1501 Token gotten through a normal OAuth 2.0 flow 1502 o Moved non-normative client lifecycle examples to appendix 1503 o Marked differentiating between auth servers as out of scope 1504 o Added protocol flow diagram 1505 o Added credential rotation discussion 1506 o Called out Client Registration Endpoint as an OAuth 2.0 Protected 1507 Resource 1508 o Cleaned up several pieces of text 1510 -11 1512 o Added localized text to registration request and response 1513 examples. 1514 o Removed "client_secret_jwt" and "private_key_jwt". 1515 o Clarified "tos_uri" and "policy_uri" definitions. 1516 o Added the OAuth Token Endpoint Authentication Methods registry for 1517 registering "token_endpoint_auth_method" metadata values. 1518 o Removed uses of non-ASCII characters, per RFC formatting rules. 1520 o Changed "expires_at" to "client_secret_expires_at" and "issued_at" 1521 to "client_id_issued_at" for greater clarity. 1522 o Added explanatory text for different credentials (Initial Access 1523 Token, Registration Access Token, Client Credentials) and what 1524 they're used for. 1525 o Added Client Lifecycle discussion and examples. 1526 o Defined Initial Access Token in Terminology section. 1528 -10 1530 o Added language to point out that scope values are service-specific 1531 o Clarified normative language around client metadata 1532 o Added extensibility to token_endpoint_auth_method using absolute 1533 URIs 1534 o Added security consideration about registering redirect URIs 1535 o Changed erroneous 403 responses to 401's with notes about token 1536 handling 1537 o Added example for initial registration credential 1539 -09 1541 o Added method of internationalization for Client Metadata values 1542 o Fixed SAML reference 1544 -08 1546 o Collapsed jwk_uri, jwk_encryption_uri, x509_uri, and 1547 x509_encryption_uri into a single jwks_uri parameter 1548 o Renamed grant_type to grant_types since it's a plural value 1549 o Formalized name of "OAuth 2.0" throughout document 1550 o Added JWT Bearer Assertion and SAML 2 Bearer Assertion to example 1551 grant types 1552 o Added response_types parameter and explanatory text on its use 1553 with and relationship to grant_types 1555 -07 1557 o Changed registration_access_url to registration_client_uri 1558 o Fixed missing text in 5.1 1559 o Added Pragma: no-cache to examples 1560 o Changed "no such client" error to 403 1561 o Renamed Client Registration Access Endpoint to Client 1562 Configuration Endpoint 1563 o Changed all the parameter names containing "_url" to instead use 1564 "_uri" 1565 o Updated example text for forming Client Configuration Endpoint URL 1567 -06 1568 o Removed secret_rotation as a client-initiated action, including 1569 removing client secret rotation endpoint and parameters. 1570 o Changed _links structure to single value registration_access_url. 1571 o Collapsed create/update/read responses into client info response. 1572 o Changed return code of create action to 201. 1573 o Added section to describe suggested generation and composition of 1574 Client Registration Access URL. 1575 o Added clarifying text to PUT and POST requests to specify JSON in 1576 the body. 1577 o Added Editor's Note to DELETE operation about its inclusion. 1578 o Added Editor's Note to registration_access_url about alternate 1579 syntax proposals. 1581 -05 1583 o changed redirect_uri and contact to lists instead of space 1584 delimited strings 1585 o removed operation parameter 1586 o added _links structure 1587 o made client update management more RESTful 1588 o split endpoint into three parts 1589 o changed input to JSON from form-encoded 1590 o added READ and DELETE operations 1591 o removed Requirements section 1592 o changed token_endpoint_auth_type back to 1593 token_endpoint_auth_method to match OIDC who changed to match us 1595 -04 1597 o removed default_acr, too undefined in the general OAuth2 case 1598 o removed default_max_auth_age, since there's no mechanism for 1599 supplying a non-default max_auth_age in OAuth2 1600 o clarified signing and encryption URLs 1601 o changed token_endpoint_auth_method to token_endpoint_auth_type to 1602 match OIDC 1604 -03 1606 o added scope and grant_type claims 1607 o fixed various typos and changed wording for better clarity 1608 o endpoint now returns the full set of client information 1609 o operations on client_update allow for three actions on metadata: 1610 leave existing value, clear existing value, replace existing value 1611 with new value 1613 -02 1615 o Reorganized contributors and references 1616 o Moved OAuth references to RFC 1617 o Reorganized model/protocol sections for clarity 1618 o Changed terminology to "client register" instead of "client 1619 associate" 1620 o Specified that client_id must match across all subsequent requests 1621 o Fixed RFC2XML formatting, especially on lists 1623 -01 1625 o Merged UMA and OpenID Connect registrations into a single document 1626 o Changed to form-paramter inputs to endpoint 1627 o Removed pull-based registration 1629 -00 1631 o Imported original UMA draft specification 1633 Authors' Addresses 1635 Justin Richer (editor) 1636 The MITRE Corporation 1638 Email: jricher@mitre.org 1640 John Bradley 1641 Ping Identity 1643 Email: ve7jtb@ve7jtb.com 1645 Michael B. Jones 1646 Microsoft 1648 Email: mbj@microsoft.com 1649 URI: http://self-issued.info/ 1651 Maciej Machulak 1652 Newcastle University 1654 Email: m.p.machulak@ncl.ac.uk 1655 URI: http://ncl.ac.uk/