Subject: [OAUTH-WG] Registration: HAL _links structure and client self-URL

From: Justin Richer <[email-masked]>
Date: Mon, 11 Feb 2013 16:14:37 -0500

Draft -05 of OAuth Dynamic Client Registration [1] returns a URL pointer 
for the client to perform update and secret rotation actions. This 
functionality arose from discussions on the list about moving towards a 
more RESTful pattern, and Nat Sakimura proposed this approach in the 
OpenID Connect Working Group. This URL may be distinct from the Client 
Registration Endpoint URL, but draft -05 makes no promises as to its 
content, form, or structure, though it does contain implementor's notes 
on possible methods.

Two questions arise from this change:
  - The semantics of returning the client manipulation URL
  - The syntax (derived from HAL for JSON [2], an individual I-D 
submission)

On semantics:

Pro:
  - The server has flexibility on how to define the "update" endpoint, 
sending all clients to one URL, sending different clients to different 
URLs, or sending clients to a URL with a baked-in query parameter
  - The client can take the URL as-is and use it for all management 
operations (ie, it doesn't have to generate or compose the URL based on 
component parts)

Con:
  - The client must remember one more piece of information from the 
server at runtime if it wants to do manipulation and management of 
itself at the server (in addition to client_id, client_secret, 
registration_access_token, and others)

Alternatives include specifying a URL pattern for the server to use and 
all clients to follow, specifying a query parameter for the update 
action, and specifying a separate endpoint entirely and using the 
presence of items such as client_id and the registration access token to 
differentiate the requests. Note that *all* of these alternatives can be 
accommodated using the semantics described above, with the same actions 
on the client's part.

On syntax:

Pro:
  - Follows the designs of RFC5988 for link relations
  - The HAL format is general, and allows for all kinds of other 
information to be placed inside the _links structure
  - Allows for full use of the JSON object to specify advanced 
operations on the returned endpoint if desired

Con:
  - The rest of OAuth doesn't follow link relation guidelines (though 
it's been brought up)
  - The HAL format is general, and allows for all kinds of other 
information to be placed inside the _links structure
  - The HAL-JSON document is an expired individual I-D, and it's unclear 
what wider adoption looks like right now

Alternatives include returning the URL as a separate data member 
(registration_update_url), using HTTP headers, or using JSON Schema.

  -- Justin

[1] http://tools.ietf.org/html/draft-ietf-oauth-dyn-reg-05
[2] http://tools.ietf.org/html/draft-kelly-json-hal-03

---

From: Richard Harrington <[email-masked]>
Date: Mon, 11 Feb 2013 15:33:58 -0800

Since the request is an HTTP POST and a resource is created (http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5) the response should be an HTTP 201 Created (http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2) which is supposed to include the location of the newly created resource.

This is a good pattern to follow since, as you say, it does provide flexibility.

On Feb 11, 2013, at 1:14 PM, Justin Richer <[email-masked]> wrote:

> Draft -05 of OAuth Dynamic Client Registration [1] returns a URL pointer for the client to perform update and secret rotation actions. This functionality arose from discussions on the list about moving towards a more RESTful pattern, and Nat Sakimura proposed this approach in the OpenID Connect Working Group. This URL may be distinct from the Client Registration Endpoint URL, but draft -05 makes no promises as to its content, form, or structure, though it does contain implementor's notes on possible methods.
> 
> - The syntax (derived from HAL for JSON [2], an individual I-D submission)
> 
> On semantics:
> 
> Pro:
> - The server has flexibility on how to define the "update" endpoint, sending all clients to one URL, sending different clients to different URLs, or sending clients to a URL with a baked-in query parameter
> - The client can take the URL as-is and use it for all management operations (ie, it doesn't have to generate or compose the URL based on component parts)
> 
> Con:
> - The client must remember one more piece of information from the server at runtime if it wants to do manipulation and management of itself at the server (in addition to client_id, client_secret, registration_access_token, and others)
> 
> Alternatives include specifying a URL pattern for the server to use and all clients to follow, specifying a query parameter for the update action, and specifying a separate endpoint entirely and using the presence of items such as client_id and the registration access token to differentiate the requests. Note that *all* of these alternatives can be accommodated using the semantics described above, with the same actions on the client's part.
> 
> 
> On syntax:
> 
> Pro:
> - The HAL format is general, and allows for all kinds of other information to be placed inside the _links structure
> - Allows for full use of the JSON object to specify advanced operations on the returned endpoint if desired
> 
> Con:
> - The rest of OAuth doesn't follow link relation guidelines (though it's been brought up)
> - The HAL format is general, and allows for all kinds of other information to be placed inside the _links structure
> - The HAL-JSON document is an expired individual I-D, and it's unclear what wider adoption looks like right now
> 
> Alternatives include returning the URL as a separate data member (registration_update_url), using HTTP headers, or using JSON Schema.
> 
> -- Justin
> 
> 
> 
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth

---

From: Mike Jones <[email-masked]>
Date: Tue, 12 Feb 2013 01:12:52 +0000

It seems like significant overkill, bordering on silliness, to use the syntax
  _links: {
    "self": {
      "href":
          "https://server.example.com/register/s6BhdRkqt3"
      }
  }
to represent a value that could be more straightforwardly represented as:
  "registration_access_url": "https://server.example.com/register/s6BhdRkqt3"

Even some of the advocates for it have called it "pedantic".  I believe that most developers would have less charitable things to say about it, and would wonder why we're trying to foist needless complexity on them.

I'll also point out that this syntax is based upon an expired individual submission draft http://tools.ietf.org/html/draft-kelly-json-hal-03 that is not in any working group.  I don't believe we should take a dependence on this draft or this syntax.

Occam's razor says that this isn't needed.

				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Justin Richer
Sent: Monday, February 11, 2013 1:15 PM
To: [email-masked]
Subject: [OAUTH-WG] Registration: HAL _links structure and client self-URL

On semantics:

Pro:

Con:

On syntax:

Pro:

Con:

  -- Justin

---

From: Justin Richer <[email-masked]>
Date: Tue, 12 Feb 2013 09:25:11 -0500

I'd be fine with the return from a creation request being a 201 instead 
of a 200.

  -- Justin

On 02/11/2013 06:33 PM, Richard Harrington wrote:
> Since the request is an HTTP POST and a resource is created 
> (http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5) the 
> response should be an HTTP 201 Created 
> (http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2) 
> which is supposed to include the location of the newly created resource.
>
> On Feb 11, 2013, at 1:14 PM, Justin Richer <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>> Draft -05 of OAuth Dynamic Client Registration [1] returns a URL 
>> pointer for the client to perform update and secret rotation actions. 
>> This functionality arose from discussions on the list about moving 
>> towards a more RESTful pattern, and Nat Sakimura proposed this 
>> approach in the OpenID Connect Working Group. This URL may be 
>> distinct from the Client Registration Endpoint URL, but draft -05 
>> makes no promises as to its content, form, or structure, though it 
>> does contain implementor's notes on possible methods.
>>
>> sending all clients to one URL, sending different clients to 
>> different URLs, or sending clients to a URL with a baked-in query 
>> parameter
>> operations (ie, it doesn't have to generate or compose the URL based 
>> on component parts)
>>
>> Con:
>> Alternatives include specifying a URL pattern for the server to use 
>> and all clients to follow, specifying a query parameter for the 
>> update action, and specifying a separate endpoint entirely and using 
>> the presence of items such as client_id and the registration access 
>> token to differentiate the requests. Note that *all* of these 
>> alternatives can be accommodated using the semantics described above, 
>> with the same actions on the client's part.
>>
>>
>> On syntax:
>>
>> Pro:
>> - The HAL-JSON document is an expired individual I-D, and it's 
>> unclear what wider adoption looks like right now
>>
>> [email-masked] <mailto:[email-masked]>

---

From: Justin Richer <[email-masked]>
Date: Tue, 12 Feb 2013 10:21:24 -0500

I would be OK with the change to registration_access_url or something 
similar to that. The main argument against it is that we'd be inventing 
a bespoke field for something that's already covered out there by the 
HTTP Linked Data world. Nat did a good job of trying to generalize 
concepts of linked OAuth metadata with

    http://tools.ietf.org/html/draft-sakimura-oauth-meta-01

I don't think it's inherently silly to try and generalize the problem, 
but I can appreciate the argument that such generalization could be 
overkill in this instance.

  -- Justin

---

From: John Bradley <[email-masked]>
Date: Tue, 12 Feb 2013 12:28:17 -0300

Returning a location header in the 201 ids fine as long as we also have the same info as a claim.

I think most clients will want to process the JSON and store all the parameters together.  Making them fish out a header makes the W3C happy and is the correct thing to do but taking it from a claim is what developers are more comfortable with.

John B.

On 2013-02-12, at 11:25 AM, Justin Richer <[email-masked]> wrote:

> I'd be fine with the return from a creation request being a 201 instead of a 200. 
> 
>  -- Justin
>

---

From: Justin Richer <[email-masked]>
Date: Tue, 12 Feb 2013 11:22:33 -0500

Agreed - I didn't think that header-only was the proposal, but let's be 
explicit about the returned body always containing the URL. The way I 
read the 201 definition, it suggests (SHOULD) that you use the location 
header, but also says that the entity should refer to the new resource. 
It was my assumption that the returned JSON would still have some form 
of client-entity management URL (whether it's the HAL _links structure 
or registration_management_url or something else is still up for debate).

  -- Justin

On 02/12/2013 10:28 AM, John Bradley wrote:
> I think most clients will want to process the JSON and store all the 
> parameters together.  Making them fish out a header makes the W3C 
> happy and is the correct thing to do but taking it from a claim is 
> what developers are more comfortable with.
>
> John B.
>
> On 2013-02-12, at 11:25 AM, Justin Richer <[email-masked] 
>>>> pointer for the client to perform update and secret rotation 
>>>> actions. This functionality arose from discussions on the list 
>>>> about moving towards a more RESTful pattern, and Nat Sakimura 
>>>> proposed this approach in the OpenID Connect Working Group. This 
>>>> URL may be distinct from the Client Registration Endpoint URL, but 
>>>> draft -05 makes no promises as to its content, form, or structure, 
>>>> though it does contain implementor's notes on possible methods.
>>>>
>>>> - The server has flexibility on how to define the "update" 
>>>> endpoint, sending all clients to one URL, sending different clients 
>>>> to different URLs, or sending clients to a URL with a baked-in 
>>>> query parameter
>>>> operations (ie, it doesn't have to generate or compose the URL 
>>>> based on component parts)
>>>>
>>>> Con:
>>>> update action, and specifying a separate endpoint entirely and 
>>>> using the presence of items such as client_id and the registration 
>>>> access token to differentiate the requests. Note that *all* of 
>>>> these alternatives can be accommodated using the semantics 
>>>> described above, with the same actions on the client's part.
>>>>
>>>>
>>>> On syntax:
>>>>
>>>> Pro:

---

From: Nat Sakimura <[email-masked]>
Date: Wed, 13 Feb 2013 02:10:45 +0900

Actually, if it is to return it in the HTTP header, then it should
also use the RFC5988 Web Linking format.
Now, that is nice to have, but for many JSON programmers, I agree that
it would be a hassle to obtain the header and store them in addition
to the JSON. So, it is nicer to have it in JSON body.

Re: Is "_links.self.href" grossly complex over "registration_access_url"?

I do not think so. Accessing a flat top level parameter such
as registration_access_url and _links.self.href does not make any
difference from a
client programmers point of view. That's a beauty of JSON. Both can be
treated as a parameter name. Doing a group operation on the links makes
difference though: the structured one is easier since you can just operate
on _links while in case of the top level parameters, you have to have an
explicit list of them and do the matches. (See below for the necessity
for the grouping).

I and John discussed this for at least half an hour F2F last week, both
technically and from operation/legal point of view, for OpenID Connect
Registration.
Similar points could be made to OAuth dyn reg.

Here is what we have discussed:

When dynamically registering the client to the server,
the server probably needs to return the following:

  * terms-of-service (terms of service of the server to the client)
  * privacy-policy (privacy policy of the server to the client)

Both are defined in RFC5988/IANA Link Relations registry.

They should be returned together with

  * self.href

which is also defined in RFC5988/IANA Link Relations registry.

There are several ways to do it.

  * Return these using RFC5988 (HTTP Header)
  * Return these in entity body
      * Use HAL (or OAuth-meta)/JSON Schema
      * Use something else (e.g., a top level items)

Returning it in the entity body has several advantage over HTTP header:

  * They can be captured in one call;
  * They are protocol agnostic;

We determined that these advantages outweighs the disadvantage of creating
a new standard.

The question becomes then whether to:

  * Use HAL (or OAuth-meta)/JSON Schema
  * Use something else (e.g., a top level items)

First, we have to consider what needs to be returned in the
link/relationship category. If it were just _links.self.href, then grouping
probably does not make sense. However, since we have terms-of-service and
privacy-policy as well already, it may well make sense.

Moreover, when we think of a multi-tenant authorization server that may
want to use different OAuth authz and token endpoints for different
tennants, it would be better to be able to return those in the registration
response. Then, it would make sense to register OAuth authz and token
endpoints as rel type in the IANA registry (like Bill Mills is trying to
do) and use them in a uniform manner. Note: these per tenant endpoints may
support different scopes etc. as well. Then, these has to be coupled with
the URIs. That is why all of RFC5988/HAL/JSON Schema uses href instead of
just having the URL as the value of the parameter. The semantic
relationship would often have an associated URI, and other parameters that
goes with it.

e.g.:

{
    "_links": {
        "terms-of-service": {
            "href": "https: //server.example.com/tos"
        },
        "privacy-policy": {
            "href": "https: //server.example.com/pp"
        },
        "self": {
            "href": "https: //server.example.com/clients/1234",
            "authorize": "Bearer"
        },
        "oauth_authz": {
            "href": "https: //server.example.com/authz",
            "scopes": "openid profile email",
            "response_types": [
                "token id_token",
                "code id_token",
                "token",
                "code"
            ]
        },
        "oauth_token": {
            "href": "https: //server.example.com/token",
            "authorize": "Basic"
        }
    }
}

In short, there are bunch of link relations that needs to be returned
with additional parameters.
Grouping them seems to make sense.

Considering all these, John and I came to the conclusion that the HAL type
syntax would probably make more sense.
(Note: JSON Schema syntax does not make the parameter access as easy as HAL.)

In fact, Mike Kelly (the author of HAL) and I have just submit
a new version of draft-sakimura-oauth-meta

   http://tools.ietf.org/html/draft-sakimura-oauth-meta-02

The proposal was discussed at IETF 85 OAuth WG and the chairs asked to
submit the draft.
The -00 appeared in December, and this -02 has some simplification and
the addition
of the "operations" inspired by
https://tools.ietf.org/html/draft-ietf-scim-api-00#section-3.5 .
It is arguably a subset of HAL plus some OAuth specifics.
I have not added Discovery response example,
but adding them would makes even more sense, I think.

Cheers,

Nat

2013/2/13 Justin Richer <[email-masked]>
>
> Agreed - I didn't think that header-only was the proposal, but let's be explicit about the returned body always containing the URL. The way I read the 201 definition, it suggests (SHOULD) that you use the location header, but also says that the entity should refer to the new resource. It was my assumption that the returned JSON would still have some form of client-entity management URL (whether it's the HAL _links structure or registration_management_url or something else is still up for debate).
>
>  -- Justin
>
>
>

--
Nat Sakimura (=nat)
Chairman, OpenID Foundation
http://nat.sakimura.org/
@_nat_en

---

From: Mike Jones <[email-masked]>
Date: Tue, 12 Feb 2013 19:25:33 +0000

Part of the REST/JSON philosophy is that interfaces should be as simple and developer-friendly as possible.  XML was rejected by developers, in part, because of the self-describing nature of the structure, which required extra syntax that was often not useful in practice.  Trying to re-impose that structure using extra JSON syntax conventions is just asking developers to have an allergic reaction to our specs upon encountering them.  The syntactic complexity and *surprise factor* isn't worth the limited semantic benefits of using "_links".

Since you bring up privacy policy and terms of service, I'll note that the OAuth Dynamic Registration spec already has these fields to address those:
	policy_url
	tos_url

Those have been working fine for OpenID Connect too.  There's no need to likewise convolve them to add the extra syntax that you describe below.

(BTW, in a private thread, John Bradley pointed out that what the two of you talked about in person was actually the possibility of adding privacy policy and terms of service declarations at *discovery time*, rather than registration time.  That's a different topic, which we should discuss separately, if you want to pursue that.)

				Best wishes,
				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Nat Sakimura
Sent: Tuesday, February 12, 2013 9:11 AM
To: Justin Richer; [email-masked]
Subject: Re: [OAUTH-WG] Registration: HAL _links structure and client self-URL

Actually, if it is to return it in the HTTP header, then it should also use the RFC5988 Web Linking format.
Now, that is nice to have, but for many JSON programmers, I agree that it would be a hassle to obtain the header and store them in addition to the JSON. So, it is nicer to have it in JSON body.

I do not think so. Accessing a flat top level parameter such as registration_access_url and _links.self.href does not make any difference from a client programmers point of view. That's a beauty of JSON. Both can be treated as a parameter name. Doing a group operation on the links makes difference though: the structured one is easier since you can just operate on _links while in case of the top level parameters, you have to have an explicit list of them and do the matches. (See below for the necessity for the grouping).

I and John discussed this for at least half an hour F2F last week, both technically and from operation/legal point of view, for OpenID Connect Registration.
Similar points could be made to OAuth dyn reg.

When dynamically registering the client to the server, the server probably needs to return the following:

  * self.href

We determined that these advantages outweighs the disadvantage of creating a new standard.

First, we have to consider what needs to be returned in the link/relationship category. If it were just _links.self.href, then grouping probably does not make sense. However, since we have terms-of-service and privacy-policy as well already, it may well make sense.

Moreover, when we think of a multi-tenant authorization server that may want to use different OAuth authz and token endpoints for different tennants, it would be better to be able to return those in the registration response. Then, it would make sense to register OAuth authz and token endpoints as rel type in the IANA registry (like Bill Mills is trying to
do) and use them in a uniform manner. Note: these per tenant endpoints may support different scopes etc. as well. Then, these has to be coupled with the URIs. That is why all of RFC5988/HAL/JSON Schema uses href instead of just having the URL as the value of the parameter. The semantic relationship would often have an associated URI, and other parameters that goes with it.

e.g.:

{
    "_links": {
        "terms-of-service": {

In short, there are bunch of link relations that needs to be returned with additional parameters.
Grouping them seems to make sense.

Considering all these, John and I came to the conclusion that the HAL type syntax would probably make more sense.
(Note: JSON Schema syntax does not make the parameter access as easy as HAL.)

In fact, Mike Kelly (the author of HAL) and I have just submit a new version of draft-sakimura-oauth-meta

The proposal was discussed at IETF 85 OAuth WG and the chairs asked to submit the draft.
The -00 appeared in December, and this -02 has some simplification and the addition of the "operations" inspired by
https://tools.ietf.org/html/draft-ietf-scim-api-00#section-3.5 .
It is arguably a subset of HAL plus some OAuth specifics.
I have not added Discovery response example, but adding them would makes even more sense, I think.

Cheers,

Nat

---

From: John Bradley <[email-masked]>
Date: Tue, 12 Feb 2013 16:52:48 -0300

The current privacy policy and TOS URL in registration are the ones for the Client.

Nat and I discussed adding ones for the Authorization server that the client agrees to as separate from ones that the user is agreeing to.

The Authorization servers TOS would be in discovery and perhaps in the registration response to indicate what the client is agreeing to.

As there rare standard relationships that cover this links Nat was speculating that they could be part of the _links object. 

That aside confirming the terms of service that the client has agreed to in some way is probably a good thing in the registration response.

John B.

---

From: Justin Richer <[email-masked]>
Date: Tue, 12 Feb 2013 14:56:08 -0500

One question though: How exactly would the client, a software 
application, agree to the TOS? Is it supposed to fetch the content of 
the tos_url and do some processing on it? I wasn't under the impression 
that the tos_url contents were machine readable. Is it supposed to 
present that to the user somehow? It seems that's a better thing for the 
server to do at Authorization time, since it's got the user's attention.

Remember, this is meant to be for *automated* registration. The 
developer of the Client has no say at this stage of the game.

So, I think this is a bit of a red herring, to be honest.

  -- Justin

---

From: John Bradley <[email-masked]>
Date: Tue, 12 Feb 2013 17:04:44 -0300

There are two TOS and privacy policies.

One for the AS that the client is agreeing to by registering.  Will it hold up in court?  don't know Facebook is doing this.
The link would be a reference to a human readable file that the client (RP) can have someone look over before using the connection.
This policy may relate to how long the client can cache info etc.

The other is the privacy policy of the client that may be presented as a click through from the Authorization server.  In general the user is not explicitly accepting this, only implicitly accepting it by continuing to the RP after having been given a chance to look at it if they want.

These are very US fuse on privacy but ignoring them is probably a mistake.

John B.
On 2013-02-12, at 4:56 PM, Justin Richer <[email-masked]> wrote:

> One question though: How exactly would the client, a software application, agree to the TOS? Is it supposed to fetch the content of the tos_url and do some processing on it? I wasn't under the impression that the tos_url contents were machine readable. Is it supposed to present that to the user somehow? It seems that's a better thing for the server to do at Authorization time, since it's got the user's attention.
> 
> Remember, this is meant to be for *automated* registration. The developer of the Client has no say at this stage of the game.
>

---

From: Justin Richer <[email-masked]>
Date: Tue, 12 Feb 2013 15:05:59 -0500

I agree with the previous statement that the AS's privacy/TOS would be 
better handled through discovery, since it's not likely to change per 
client instance.

  -- Justin

---

From: Nat Sakimura <[email-masked]>
Date: Wed, 13 Feb 2013 05:26:31 +0900

Let me explain a bit more.

A trust framework may supply several ToS and Privacy Policy options
much like CC licenses.
If we want to really automate the things, you really need it.
Otherwise, the service's owner need to go read the ToS and Privacy
Policy in person and makes the dynamic registration not so dynamic.
Those option should be available through Discovery.

In Discovery, the server may provide multiple options,
out of which the client picks one. Think of something like Basic and
Premium service. In the Registration response, then, should be
the one that was picked by the client / assigned by the server.

(The notion is closely related to the implicit consent model for the
end users, which is in active discussion in bunch of places, by the way.)

Nat

2013/2/13 Justin Richer <[email-masked]>:
> better handled through discovery, since it's not likely to change per client
> instance.
>
>  -- Justin
>
>
>> One for the AS that the client is agreeing to by registering.  Will it
>> hold up in court?  don't know Facebook is doing this.
>> The link would be a reference to a human readable file that the client
>> (RP) can have someone look over before using the connection.
>> The other is the privacy policy of the client that may be presented as a
>> click through from the Authorization server.  In general the user is not
>> explicitly accepting this, only implicitly accepting it by continuing to the
>> RP after having been given a chance to look at it if they want.
>>
>>> application, agree to the TOS? Is it supposed to fetch the content of the
>>> tos_url and do some processing on it? I wasn't under the impression that the
>>> tos_url contents were machine readable. Is it supposed to present that to
>>> the user somehow? It seems that's a better thing for the server to do at
>>> Authorization time, since it's got the user's attention.
>>>
>>> Remember, this is meant to be for *automated* registration. The developer
>>> of the Client has no say at this stage of the game.
>>>
>>>> Nat and I discussed adding ones for the Authorization server that the
>>>> client agrees to as separate from ones that the user is agreeing to.
>>>>
>>>> The Authorization servers TOS would be in discovery and perhaps in the
>>>> registration response to indicate what the client is agreeing to.
>>>>
>>>> As there rare standard relationships that cover this links Nat was
>>>> speculating that they could be part of the _links object.
>>>>
>>>> That aside confirming the terms of service that the client has agreed to
>>>> in some way is probably a good thing in the registration response.
>>>>
>>>> John B.
>>>>
>>>>> Part of the REST/JSON philosophy is that interfaces should be as simple
>>>>> and developer-friendly as possible.  XML was rejected by developers, in
>>>>> part, because of the self-describing nature of the structure, which required
>>>>> extra syntax that was often not useful in practice.  Trying to re-impose
>>>>> that structure using extra JSON syntax conventions is just asking developers
>>>>> to have an allergic reaction to our specs upon encountering them.  The
>>>>> syntactic complexity and *surprise factor* isn't worth the limited semantic
>>>>> benefits of using "_links".
>>>>>
>>>>> Since you bring up privacy policy and terms of service, I'll note that
>>>>> the OAuth Dynamic Registration spec already has these fields to address
>>>>> those:
>>>>>         policy_url
>>>>>         tos_url
>>>>>
>>>>> Those have been working fine for OpenID Connect too.  There's no need
>>>>> to likewise convolve them to add the extra syntax that you describe below.
>>>>>
>>>>> (BTW, in a private thread, John Bradley pointed out that what the two
>>>>> of you talked about in person was actually the possibility of adding privacy
>>>>> policy and terms of service declarations at *discovery time*, rather than
>>>>> registration time.  That's a different topic, which we should discuss
>>>>> separately, if you want to pursue that.)
>>>>>
>>>>>                                 Best wishes,
>>>>>                                 -- Mike
>>>>>
>>>>> it would be a hassle to obtain the header and store them in addition to the
>>>>> JSON. So, it is nicer to have it in JSON body.
>>>>>
>>>>> I do not think so. Accessing a flat top level parameter such as
>>>>> registration_access_url and _links.self.href does not make any difference
>>>>> from a client programmers point of view. That's a beauty of JSON. Both can
>>>>> be treated as a parameter name. Doing a group operation on the links makes
>>>>> explicit list of them and do the matches. (See below for the necessity for
>>>>> the grouping).
>>>>>
>>>>> do) and use them in a uniform manner. Note: these per tenant endpoints
>>>>> may support different scopes etc. as well. Then, these has to be coupled
>>>>> with the URIs. That is why all of RFC5988/HAL/JSON Schema uses href instead
>>>>> of just having the URL as the value of the parameter. The semantic
>>>>> Considering all these, John and I came to the conclusion that the HAL
>>>>> type syntax would probably make more sense.
>>>>> the addition of the "operations" inspired by
>>>>>> Agreed - I didn't think that header-only was the proposal, but let's
>>>>>> be explicit about the returned body always containing the URL. The way I
>>>>>> header, but also says that the entity should refer to the new resource. It
>>>>>> was my assumption that the returned JSON would still have some form of
>>>>>> client-entity management URL (whether it's the HAL _links structure or
>>>>>> registration_management_url or something else is still up for debate).
>>>>>>
>>>>>> -- Justin
>>>>>>
>>>>>>
>>>>>>
>>>>>> parameters together.  Making them fish out a header makes the W3C happy and
>>>>>> is the correct thing to do but taking it from a claim is what developers are
>>>>>> more comfortable with.
>>>>>>
>>>>>> John B.
>>>>>>
>>>>>> (http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5) the response
>>>>>> should be an HTTP 201 Created
>>>>>> (http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2) which is
>>>>>> supposed to include the location of the newly created resource.
>>>>>>
>>>>>> pointer for the client to perform update and secret rotation actions. This
>>>>>> functionality arose from discussions on the list about moving towards a more
>>>>>> RESTful pattern, and Nat Sakimura proposed this approach in the OpenID
>>>>>> Connect Working Group. This URL may be distinct from the Client Registration
>>>>>> Endpoint URL, but draft -05 makes no promises as to its content, form, or
>>>>>> structure, though it does contain implementor's notes on possible methods.
>>>>>>
>>>>>> and all clients to follow, specifying a query parameter for the update
>>>>>> action, and specifying a separate endpoint entirely and using the presence
>>>>>> of items such as client_id and the registration access token to
>>>>>> accommodated using the semantics described above, with the same actions on
>>>>>> the client's part.
>>>>>>
>>>>>>
>>>>>> On syntax:
>>>>>>
>>>>>> Pro:

---

From: Nat Sakimura <[email-masked]>
Date: Wed, 13 Feb 2013 05:48:57 +0900

Like bunch of people expressed their opinion in the Thursday's OpenID
call, I honestly do not understand why you think this is complex.
It is JSON.
It is not a surprise.

Compare

obj = {
  "registration_access_url":"http://example.com/"
};

obj = {
  "_links":{"self":{"href":"http://example.com/"}}
};

In the former case, the client accesses it as obj.registration_access_url.
In the later case, the client accesses it as obj._links.self.href.

As far as programming easiness is concerned, they are more or less the same.

Now, introduce other link relationships.
Say you want to store the link/rel metadata in one table and other
data in another table.
The flat one (the former) gets significantly harder.

We human being categorizes things into buckets, and we handle those buckets.
If we do not need those categorization power, then why do we use JSON?

One of the beauty of JSON is that while it has the categorization power,
you can just access as if you are in a flat name space when you are
accessing individual items.

So, while you characterize it as "complex", "hard", etc., in fact it
is "simpler" and "easier".

Also, I think you misquote the REST/JSON philosophy.

One of the most fundamental philosophy of REST is to drive the states
through hyper-links and media-types.
As a result, it also asks for a uniform interface. JSON lacks this
hyper-link and uniform interface capability.
Proposals like HAL/OAuth-meta and JSON Hyper-Schema are attempts to
address this shortcoming.
It is trying to provide a uniform interface over hyper-links.
Ad-hoc variable like registration_access_url fails this test because
it is only useable in this particular instance.
(I dislike the name as well as it does not represent the resource
representation that it returns, but that is another issue.)

> Those have been working fine for OpenID Connect too.  There's no need to likewise convolve them to add the extra syntax that you describe below.

As John said, and as I said in the private email yesterday, they are
totally different.

> (BTW, in a private thread, John Bradley pointed out that what the two of you talked about in person was actually the possibility of adding privacy policy and terms of service declarations at *disco…

No, that is not right, as John's previous mail indicates. There are
ones for discovery and the ones in registration responses.

Nat

---

From: Anthony Nadalin <[email-masked]>
Date: Tue, 12 Feb 2013 22:42:01 +0000

I doubt that the ToS and Privacy Policy will be different for a given Trust Framework provider, as these are all bilateral agreements, I do expect these to be different between trust framework providers though

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Nat Sakimura
Sent: Tuesday, February 12, 2013 12:27 PM
To: Justin Richer
Cc: [email-masked]
Subject: Re: [OAUTH-WG] Registration: HAL _links structure and client self-URL

A trust framework may supply several ToS and Privacy Policy options much like CC licenses.
If we want to really automate the things, you really need it.
Otherwise, the service's owner need to go read the ToS and Privacy Policy in person and makes the dynamic registration not so dynamic.
Those option should be available through Discovery.

In Discovery, the server may provide multiple options, out of which the client picks one. Think of something like Basic and Premium service. In the Registration response, then, should be the one that was picked by the client / assigned by the server.

(The notion is closely related to the implicit consent model for the end users, which is in active discussion in bunch of places, by the way.)

Nat

2013/2/13 Justin Richer <[email-masked]>:
>> One for the AS that the client is agreeing to by registering.  Will 
>> it hold up in court?  don't know Facebook is doing this.
>> The other is the privacy policy of the client that may be presented 
>> as a click through from the Authorization server.  In general the 
>> user is not explicitly accepting this, only implicitly accepting it 
>> by continuing to the RP after having been given a chance to look at it if they want.
>>
>>> application, agree to the TOS? Is it supposed to fetch the content 
>>> of the tos_url and do some processing on it? I wasn't under the 
>>> impression that the tos_url contents were machine readable. Is it 
>>> supposed to present that to the user somehow? It seems that's a 
>>> better thing for the server to do at Authorization time, since it's got the user's attention.
>>>
>>>> Nat and I discussed adding ones for the Authorization server that 
>>>> the client agrees to as separate from ones that the user is agreeing to.
>>>>
>>>> The Authorization servers TOS would be in discovery and perhaps in 
>>>> the registration response to indicate what the client is agreeing to.
>>>>
>>>> That aside confirming the terms of service that the client has 
>>>> agreed to in some way is probably a good thing in the registration response.
>>>>
>>>> John B.
>>>>
>>>>> Part of the REST/JSON philosophy is that interfaces should be as 
>>>>> simple and developer-friendly as possible.  XML was rejected by 
>>>>> developers, in part, because of the self-describing nature of the 
>>>>> structure, which required extra syntax that was often not useful 
>>>>> in practice.  Trying to re-impose that structure using extra JSON 
>>>>> syntax conventions is just asking developers to have an allergic 
>>>>> reaction to our specs upon encountering them.  The syntactic 
>>>>> complexity and *surprise factor* isn't worth the limited semantic benefits of using "_links".
>>>>>
>>>>> Since you bring up privacy policy and terms of service, I'll note 
>>>>> that the OAuth Dynamic Registration spec already has these fields 
>>>>> to address
>>>>> those:
>>>>>         policy_url
>>>>>         tos_url
>>>>>
>>>>> Those have been working fine for OpenID Connect too.  There's no 
>>>>> need to likewise convolve them to add the extra syntax that you describe below.
>>>>>
>>>>> (BTW, in a private thread, John Bradley pointed out that what the 
>>>>> two of you talked about in person was actually the possibility of 
>>>>> adding privacy policy and terms of service declarations at 
>>>>> *discovery time*, rather than registration time.  That's a 
>>>>> different topic, which we should discuss separately, if you want 
>>>>> to pursue that.)
>>>>>
>>>>>                                 Best wishes,
>>>>>                                 -- Mike
>>>>>
>>>>> Now, that is nice to have, but for many JSON programmers, I agree 
>>>>> that it would be a hassle to obtain the header and store them in 
>>>>> addition to the JSON. So, it is nicer to have it in JSON body.
>>>>>
>>>>> registration_access_url and _links.self.href does not make any 
>>>>> difference from a client programmers point of view. That's a 
>>>>> beauty of JSON. Both can be treated as a parameter name. Doing a 
>>>>> group operation on the links makes difference though: the 
>>>>> structured one is easier since you can just operate on _links 
>>>>> while in case of the top level parameters, you have to have an 
>>>>> explicit list of them and do the matches. (See below for the necessity for the grouping).
>>>>>
>>>>> I and John discussed this for at least half an hour F2F last week, 
>>>>> both technically and from operation/legal point of view, for 
>>>>> OpenID Connect Registration.
>>>>> link/relationship category. If it were just _links.self.href, then 
>>>>> grouping probably does not make sense. However, since we have 
>>>>> terms-of-service and privacy-policy as well already, it may well make sense.
>>>>>
>>>>> Moreover, when we think of a multi-tenant authorization server 
>>>>> that may want to use different OAuth authz and token endpoints for 
>>>>> different tennants, it would be better to be able to return those 
>>>>> in the registration response. Then, it would make sense to 
>>>>> register OAuth authz and token endpoints as rel type in the IANA 
>>>>> registry (like Bill Mills is trying to
>>>>> do) and use them in a uniform manner. Note: these per tenant 
>>>>> endpoints may support different scopes etc. as well. Then, these 
>>>>> has to be coupled with the URIs. That is why all of 
>>>>> RFC5988/HAL/JSON Schema uses href instead of just having the URL 
>>>>> as the value of the parameter. The semantic relationship would 
>>>>> often have an associated URI, and other parameters that goes with it.
>>>>>
>>>>> e.g.:
>>>>>
>>>>> {
>>>>>     "_links": {
>>>>>         "terms-of-service": {
>>>>> Considering all these, John and I came to the conclusion that the 
>>>>> HAL type syntax would probably make more sense.
>>>>> (Note: JSON Schema syntax does not make the parameter access as 
>>>>> easy as
>>>>> HAL.)
>>>>>
>>>>> The -00 appeared in December, and this -02 has some simplification 
>>>>> and the addition of the "operations" inspired by
>>>>>> Agreed - I didn't think that header-only was the proposal, but 
>>>>>> let's be explicit about the returned body always containing the 
>>>>>> URL. The way I read the 201 definition, it suggests (SHOULD) that 
>>>>>> you use the location header, but also says that the entity should 
>>>>>> refer to the new resource. It was my assumption that the returned 
>>>>>> JSON would still have some form of client-entity management URL 
>>>>>> (whether it's the HAL _links structure or registration_management_url or something else is still up for debate).
>>>>>>
>>>>>> -- Justin
>>>>>>
>>>>>>
>>>>>>
>>>>>> I think most clients will want to process the JSON and store all 
>>>>>> the parameters together.  Making them fish out a header makes the 
>>>>>> W3C happy and is the correct thing to do but taking it from a 
>>>>>> claim is what developers are more comfortable with.
>>>>>>
>>>>>> John B.
>>>>>>
>>>>>> (http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5) 
>>>>>> the response should be an HTTP 201 Created
>>>>>> (http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2
>>>>>> ) which is supposed to include the location of the newly created resource.
>>>>>>
>>>>>> URL may be distinct from the Client Registration Endpoint URL, 
>>>>>> but draft -05 makes no promises as to its content, form, or structure, though it does contain implementor's notes on possible methods.
>>>>>>
>>>>>> endpoint, sending all clients to one URL, sending different 
>>>>>> clients to different URLs, or sending clients to a URL with a 
>>>>>> baked-in query parameter
>>>>>> server at runtime if it wants to do manipulation and management 
>>>>>> of itself at the server (in addition to client_id, client_secret, 
>>>>>> Alternatives include specifying a URL pattern for the server to 
>>>>>> use and all clients to follow, specifying a query parameter for 
>>>>>> the update action, and specifying a separate endpoint entirely 
>>>>>> and using the presence of items such as client_id and the 
>>>>>> registration access token to differentiate the requests. Note 
>>>>>> that *all* of these alternatives can be accommodated using the 
>>>>>> semantics described above, with the same actions on the client's part.
>>>>>>
>>>>>>
>>>>>> On syntax:
>>>>>>
>>>>>> Pro: