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: oauth-boun...@ietf.org [mailto:oauth-boun...@ietf.org] On Behalf Of Nat
Sakimura
Sent: Tuesday, February 12, 2013 9:11 AM
To: Justin Richer; oauth@ietf.org
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.
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 <jric...@mitre.org>
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:
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 <jric...@mitre.org> wrote:
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.
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 <jric...@mitre.org> 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.
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
_______________________________________________
OAuth mailing list
OAuth@ietf.org
https://www.ietf.org/mailman/listinfo/oauth
_______________________________________________
OAuth mailing list
OAuth@ietf.org
https://www.ietf.org/mailman/listinfo/oauth
_______________________________________________
OAuth mailing list
OAuth@ietf.org
https://www.ietf.org/mailman/listinfo/oauth
--
Nat Sakimura (=nat)
Chairman, OpenID Foundation
http://nat.sakimura.org/
@_nat_en
_______________________________________________
OAuth mailing list
OAuth@ietf.org
https://www.ietf.org/mailman/listinfo/oauth
_______________________________________________
OAuth mailing list
OAuth@ietf.org
https://www.ietf.org/mailman/listinfo/oauth
