idnits 2.17.1
draft-hardjono-oauth-dynreg-00.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
** The document seems to lack an IANA Considerations section. (See Section
2.2 of https://www.ietf.org/id-info/checklist for how to handle the case
when there are no actions for IANA.)
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 (May 1, 2011) is 4738 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)
== Unused Reference: 'RFC2617' is defined on line 814, but no explicit
reference was found in the text
** Obsolete normative reference: RFC 4627 (ref. 'JSON') (Obsoleted by RFC
7158, RFC 7159)
-- Possible downref: Non-RFC (?) normative reference: ref. 'OAuth-Sig'
** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615,
RFC 7616, RFC 7617)
** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615)
Summary: 4 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group T. Hardjono, Ed.
3 Internet-Draft MIT Kerberos Consortium
4 Intended status: Standards Track M. Machulak
5 Expires: November 2, 2011 Newcastle University
6 E. Maler
7 XMLgrrl.com
8 C. Scholz
9 COM.lounge GmbH
10 May 1, 2011
12 OAuth Dynamic Client Registration Protocol
13 draft-hardjono-oauth-dynreg-00
15 Abstract
17 This specification proposes an OAuth Dynamic Client Registration
18 protocol.
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 November 2, 2011.
37 Copyright Notice
39 Copyright (c) 2011 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. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 4
58 3. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 5
59 3.1. The client needs to be uniquely identifiable by the
60 authorization server . . . . . . . . . . . . . . . . . . . 5
61 3.2. The authorization server must collect metadata about a
62 client for later user interaction . . . . . . . . . . . . 5
63 3.3. The authorization server must have the option of
64 strongly authenticating the client and its metadata . . . 5
65 3.4. Dynamic client registration must be possible from both
66 web-server applications and applications with other
67 capabilities and limitations, such as native
68 applications . . . . . . . . . . . . . . . . . . . . . . . 6
69 3.5. Transaction integrity must be ensured in large
70 deployments where data propagation can be an issue . . . . 6
71 3.6. UMA design principles and requirements . . . . . . . . . . 6
72 4. Analysis of Registration Flow Options . . . . . . . . . . . . 7
73 5. Discovery of Server's Client Registration Endpoint . . . . . . 8
74 6. Client Registration with Pushed Metadata . . . . . . . . . . . 9
75 6.1. Client Registration Request . . . . . . . . . . . . . . . 9
76 6.2. Client Registration Response . . . . . . . . . . . . . . . 10
77 6.3. Error Response . . . . . . . . . . . . . . . . . . . . . . 11
78 7. Client Registration with Pushed URL and Pulled Metadata . . . 12
79 7.1. Client Registration Request . . . . . . . . . . . . . . . 13
80 7.2. Client Discovery . . . . . . . . . . . . . . . . . . . . . 14
81 7.3. Client Registration Response . . . . . . . . . . . . . . . 15
82 7.4. Error Response . . . . . . . . . . . . . . . . . . . . . . 16
83 8. Native Application Client Registration . . . . . . . . . . . . 17
84 9. Security Considerations . . . . . . . . . . . . . . . . . . . 18
85 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18
86 11. Document History . . . . . . . . . . . . . . . . . . . . . . . 18
87 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19
88 12.1. Normative References . . . . . . . . . . . . . . . . . . . 19
89 12.2. Non-Normative References . . . . . . . . . . . . . . . . . 19
90 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 20
92 1. Introduction
94 This informal draft discusses a number of requirements for and
95 approaches to automatic registration of clients with an OAuth
96 authorization server, with special emphasis on the needs of the
97 OAuth-based User-Managed Access protocol [UMA-Core].
99 In some use-case scenarios it is desirable or necessary to allow
100 OAuth clients to obtain authorization from an OAuth authorization
101 server without the two parties having previously interacted.
102 Nevertheless, in order for the authorization server to accurately
103 represent to end-users which client is seeking authorization to
104 access the end-user's resources, a method for automatic and unique
105 registration of clients is needed.
107 The goal of this proposed registration protocol is for an
108 authorization server to provide a client with a client identifier and
109 optionally a client secret in a dynamic fashion. To accomplish this,
110 the authorization server must first be provided with information
111 about the client, with the client-name being the minimal information
112 provided. In practice, additional information will need to be
113 furnished to the authorization server, such as the client's homepage,
114 icon, description, and so on.
116 The dynamic registration protocol proposed here is envisioned to be
117 an additional task to be performed by the OAuth authorization server,
118 namely registration of a new client identifier and optional secret
119 and the issuance of this information to the client. This task would
120 occur prior to the point at which the client wields its identifier
121 and secret at the authorization server in order to obtain an access
122 token in normal OAuth fashion.
124 1.1. Notational Conventions
126 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT',
127 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this
128 document are to be interpreted as described in [RFC2119].
130 Unless otherwise noted, all the protocol parameter names and values
131 are case sensitive.
133 1.2. Terminology
135 resource server
136 A server capable of accepting and responding to protected
137 resource requests.
139 resource owner
140 An entity capable of granting access to a protected resource.
142 client
143 An application obtaining authorization and making protected
144 resource requests.
146 authorization server
147 A server capable of issuing tokens after successfully
148 authenticating the resource owner and obtaining authorization.
149 The authorization server may be the same server as the resource
150 server, or a separate entity.
152 authorization manager
153 An UMA-defined variant of an authorization server that carries
154 out an authorizing user's policies governing access to a
155 protected resource.
157 end-user authorization endpoint
158 The authorization server's HTTP endpoint capable of
159 authenticating the end-user and obtaining authorization.
161 token endpoint
162 The authorization server's HTTP endpoint capable of issuing
163 tokens and refreshing expired tokens.
165 client identifier
166 An unique identifier issued to the client to identify itself to
167 the authorization server. Client identifiers may have a
168 matching secret.
170 client registration endpoint The authorization server's HTTP
171 endpoint capable of issuing client identifiers and optional
172 client secrets.
174 2. Use Cases
176 The UMA protocol involves two instances of OAuth flows. In the
177 first, an end-user introduces a host (essentially an enhanced OAuth
178 resource server) to an authorization manager (an enhanced OAuth
179 authorization server) as a client of it, possibly without that host
180 having obtained client identification information from that server
181 previously. In the second, a requester (an enhanced OAuth client)
182 approaches a host and authorization manager to get and use an access
183 token in approximately the normal OAuth fashion, again possibly
184 without that client having obtained client identification information
185 from that server previously. Both the host-as-client and the
186 requester-as-client thus may need dynamic client registration in
187 order for the UMA protocol flow to proceed.
189 The needs for inter-party trust vary in different UMA use cases. In
190 lightweight Web circumstances such as person-to-person calendar
191 sharing, dynamic registration is entirely appropriate. In cases
192 where high-sensitivity information is being protected or where a
193 regulatory environment puts constraints on the building of trust
194 relationships, such as sharing health records with medical
195 professionals or giving access to tax records to outsourced
196 bookkeeping staff, static means of provisioning client identifiers
197 may be imposed.
199 More information about UMA use cases is available at [UMA-UC].
201 3. Requirements
203 Following are proposed requirements for dynamic client registration.
205 3.1. The client needs to be uniquely identifiable by the authorization
206 server
208 In order for an authorization server to do proper user-delegated
209 authorization and prevent unauthorized access it must be able to
210 identify clients uniquely. As is done today in OAuth, the client
211 identifier (and optional secret) should thus be issued by the
212 authorization server and not simply accepted as proposed by the
213 client.
215 3.2. The authorization server must collect metadata about a client for
216 later user interaction
218 In order for the authorization server to describe a client to an end-
219 user in an authorization step it needs information about the client.
220 This can be the client name at a minimum, but today servers usually
221 request at least a description, a homepage URL, and an icon when
222 doing manual registration.
224 3.3. The authorization server must have the option of strongly
225 authenticating the client and its metadata
227 In order to prevent spoofing of clients and enable dynamic building
228 of strong trust relationships, the authorization server should have
229 the option to verify the provided information. This might be solved
230 using message signature verification; relatively weaker
231 authentication might be achieved in a simpler way by pulling metadata
232 from a trusted client URL.
234 3.4. Dynamic client registration must be possible from both web-server
235 applications and applications with other capabilities and
236 limitations, such as native applications
238 In the UMA context, alternative types of applications might serve as
239 both hosts (for example, as a device-based personal data store) and
240 requesters (for example, to subscribe to a calendar or view a photo).
241 Such applications, particularly native applications, may have special
242 limitations, so new solutions to meeting the set of requirements
243 presented here may be needed. We anticipate that each instance of a
244 native application (that is, the specific instance running on each
245 device) that is installed and run by the same user may need the
246 option of getting a unique client identifier. In this case, there
247 are implications around gathering and displaying enough information
248 to ensure that the end-user is delegating authorization to the
249 intended application.
251 3.5. Transaction integrity must be ensured in large deployments where
252 data propagation can be an issue
254 When a client sends information to a server endpoint, it might take
255 time for this data to propagate through big server installations that
256 spread across various data centers. Care needs to be taken that
257 subsequent interactions with the user after the registration process,
258 such as an authorization request, show the correct data.
260 In the UMA context, dynamic registration of a host at an AM is almost
261 certain to take place in the middle of an introduction and
262 authorization process mediated by the end-user; even though the host
263 needs a client identifier from the AM no matter which end-user caused
264 the registration process to take place, the end-user may need to wait
265 for the registration sub-process to finish in order to continue with
266 the overall process. It may be necessary to ensure that the host
267 interacts with the same AM server throughout.
269 3.6. UMA design principles and requirements
271 In addition to general requirements for dynamic client registration,
272 UMA seeks to optimize for the design principles and requirements
273 found in the UMA Requirements document [UMA-Reqs], most particularly:
275 o DP1: Simple to understand, implement in an interoperable fashion,
276 and deploy on an Internet-wide scale
278 o DP6: Able to be combined and extended to support a variety of use
279 cases and emerging application functionality
281 o DP8: Avoid adding crypto requirements beyond what existing web app
282 implementations do today
284 o DP10: Complexity should be borne by the authorization endpoint vs.
285 other endpoints
287 4. Analysis of Registration Flow Options
289 This section analyzes some options for exchanging client metadata for
290 a client identifier and optional secret.
292 It currently seems impossible to specify a single registration flow
293 that will satisfy all requirements, deployment needs, and client
294 types. This document, therefore, presents as small a variety of
295 options as possible. If it is possible to construct a single unified
296 flow in the ultimate design, all other things being equal this would
297 be preferred.
299 Client provides metadata on every request
300 In this approach, the client passes all necessary metadata such
301 as its name and icon on every request to the authorization
302 server, and the client doesn't wield a client identifier as
303 such. This option makes it more difficult (though not
304 impossible) to meet the first and second requirements since
305 different clients could theoretically represent themselves to
306 an authorization server with the same metadata and the same
307 client could represent itself on subsequent visits with
308 different metadata. Also, today's OAuth protocol requires the
309 use of a client identifier. Because of the UMA simplicity
310 principle we do not recommend this flow option and and have not
311 provided a candidate solution.
313 Client pushes metadata
314 In this approach, the client discovers the registration
315 endpoint of the authorization server and sends its metadata
316 directly to that endpoint in a standard format. The
317 authorization server answers with a client identifier and
318 optional secret in the response. This approach may be
319 necessary in cases where the client is behind a firewall, but
320 strong authentication of the client metadata may be more
321 difficult or costly with this approach than with a "pull"
322 approach, discussed just below. Further, this approach is
323 problematic in the case of applications that can't function as
324 POST-capable web servers. A proposal for "push" is presented
325 in this document.
327 Client pushes URL, server pulls metadata from it
328 In this approach, the client sends only a URL to the
329 authorization server, which then uses that URL to pull metadata
330 about the client in some standard format, returning
331 identification information in the response to the initial
332 request. This approach more easily allows for strong
333 authentication of clients because the metadata can be
334 statically signed. (The message containing the URL could be
335 signed as well.) However, caution should be exercised around
336 the propagation issue if the initial URL push is made to a
337 server different from the one the end-user is interacting with.
338 Further, this approach is problematic in the case of
339 applications that cannot themselves serve as "pull-able"
340 metadata repositories. A proposal for "pull" is presented in
341 this document.
343 Native-app client collaborates with home-base web app to provide
344 metadata
345 An instance of a native application (for example, on a mobile
346 device) may have difficulty directly conveying trustworthy
347 metadata but may also have difficulty providing a trustworthy
348 third-party source from which a server can pull metadata. This
349 document explores one option for meeting the requirements, but
350 does not present a full-fledged proposal.
352 5. Discovery of Server's Client Registration Endpoint
354 Regardless of flow option, the client needs to discover the
355 authorization server's client registration endpoint.
357 The client MUST use the [RFC5785] and [hostmeta] discovery mechanisms
358 to learn the URI of the client registration endpoint at the
359 authorization server. The authorization server MUST provide a host-
360 meta document containing a Link element with a rel value of:
361 "http://oauth.net/as/registration"
363 For example:
365
366 http://server.example.com
367
369 Client Registration Endpoint
370
371
373 6. Client Registration with Pushed Metadata
375 This registration flow works as follows:
377 1. The client sends its metadata in JSON form to the client
378 registration endpoint. The client MUST send its name,
379 description, and redirection URI and MAY send a URI for its icon.
380 The client MAY sign the metadata as a JSON Token issuer, using
381 the mechanisms defined in [OAuth-Sig].
383 2. The authorization server checks the data, verifying the signature
384 as necessary, and returns a client identifier and an optional
385 client secret.
387 +--------+ +---------------+
388 | Client |--(A)--- Registration Request --->| Authorization |
389 | | with Metadata | Server |
390 | | | |
391 | |<-(B)----Registration Response ---| |
392 | | with Client ID Info | |
393 +--------+ +---------------+
395 Figure 1: Client Registration Flow with Pushed Metadata
397 6.1. Client Registration Request
399 The client sends a JSON formatted document to the client registration
400 endpoint. The client includes the following parameters in the
401 request:
403 type
404 REQUIRED. This parameter must be set to "push".
406 client_name
407 REQUIRED. This field contains a human-readable name of the
408 client.
410 client_url
411 REQUIRED. This field contains the URL of the homepage of the
412 client.
414 client_description
415 REQUIRED. This field contains a text description of the
416 client.
418 client_icon
419 OPTIONAL. This field contains a URL for an icon for the
420 client.
422 redirect_url
423 REQUIRED. This field contains the URL to which the
424 authorization server should send its response.
426 The client MAY include additional metadata in the request and the
427 authorization server MAY ignore this additional information.
429 For example, the client might send the following request:
431 POST /register HTTP/1.1
432 Host: server.example.com
433 Content-Type: application/json
435 {
436 type: "push",
437 client_name: "Online Photo Gallery",
438 client_url: "http://onlinephotogallery.com",
439 client_description: "Uploading and also editing capabilities!",
440 client_icon: "http://onlinephotogallery.com/icon.png",
441 redirect_url: "https://onlinephotogallery.com/client_reg"
442 }
444 The parameters are included in the entity body of the HTTP request
445 using the "application/json" media type as defined by [JSON]. The
446 parameters are serialized into a JSON structure by adding each
447 parameter at the highest structure level. Parameter names and string
448 values are included as JSON strings.
450 6.2. Client Registration Response
452 After receiving and verifying information received from the client,
453 the authorization server issues a client identifier and an optional
454 client secret, and constructs the response by adding the following
455 parameters to the entity body of the HTTP response with a 200 status
456 code (OK):
458 client_id
459 REQUIRED.
461 client_secret
462 OPTIONAL.
464 issued_at
465 OPTIONAL. Specifies the timestamp when the identifier was
466 issued. The timestamp value MUST be a positive integer. The
467 value is expressed in the number of seconds since January 1,
468 1970 00:00:00 GMT.
470 expires_in
471 OPTIONAL; if supplied, the "issued_at" parameter is REQUIRED.
472 Specifies the valid lifetime, in seconds, of the identifier.
473 The value is represented in base 10 ASCII.
475 The parameters are included in the entity body of the HTTP response
476 using the "application/json" media type as defined by [JSON]. The
477 parameters are serialized into a JSON structure by adding each
478 parameter at the highest structure level. Parameter names and string
479 values are included as JSON strings.
481 The authorization server MUST include the HTTP "Cache-Control"
482 response header field with a value of "no-store" in any response
483 containing "client_secret".
485 For example, the authorization server might return the following
486 response:
488 HTTP/1.1 200 OK
489 Content-Type: application/json
490 Cache-Control: no-store
492 {
493 client_id: "5UO9XcL4TQTa",
494 client_secret: "WdRKN3zeTc20"
495 }
497 6.3. Error Response
499 If the request for registration is invalid or unauthorized, the
500 authorization server constructs the response by adding the following
501 parameters to the entity body of the HTTP response with a 400 status
502 code (Bad Request) using the "application/json" media type:
504 o "error" (REQUIRED).
506 o "error_description" (OPTIONAL). Human-readable text providing
507 additional information, used to assist in the understanding and
508 resolution of the error occurred.
510 o "error_uri" (OPTIONAL). A URI identifying a human-readable web
511 page with information about the error, used to provide the end-
512 user with additional information about the error.
514 An example error response (with line breaks for readability):
516 HTTP/1.1 400 Bad Request
517 Content-Type: application/json
518 Cache-Control: no-store
520 {
521 "error": "unauthorized_client",
522 "description": "This client is not on the
523 white list of this Authorization Server."
524 }
526 7. Client Registration with Pushed URL and Pulled Metadata
528 This registration flow works as follows:
530 1. The client sends its metadata URI to the client registration
531 endpoint. The client MAY sign the metadata as a JSON Token
532 issuer, using the mechanisms defined in [OAuth-Sig].
534 2. The authorization server verifies the signature as necessary, and
535 uses the [RFC5785] and [hostmeta] discovery mechanisms on this
536 URI to retrieve the host-meta document describing the client.
537 The host-meta document MUST contain the client name, description,
538 and redirection URI, and MAY contain a URI for the client icon.
540 +--------+ +---------------+
541 | Client |--(A)--- Registration Request --->| Authorization |
542 | | with URL | Server |
543 | | | |
544 | |<-(B)--- Client Discovery --------| |
545 | | | |
546 | |--(C)---- Host-Meta Document ---->| |
547 | | | |
548 | |<-(D)--- Registration Response ---| |
549 | | with Client ID Info | |
550 +--------+ +---------------+
552 Figure 2: Client Registration Flow with Pushed URL and Pulled
553 Metadata
555 7.1. Client Registration Request
557 The client sends a JSON formatted document to the client registration
558 endpoint. The client includes the following parameters in the
559 request:
561 type
562 REQUIRED. This parameter must be set to "pull".
564 client_url
565 REQUIRED. This field contains the URL of the homepage of the
566 client.
568 The client MUST NOT include other metadata parameters, such as those
569 defined in the pushed-metadata scenario.
571 For example, the client might send the following request:
573 POST /register HTTP/1.1
574 Host: server.example.com
575 Content-Type: application/json
577 {
578 type: "pull",
579 url: "http://onlinephotogallery.com"
580 }
582 The parameters are included in the entity body of the HTTP request
583 using the "application/json" media type as defined by [JSON]. The
584 parameters are serialized into a JSON structure by adding each
585 parameter at the highest structure level. Parameter names and string
586 values are included as JSON strings.
588 7.2. Client Discovery
590 The authorization server evaluates this request and MAY perform a
591 [RFC5785] and [hostmeta] discovery mechanism on the provided URL to
592 the host-meta document for the client.
594 For example:
596 GET /.well-known/host-meta HTTP/1.1
597 Host: onlinephotogallery.com
599 The authorization server retrieves the host-meta document, which MUST
600 contain:
602 o A "Property" element with a "type" value of
603 "http://oauth.net/client/name" containing the human-readable
604 client name. (REQUIRED)
606 o A "Property" element with a "type" value of
607 "http://oauth.net/client/description" containing the human
608 readable description of the client. (REQUIRED)
610 o A "Link" element with a "rel" value of
611 "http://oauth.net/client/redirect_uri" (REQUIRED).
613 o A "Link" element with a "rel" value of
614 "http://oauth.net/client/uri" (REQUIRED).
616 o A "Link" element with a "rel" value of
617 "http://oauth.net/client/icon" (OPTIONAL).
619 For example:
621
622 http://onlinephotogallery.com
623
624 Online Photo Gallery
625
626
627 Really nice Online Photo Gallery!
628
629
631 Client URI
632
633
635 Client Redirect URI
636
637
639 Client Icon
640
641
643 7.3. Client Registration Response
645 After receiving and verifying information retrieved from the client,
646 the authorization server issues the client identifier and an optional
647 client secret, and constructs the response by adding the following
648 parameters to the entity body of the HTTP response with a 200 status
649 code (OK):
651 o "client_id" (REQUIRED)
653 o "client_secret" (OPTIONAL)
655 The parameters are included in the entity body of the HTTP response
656 using the "application/json" media type as defined by [JSON]. The
657 parameters are serialized into a JSON structure by adding each
658 parameter at the highest structure level. Parameter names and string
659 values are included as JSON strings.
661 The authorization server MUST include the HTTP "Cache-Control"
662 response header field with a value of "no-store" in any response
663 containing the "client_secret".
665 For example the authorization server might return the following
666 response:
668 HTTP/1.1 200 OK
669 Content-Type: application/json
670 Cache-Control: no-store
672 {
673 "client_id":"5UO9XcL4TQTa",
674 "client_secret":"WdRKN3zeTc20"
675 }
677 7.4. Error Response
679 If the request for registration is invalid or unauthorized, the
680 authorization server constructs the response by adding the following
681 parameters to the entity body of the HTTP response with a 400 status
682 code (Bad Request) using the "application/json" media type:
684 o "error" (REQUIRED). A single error code.
686 o "error_description" (OPTIONAL). Human-readable text providing
687 additional information, used to assist in the understanding and
688 resolution of the error occurred.
690 o "error_uri" (OPTIONAL). A URI identifying a human-readable web
691 page with information about the error, used to provide the end-
692 user with additional information about the error.
694 An example error response (with line breaks for readability):
696 HTTP/1.1 400 Bad Request
697 Content-Type: application/json
698 Cache-Control: no-store
700 {
701 "error": "unauthorized_client",
702 "description": "This client is not on the
703 white list of this Authorization Server."
704 }
706 If the host-meta discovery was not successful, the authorization
707 server MUST use the error code "hostmeta_error".
709 An example error response (with line breaks for readability):
711 HTTP/1.1 404 Not Found
712 Content-Type: application/json
713 Cache-Control: no-store
715 {
716 "error": "hostmeta_error",
717 "description": "The hostmeta document could
718 not be retrieved from the URL."
719 }
721 8. Native Application Client Registration
723 For a native application serving as an UMA host, we anticipate that
724 the need for dynamic client registration to introduce this app to an
725 UMA authorization manager may typically happen only once (or very
726 infrequently), likely to a single authorization manager, and
727 registration could usefully take place at the time the app is
728 provisioned onto a device. By contrast, for a native app serving as
729 an UMA requester, it may need to register at multiple authorization
730 managers over time when seeking access tokens, at moments much later
731 than the original provisioning of the app onto the device.
733 When a native application is provisioned on a device, such as through
734 an app store model, often it has an associated "home base" web server
735 application component with which it registers (outside of any UMA-
736 related or OAuth-related interactions). This pairwise relationship
737 can be exploited in a number of ways to allow trustable, unique
738 metadata to be conveyed to an OAuth server and for this instance of
739 the app to receive a client identifier and optional secret. We have
740 discussed "device-initiated" and "home base-initiated" pattern
741 options for OAuth dynamic client registration in these circumstances.
742 Device-initiated flows seem more generically applicable (for example,
743 for both UMA host and UMA requester needs). However, a home base-
744 initiated flow may be preferable in case it is necessary to pre-
745 determine a trust level towards an OAuth server. In this case, the
746 home base server could initiate the registration process if and only
747 if there exists a trust relationship between the two parties.
749 Following is one option for a device-initiated flow:
751 1. User provisions native app on device and registers with and
752 authenticates to app's home-base web application.
754 2. Home base provisions native app with home base-signed metadata.
756 3. Whenever user tries to use native app to access a protected
757 resource, native app provides home base-provided metadata to
758 server.
760 4. Server verifies home base signature by pulling public key from
761 home base URL and generates client identifier and secret for
762 native app.
764 5. Server returns client identifier and secret to native app.
766 9. Security Considerations
768 Following are some security considerations:
770 o No client authentication: The server should treat unsigned pushed
771 client metadata as self-asserted.
773 o Weak client authentication: The server should treat unsigned
774 pulled client metadata as self-asserted unless the the domain of
775 the client matches the client metadata URL and the URL is well-
776 known and trusted.
778 o Strong client authentication: The server should treat signed
779 client metadata (pushed or pulled) and a signed metadata URL as
780 self-asserted unless it can verify the signature as being from a
781 trusted source.
783 10. Acknowledgments
785 The authors thank the User-Managed Access Work Group participants,
786 particularly the following, for their input to this document:
788 o Domenico Catalano
790 o George Fletcher
792 o Nat Sakimura
794 11. Document History
796 [[ to be removed by RFC editor before publication as an RFC ]]
798 12. References
800 12.1. Normative References
802 [JSON] Crockford, D., "The application/json Media Type for
803 JavaScript Object Notation (JSON)", 2006,
804 .
806 [OAuth-Sig]
807 Balfanz, D., "OAuth Signature proposals", 2010, .
811 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
812 Requirement Levels", BCP 14, RFC 2119, March 1997.
814 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
815 Leach, P., Luotonen, A., and L. Stewart, "HTTP
816 Authentication: Basic and Digest Access Authentication",
817 RFC 2617, June 1999.
819 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
820 Uniform Resource Identifiers (URIs)", RFC 5785,
821 April 2010.
823 [hostmeta]
824 Hammer-Lahav, E., "Web Host Metadata", 2010, .
828 12.2. Non-Normative References
830 [UMA-Core]
831 Scholz, C., "UMA Requirements", 2010, .
835 [UMA-Reqs]
836 Maler, E., "UMA Requirements", 2010, .
840 [UMA-UC] Akram, H., "UMA Explained", 2010, .
844 Authors' Addresses
846 Thomas Hardjono (editor)
847 MIT Kerberos Consortium
849 Phone:
850 Fax:
851 Email: hardjono@mit.edu
852 URI:
854 Maciej Machulak
855 Newcastle University
857 Email: m.p.machulak@ncl.ac.uk
858 URI: http://ncl.ac.uk/
860 Eve Maler
861 XMLgrrl.com
863 Email: eve@xmlgrrl.com
864 URI: http://www.xmlgrrl.com
866 Christian Scholz
867 COM.lounge GmbH
869 Phone:
870 Fax:
871 Email:
872 URI: