Subject: [OAUTH-WG] Registration: RESTful client lifecycle management

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

Draft -05 of OAuth Dynamic Client Registration [1] defines several 
operations that the client can take on its behalf as part of the 
registration process. These boil down to the basic CRUD operations that 
you find in many APIs: Create, Read, Update, Delete. Draft -00 defined 
only the "Create" operation, draft -01 through -04 added the "Update" 
operation, switched using the "operation=" parameter.

Following several suggestions to do so on the list, the -05 draft 
defines these operations in terms of a RESTful API for the client. Namely:

  - HTTP POST to registration endpoint => Create (register) a new client
  - HTTP PUT to update endpoint (with registration_access_token) => 
Update the registered information for this client
  - HTTP GET to update endpoint (with registration_access_token) => read 
the registered information for this client
  - HTTP DELETE to update endpoint (with registration_access_token) => 
Delete (unregister/de-provision) this client

The two main issues at stake here are: the addition of the READ and 
DELETE methods, and the use of HTTP verbs following a RESTful design 
philosophy.

Pro:
  - RESTful APIs (with HTTP verbs to differentiate functionality) are 
the norm today
  - Full lifecycle management is common and is going to be expected by 
many users of this protocol in the wild

Cons:
  - Update semantics are still under debate (full replace? patch?)
  - Somewhat increased complexity on the server to support all operations
  - Client has to understand all HTTP verbs for full access (though 
plain registration is just POST)

Alternatives include using an operational switch parameter (like the old 
drafts), defining separate endpoints for every action, or doing all 
operations on a single endpoint using verbs to switch.

  -- Justin

[1] http://tools.ietf.org/html/draft-ietf-oauth-dyn-reg-05

---

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

I'm fine with the use of the different verbs, provided that the client_id is present to distinguish between "register" and "update" operations for implementations that want to use it in that matter, as I'd previously written.  (*Your* implementation is free to not use this value, if you so choose, but it's useful for many.)

If that's not acceptable, then we should restore the "operation" parameter.

I will add that "register" should be the only required operation.  It's fine to support others if needed in a particular context, but enabling registration of clients shouldn't require servers to also support changing them, getting state about them, and deleting them.

				-- 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: RESTful client lifecycle management

Draft -05 of OAuth Dynamic Client Registration [1] defines several operations that the client can take on its behalf as part of the registration process. These boil down to the basic CRUD operations that you find in many APIs: Create, Read, Update, Delete. Draft -00 defined only the "Create" operation, draft -01 through -04 added the "Update" 
operation, switched using the "operation=" parameter.

Following several suggestions to do so on the list, the -05 draft defines these operations in terms of a RESTful API for the client. Namely:

  - HTTP POST to registration endpoint => Create (register) a new client
  - HTTP PUT to update endpoint (with registration_access_token) => Update the registered information for this client
  - HTTP GET to update endpoint (with registration_access_token) => read the registered information for this client
  - HTTP DELETE to update endpoint (with registration_access_token) => Delete (unregister/de-provision) this client

The two main issues at stake here are: the addition of the READ and DELETE methods, and the use of HTTP verbs following a RESTful design philosophy.

Pro:
  - RESTful APIs (with HTTP verbs to differentiate functionality) are the norm today
  - Full lifecycle management is common and is going to be expected by many users of this protocol in the wild

Cons:
  - Update semantics are still under debate (full replace? patch?)
  - Somewhat increased complexity on the server to support all operations
  - Client has to understand all HTTP verbs for full access (though plain registration is just POST)

  -- Justin

[1] http://tools.ietf.org/html/draft-ietf-oauth-dyn-reg-05
_______________________________________________
OAuth mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/oauth

---

From: John Bradley <[email-masked]>
Date: Mon, 11 Feb 2013 22:51:46 -0300

I would always include the client_id on update.

I think it is also us full to have other tokens used at the update endpoint.  I can see the master token used to update all the clients it has registered as part of API management. 
Relying on the registration_access_token is probably a design that will cause trouble down the road.

I think GET and POST are relatively clear.   I don't know about expelling PUT to developers.  I think POST with a client_id to a (separate discussion) update_uri works without restricting it to PUT.

I think DELETE needs to be better understood.   I think a status that can be set for client lifecycle is better than letting a client delete a entry.    
In some cases there will be more than one instance of a client and letting them know they have been turned off for a reason is better than making there registration disappear.  
So for the moment I would levee out DELETE.

John B.

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

> Draft -05 of OAuth Dynamic Client Registration [1] defines several operations that the client can take on its behalf as part of the registration process. These boil down to the basic CRUD operations that you find in many APIs: Create, Read, Update, Delete. Draft -00 defined only the "Create" operation, draft -01 through -04 added the "Update" operation, switched using the "operation=" parameter.
> 
> Alternatives include using an operational switch parameter (like the old drafts), defining separate endpoints for every action, or doing all operations on a single endpoint using verbs to switch.
> 
> -- Justin
>

---

From: Torsten Lodderstedt <[email-masked]>
Date: Tue, 12 Feb 2013 08:23:49 +0100

+1 for always including the client_id 

As John pointed out, there could be different entities updating client data. Then one has to distinguish the resource and the credential.

---

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

The problem that I have with "always including the client_id" is *where* 
to include it. Are we talking a query parameter, URI template, or 
somewhere in the request body? The latter will only work for POST and 
PUT, so it's out of the question to support GET and DELETE using that 
semantic. I think we should support all operations using parallel syntax 
-- that's just good API design.

I *really* don't like the idea of switching the action solely based on 
whether or not the client_id is present in the request body of a POST. 
This is a side-effectful mode switch, and it will only lead to pain and 
misery. Additionally, if the input is JSON (separate discussion), then a 
server would have to parse the JSON body before knowing where to route 
the request. In most web development frameworks that I've used, this is 
impossible. A query parameter or URL pattern, on the other hand, is doable.

As it stands right now, a server is free to include the client_id in the 
"update/management" URL that it returns as part of the _link structure 
(separate discussion). The current text goes as far as recommending that 
practice, but doesn't take the step of requiring it in any form, and 
leaving it up to the server to decide what form it takes. If a server 
can route better with a query parameter, it'll return a URL to the 
client that has a client_id= query parameter. If a server would rather 
use a path component with the client_id, it can do that, too. If it 
wants to put everything on one URL and differentiate through the request 
body or presence/absence of the registration_access_token, it can always 
return the same URL to every client. I think that's nuts, but you can do 
it. Interoperability is preserved because the client simply follows the 
returned URL to do its bits and pieces, and it doesn't ever have to 
create or compose this URL from component parts.

I want to continue to distinguish between the POST and PUT operations 
for create and update, respectively. This is a common pattern and the 
one described in the original REST thesis that described the 
architectural style. I'll also bring up that the semantics of PUT are 
intended to be "replace all", which is what you had originally argued 
for in the update case as well. I not convinced that developers of today 
can't handle HTTP verbs like PUT if they want to do fancier operations 
like updates. Note that the core operations, create and read, remain as 
POST and GET, which would be well within the grasp of every library and 
web developer today.

  -- Justin

---

From: John Bradley <[email-masked]>
Date: Tue, 12 Feb 2013 13:30:36 -0300

To some extent we want the server to have the flexibility it needs.

If the server knows it is going to need client_id for GET it needs to encode it in the resource URI ether as part of the path or as a query parameter (that is up to the server)

When doing updates the client MUST include the client_id as an additional integrity check.  Some servers may switch on that but that is up to them.

If we want incremental replace (not resetting claims not sent to there defaults) then we need POST for update.  
I think if you want to do the REST thing and be pure about PUT it needs to reset all values not sent to there defaults.

I suppose we could have both but two ways of doing it leads to confusion.

John B.

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

> The problem that I have with "always including the client_id" is *where* to include it. Are we talking a query parameter, URI template, or somewhere in the request body? The latter will only work for POST and PUT, so it's out of the question to support GET and DELETE using that semantic. I think we should support all operations using parallel syntax -- that's just good API design.
> 
> I *really* don't like the idea of switching the action solely based on whether or not the client_id is present in the request body of a POST. This is a side-effectful mode switch, and it will only lead to pain and misery. Additionally, if the input is JSON (separate discussion), then a server would have to parse the JSON body before knowing where to route the request. In most web development frameworks that I've used, this is impossible. A query parameter or URL pattern, on the other hand, is doable.
> 
> As it stands right now, a server is free to include the client_id in the "update/management" URL that it returns as part of the _link structure (separate discussion). The current text goes as far as recommending that practice, but doesn't take the step of requiring it in any form, and leaving it up to the server to decide what form it takes. If a server can route better with a query parameter, it'll return a URL to the client that has a client_id= query parameter. If a server would rather use a path component with the client_id, it can do that, too. If it wants to put everything on one URL and differentiate through the request body or presence/absence of the registration_access_token, it can always return the same URL to every client. I think that's nuts, but you can do it. Interoperability is preserved because the client simply follows the returned URL to do its bits and pieces, and it doesn't ever have to create or compose this URL from component parts.
> 
> I want to continue to distinguish between the POST and PUT operations for create and update, respectively. This is a common pattern and the one described in the original REST thesis that described the architectural style. I'll also bring up that the semantics of PUT are intended to be "replace all", which is what you had originally argued for in the update case as well. I not convinced that developers of today can't handle HTTP verbs like PUT if they want to do fancier operations like updates. Note that the core operations, create and read, remain as POST and GET, which would be well within the grasp of every library and web developer today.
> 
> -- Justin
>

---

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

> When doing updates the client MUST include the client_id as an additional integrity check.  Some servers may switch on that but that is up to them.
So if by this you mean that the client still simply follows whatever 
update url the server hands it (which may or may not include the 
client_id in some form, but the client doesn't care), and that the 
client MUST include its client_id in the request body (top-level member 
of a JSON object, at the moment) when doing a PUT (or POST/PATCH? see 
below) for the update action, then I'm totally fine with that. Is this 
what you're suggesting?

> I think if you want to do the REST thing and be pure about PUT it needs to reset all values not sent to there defaults.

I agree with this argument in terms of the purity, and as I would rather 
see the different verb used for different actions, I am willing to give 
up the semantics of the not-resetting-claims that's in there right now 
for this action. There's actually another HTTP verb, PATCH, that isn't 
used much but is meant for partial updates, and we could transfer the 
not-resetting-claims action to this instead.

> I suppose we could have both but two ways of doing it leads to confusion.

I agree that we can't do both PUT and POST, and we can't have both 
partial and complete replacement on the same verb/endpoint combination. 
We need to pick one combination and have it be clear.

  -- Justin

---

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

2013/2/13 Justin Richer <[email-masked]>:
>> If the server knows it is going to need client_id for GET it needs to
>> encode it in the resource URI ether as part of the path or as a query
>> parameter (that is up to the server)
>>
>> When doing updates the client MUST include the client_id as an additional
>> integrity check.  Some servers may switch on that but that is up to them.
>
> So if by this you mean that the client still simply follows whatever update
> url the server hands it (which may or may not include the client_id in some
> form, but the client doesn't care), and that the client MUST include its
> client_id in the request body (top-level member of a JSON object, at the
> moment) when doing a PUT (or POST/PATCH? see below) for the update action,
> then I'm totally fine with that. Is this what you're suggesting?

As far as I understand, yes. That is what we discussed last Thursday
face to face.

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

---

From: Mike Jones <[email-masked]>
Date: Tue, 12 Feb 2013 18:37:00 +0000

Then I think we've reached an acceptable resolution on this one.  By having the server return the registration_access_url upon create and having the client be required to include the client_id upon update, servers are free to manage their registration endpoint(s) as they see fit and clients always do the same thing.

				Thanks all,
				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Nat Sakimura
Sent: Tuesday, February 12, 2013 9:15 AM
To: Justin Richer
Cc: [email-masked]
Subject: Re: [OAUTH-WG] Registration: RESTful client lifecycle management

2013/2/13 Justin Richer <[email-masked]>:
>> When doing updates the client MUST include the client_id as an 
>> additional integrity check.  Some servers may switch on that but that is up to them.
>
> client MUST include its client_id in the request body (top-level 
> member of a JSON object, at the
> moment) when doing a PUT (or POST/PATCH? see below) for the update 
> action, then I'm totally fine with that. Is this what you're suggesting?

As far as I understand, yes. That is what we discussed last Thursday face to face.

---

From: Justin Richer <[email-masked]>
Date: Tue, 12 Feb 2013 13:37:54 -0500

I agree, and the "must include client_id" gels with the other discussion 
of doing a full-replace for the PUT operation for updates from another 
thread.

  -- Justin

---

From: John Bradley <[email-masked]>
Date: Tue, 12 Feb 2013 15:39:10 -0300

On 2013-02-12, at 1:39 PM, Justin Richer <[email-masked]> wrote:

> So if by this you mean that the client still simply follows whatever update url the server hands it (which may or may not include the client_id in some form, but the client doesn't care), and that the client MUST include its client_id in the request body (top-level member of a JSON object, at the moment) when doing a PUT (or POST/PATCH? see below) for the update action, then I'm totally fine with that. Is this what you're suggesting?

Yes but It is a suggestion others may still hate it.
> I agree with this argument in terms of the purity, and as I would rather see the different verb used for different actions, I am willing to give up the semantics of the not-resetting-claims that's in there right now for this action. There's actually another HTTP verb, PATCH, that isn't used much but is meant for partial updates, and we could transfer the not-resetting-claims action to this instead.

Yes PATCH would represent the incremental update but we are getting further from the beaten path here. 

> I agree that we can't do both PUT and POST, and we can't have both partial and complete replacement on the same verb/endpoint combination. We need to pick one combination and have it be clear.
> 
> -- Justin
>

---

From: Justin Richer <[email-masked]>
Date: Wed, 13 Feb 2013 10:00:27 -0500

Would it be reasonable to mark the PUT and DELETE methods as optional 
for the server to implement, but with defined semantics if they do? I 
want to keep GET and POST(create) as mandatory, as I think that's the 
minimal set of functionality required.

  -- Justin

---

From: John Bradley <[email-masked]>
Date: Wed, 13 Feb 2013 12:09:42 -0300

I am not violently opposed to PUT as a option that completely replaces the resource setting all unsent claims back to the defaults.  

I don't have a good feeling about DELETE,  I think we still need more discussion on what it means, what privileges it takes to invoke it etc.
It could be a bad thing if we get wrong or is not implemented consistently.

Personally I don't think a client should ever be able to DELETE it's record.   

I think marking a client_id as pending provisioning, suspended,  revoked etc is better and that can be done with a claim in the update endpoint.

It should only be the server that deletes a record after satisfying it's audit requirements.

John B. 

On 2013-02-13, at 12:00 PM, Justin Richer <[email-masked]> wrote:

> Would it be reasonable to mark the PUT and DELETE methods as optional for the server to implement, but with defined semantics if they do? I want to keep GET and POST(create) as mandatory, as I think that's the minimal set of functionality required.
> 
> -- Justin
>

---

From: Mike Jones <[email-masked]>
Date: Wed, 13 Feb 2013 15:32:29 +0000

I agree that DELETE is potentially problematic.  I'd leave it out.

				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of John Bradley
Sent: Wednesday, February 13, 2013 7:10 AM
To: Justin Richer
Cc: [email-masked]
Subject: Re: [OAUTH-WG] Registration: RESTful client lifecycle management

John B.

---

From: Nat Sakimura <[email-masked]>
Date: Thu, 14 Feb 2013 03:27:40 +0900

I am against the syntax of registration_access_url .

=nat via iPhone

---

From: Nat Sakimura <[email-masked]>
Date: Thu, 14 Feb 2013 03:31:22 +0900

Generally speaking, mapping PUT to replace and POST to change is an
acceptable practice so I am fine with it.

Now, what I still do not understand is why you think it is fine to do
PUT or POST and not DELETE. Doing PUT with empty content is almost the
same as DELETE. Could you explain?

=nat via iPhone

---

From: Justin Richer <[email-masked]>
Date: Wed, 13 Feb 2013 13:40:23 -0500

Duly noted, and while there seems to be solid support behind the
semantics of returning a URL, I'm not convinced the syntax argument is
over yet either. I have seen support and good arguments from both sides
and there isn't a clear winner there (see the other thread). Speaking as
an individual member, I could go with either approach and I'd like to
see what the rest of the WG wants.

Speaking now as an editor: It's been suggested off-list that we adopt
the simplified (bespoke) mechanism of the "registration_access_url"
syntax for the next draft and continue to move discussion forward for
the inclusion of the more-general mechanism (beit HAL based or something
similar like JSON-LD) here on the list. Would you and the other HAL
supporters be amenable to this solution? I wouldn't be opposed to adding
a kind of "note for discussion" section to the -06 draft to help
facilitate moving forward in a concrete manner, with the assumption that
the text would be either removed or incorporated in a later draft. I
just have to put a stake down somewhere on the syntax, and I'm leaning
towards the one that doesn't add a normative dependency on an unfinished
(as of right now) work.

-- Justin

---

From: Mike Jones <[email-masked]>
Date: Wed, 13 Feb 2013 20:04:00 +0000

+1

________________________________
From: Justin Richer
Sent: 2/13/2013 10:41 AM
To: Nat Sakimura
Cc: Mike Jones; [email-masked]
Subject: Re: [OAUTH-WG] Registration: RESTful client lifecycle management

-- Justin

---

From: John Bradley <[email-masked]>
Date: Wed, 13 Feb 2013 17:18:12 -0300

DELETE is removing the record not resetting it to defaults.  They are quite diffrent.

I want to agree on what the expected behaviour of DELETE is.   I think we have agreement on PUT and POST.

The general not in that a client can DELETE it's record is a implication I don't like.  I think that is for the server to decide and if it is not actually deleting it then DELETE is the wrong verb to use.

John B.

---

From: Tim Bray <[email-masked]>
Date: Wed, 13 Feb 2013 13:26:32 -0800

A DELETE is an http request that asks the server to delete something.  We
probably would want to avoid writing a requirement into the standard that
the server has to comply.  So you get back a 204 if it worked, a 404 if
there is no such registration, a 403 if there is but the server declines to
delete, etc. Seems pretty straightforward. -T

On Wed, Feb 13, 2013 at 12:18 PM, John Bradley <[email-masked]> wrote:

> The general not in that a client can DELETE it's record is a implication I
> don't like.  I think that is for the server to decide and if it is not
> actually deleting it then DELETE is the wrong verb to use.
>
> John B.
>
> >> I am not violently opposed to PUT as a option that completely replaces
> the resource setting all unsent claims back to the defaults.
> >>
> >> I don't have a good feeling about DELETE,  I think we still need more
> discussion on what it means, what privileges it takes to invoke it etc.
> >> I think marking a client_id as pending provisioning, suspended,
>  revoked etc is better and that can be done with a claim in the update
> endpoint.
> >>
> for the server to implement, but with defined semantics if they do? I want
> to keep GET and POST(create) as mandatory, as I think that's the minimal
> set of functionality required.
> >>>
> >>> -- Justin
> >>>
> >>>> I think it is also us full to have other tokens used at the update
> endpoint.  I can see the master token used to update all the clients it has
> registered as part of API management.
> >>>> I think GET and POST are relatively clear.   I don't know about
> expelling PUT to developers.  I think POST with a client_id to a (separate
> discussion) update_uri works without restricting it to PUT.
> >>>>
> >>>> I think DELETE needs to be better understood.   I think a status that
> can be set for client lifecycle is better than letting a client delete a
> entry.
> >>>> In some cases there will be more than one instance of a client and
> letting them know they have been turned off for a reason is better than
> making there registration disappear.
> registration process. These boil down to the basic CRUD operations that you
> find in many APIs: Create, Read, Update, Delete. Draft -00 defined only the
> "Create" operation, draft -01 through -04 added the "Update" operation,
> switched using the "operation=" parameter.
> >>>>>
> >>>>> - HTTP GET to update endpoint (with registration_access_token) =>
> read the registered information for this client
> >>>>> Alternatives include using an operational switch parameter (like the
> old drafts), defining separate endpoints for every action, or doing all

---

From: John Bradley <[email-masked]>
Date: Wed, 13 Feb 2013 18:37:07 -0300

OK Tim do you think DELETE is a feature that:
a) developers would use
b) that Authorization servers like google would implement.

If we put it in and than have people say you have a bunch of extra stuff no line is going to use just to be semantically pure.  I will not be a happy bunny.

Just because HTTP has a verb we don't need to use it if we don't have a concrete use case.

If you say Google would implement it and use it for x or y than I would feel differently about it.

I don't hate DELETE though I think it is probably a bad power to give to clients.  

Feedback on your use case please.

John B.

On 2013-02-13, at 6:26 PM, Tim Bray <[email-masked]> wrote:

> A DELETE is an http request that asks the server to delete something.  We probably would want to avoid writing a requirement into the standard that the server has to comply.  So you get back a 204 if it worked, a 404 if there is no such registration, a 403 if there is but the server declines to delete, etc. Seems pretty straightforward. -T
>

---

From: Prateek Mishra <[email-masked]>
Date: Wed, 13 Feb 2013 17:53:52 -0500

It would be helpful if the draft identified the various cases that are 
intended to be supported. For example,
in draft-ietf-oauth-assertions-10, there is a helpful distinction made 
between "Client acting on behalf of a user" vs.
"Client Action on behalf of an anonymous user" (vs. even more advanced 
use-cases). Otherwise, folks
have a hard time figuring out the pieces they need to implement and the 
required behavior.

It feels like Section 3 speaks to all of these cases simultaneously. I 
think this is confusing and
our developers have raised some questions about it.

BTW, it would also help if the rules in Section 3 were numbered.

1) For the case where we have "Client acting on behalf of user" - this 
case seems to be where we
have something like a SAML SSO assertion - complete with Subject 
identifying the
"authorized accessor or delegate". The Client offers this bearer 
instrument as an access grant and the Authorization
server understands that its "acting on behalf a user".

a) As the SAML assertion is a bearer instrument and can be stolen, the 
authorization server should insist on client credentials being present.
In other words, the client should be confidential. What is the value in 
permitting a public client to participate in this exchange?

b) Further, as part of its processing rules, once the client has been 
authenticated
the authorization server should determine whether the particular client 
has the right to present the SAML bearer assertion.

c)  What is the value of including an AuthNStatement? Specifically, what 
does the Authorization server understand by its
presence or absence? What is the guidance to deployers? Should they 
require end-user authentication to have taken place?

2) Bullet 5 (counting from the bottom of Section 3) references a more 
advanced use case based on a SAML delegation
model. Is this the ONLY case where AuthNStatement's are allowed to be 
omitted? If so, that should be stated clearly.

  I think this bullet refers to an advanced use-case and should be moved 
to an independent section.

I think by "the presenter act autonomously on behalf of the subject" you 
mean something like "Client acts on Behalf of Anonymous Users".
as identified in draft-ietf-oauth-assertions-10.

I also found the sentence "The presented SHOULD be identified in the 
<NameID> or similar element,.." problematic. Its pretty open ended
and it seems to me it will be difficult to have an interoperable 
implementation based on this text.

Finally, what are the additional processing rules that the authorization 
server needs to implement when processing this class of SAML assertions?

3) Has there been any interoperability testing of this profile? This is 
an activity we would be interested in.

---

From: Nat Sakimura <[email-masked]>
Date: Thu, 14 Feb 2013 12:26:16 +0900

> see what the rest of the WG wants.

Thank you. I wanted to raise a voice that while the need for the
returning the URL
seemed to have come to a consensus, the syntax has not, unlike Mike wrote.

> towards the one that doesn't add a normative dependency on an unfinished

FYI, I have not suggested to reference HAL or other unfinished specifications,
but incorporate the syntax. If there is to be a reference, then that is for the
curtesy and will be an informational reference.

As to the actual editing is concerned, may I suggest the reverse: i.e.,
keep the current text (-05) and add a note for discussion.
It is customary in the standardization process that the change to the text
is not to be incorporated until the resolution from the comments are reached.
If the text is changed, then it means that the resolution is reached,
which is not the case. Even "ne bis in idem" may kick in, which effectively
prohibit the change back.

Nat

---

From: Nat Sakimura <[email-masked]>
Date: Thu, 14 Feb 2013 12:31:15 +0900

I thought your concern about DELETE was whether the client should be
allowed to erase the registration data.
I thought PUT with an empty values would achieve a similar effect.
Or did you mean that with PUT, the server default kicks in and
parameters are set to the defaults?
If that is the case, they are quite different, I agree.

On the effect of DELETE, +1 to Tim's comment.

Nat

---

From: Mike Jones <[email-masked]>
Date: Thu, 14 Feb 2013 03:45:38 +0000

I agree with you that in the standards process, changes should not be introduced until there is consensus on them. However in this particular case, the problem is that in -05, many changes were introduced without consensus, or even prior review by the working group.  Thus, as previously discussed, unless consensus becomes apparent for those changes, the default action should be to revert those changes.

The introduction of the baroque _links syntax was one such change.

-- Mike
From: Nat Sakimura
Sent: 2/13/2013 7:26 PM

Nat

---

From: Justin Richer <[email-masked]>
Date: Thu, 14 Feb 2013 08:53:39 -0500

+1 to this. And I'd also be fine if it wasn't MTI (server returns a 405 
Method Not Allowed) for servers that don't want to do it at all.

  -- Justin

On 02/13/2013 04:26 PM, Tim Bray wrote:
> A DELETE is an http request that asks the server to delete something. 
>  We probably would want to avoid writing a requirement into the 
> standard that the server has to comply.  So you get back a 204 if it 
> worked, a 404 if there is no such registration, a 403 if there is but 
> the server declines to delete, etc. Seems pretty straightforward. -T
>
> On Wed, Feb 13, 2013 at 12:18 PM, John Bradley <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>     The general not in that a client can DELETE it's record is a
>     implication I don't like.  I think that is for the server to
>     decide and if it is not actually deleting it then DELETE is the
>     wrong verb to use.
>
>     John B.
>
>     On 2013-02-13, at 3:31 PM, Nat Sakimura <[email-masked]
>     <mailto:[email-masked]>> wrote:
>
>     > Feb 14, 2013 0:10?John Bradley <[email-masked]
>     <mailto:[email-masked]>> ??????:
>     >
>     >> I am not violently opposed to PUT as a option that completely
>     replaces the resource setting all unsent claims back to the defaults.
>     >>
>     >> I don't have a good feeling about DELETE,  I think we still
>     need more discussion on what it means, what privileges it takes to
>     invoke it etc.
>      revoked etc is better and that can be done with a claim in the
>     update endpoint.
>     >>
>     >> On 2013-02-13, at 12:00 PM, Justin Richer <[email-masked]
>     <mailto:[email-masked]>> wrote:
>     >>
>     >>> Would it be reasonable to mark the PUT and DELETE methods as
>     optional for the server to implement, but with defined semantics
>     if they do? I want to keep GET and POST(create) as mandatory, as I
>     think that's the minimal set of functionality required.
>     >>>
>     >>> -- Justin
>     >>>
>     >>>> I think it is also us full to have other tokens used at the
>     update endpoint.  I can see the master token used to update all
>     the clients it has registered as part of API management.
>     >>>> I think GET and POST are relatively clear.   I don't know
>     about expelling PUT to developers.  I think POST with a client_id
>     to a (separate discussion) update_uri works without restricting it
>     to PUT.
>     >>>>
>     >>>> I think DELETE needs to be better understood.   I think a
>     status that can be set for client lifecycle is better than letting
>     a client delete a entry.
>     >>>> In some cases there will be more than one instance of a
>     client and letting them know they have been turned off for a
>     reason is better than making there registration disappear.
>     >>>> On 2013-02-11, at 6:14 PM, Justin Richer <[email-masked]
>     <mailto:[email-masked]>> wrote:
>     >>>>
>     >>>>> Draft -05 of OAuth Dynamic Client Registration [1] defines
>     several operations that the client can take on its behalf as part
>     of the registration process. These boil down to the basic CRUD
>     operations that you find in many APIs: Create, Read, Update,
>     Delete. Draft -00 defined only the "Create" operation, draft -01
>     through -04 added the "Update" operation, switched using the
>     "operation=" parameter.
>     >>>>>
>     >>>>> Following several suggestions to do so on the list, the -05
>     draft defines these operations in terms of a RESTful API for the
>     client. Namely:
>     >>>>>
>     >>>>> - HTTP PUT to update endpoint (with
>     registration_access_token) => Update the registered information
>     for this client
>     >>>>> - HTTP GET to update endpoint (with
>     registration_access_token) => read the registered information for
>     this client
>     >>>>> - HTTP DELETE to update endpoint (with
>     registration_access_token) => Delete (unregister/de-provision)
>     this client
>     >>>>>
>     >>>>> The two main issues at stake here are: the addition of the
>     READ and DELETE methods, and the use of HTTP verbs following a
>     RESTful design philosophy.
>     >>>>>
>     >>>>> Pro:
>     >>>>> - Full lifecycle management is common and is going to be
>     expected by many users of this protocol in the wild
>     >>>>>
>     >>>>> Cons:
>     >>>>> Alternatives include using an operational switch parameter
>     (like the old drafts), defining separate endpoints for every
>     action, or doing all operations on a single endpoint using verbs
>     to switch.
>     >>>>>
>     >>>>> -- Justin
>     >>>>>
>     >>>>> [email-masked] <mailto:[email-masked]>
>     >> [email-masked] <mailto:[email-masked]>
>     [email-masked] <mailto:[email-masked]>

---

From: John Bradley <[email-masked]>
Date: Thu, 14 Feb 2013 11:05:19 -0300

I agree with Tim that is the behaviour I would  expect to see with DELETE though I have a rd time seeing a server ever honouring it.

I guess that we need to clarify what happens with PUT and claims the server has defaults for, perhaps some that are not changeable by the client.   

Is not including a claim in a PUT the same as not including it in registration, and it is set to the default.  
If you want to set a claim to null then you must explicitly include the claim with null as the value. That is the previous logic we had for replace as the client wasn't getting back all the config in the response and couldn't know about defaults it wasn't setting.

Perhaps PUT causes unsent claims to be interpreted as if they are sent with a null value (I think that is a likely to cause tears personally).

In ether case the client is not deleted and can still be recovered and the client_id and associated permissions are still active.

DELETE to be used correctly is I think going to delete the client_id and all associated tokens and cause a ripple effect in removing grants associated with that client_id.  

It is a big difference and understanding what a AS is supposed to do to delete a client still seems a touch vague to me.   I understand the http verb but there is more to it than that if we want interoperability.

John

---

From: Justin Richer <[email-masked]>
Date: Thu, 14 Feb 2013 09:20:57 -0500

> In ether case the client is not deleted and can still be recovered and the client_id and associated permissions are still active.

What I had in mind from this conversation is something like this:

When sending an update, a client MUST send all metadata fields returned
from the server in its initial registration or previous read or update
call, including its client_id. A server MAY replace any missing or
invalid fields with default values, or it MAY return an error as
described in the Error Response section. A server MUST return all
provisioned fields in its response. A server MUST NOT change the
client_id field. A server MAY change the client_secret and/or
refresh_access_token fields.

> DELETE to be used correctly is I think going to delete the client_id and all associated tokens and cause a ripple effect in removing grants associated with that client_id.  

This is how I would interpret it as well. It's de-provisioning the
client, not resetting it.

-- Justin

---

From: John Bradley <[email-masked]>
Date: Thu, 14 Feb 2013 11:35:16 -0300

> refresh_access_token fields.

Yes that covers it.
> client, not resetting it.

That is what I would expect I don't know if it is a good idea, and adds to the size of the spec.   Having a not supported response is better but, I don't have a good feeling about it yet.

---

From: Brian Campbell <[email-masked]>
Date: Thu, 14 Feb 2013 19:47:00 -0700

Thanks for the feedback Prateek. I've tried to address some of you comments
and questions inline below.

On Wed, Feb 13, 2013 at 3:53 PM, Prateek Mishra
<[email-masked]>wrote:

> in draft-ietf-oauth-assertions-**10, there is a helpful distinction made

The guidance in §6 of draft-ietf-oauth-assertions-10 provides some
particular details of the more general general cases and they apply here as
well as the JWT draft. I'd like to avoid repeating the text and bloating
the documents.

> our developers have raised some questions about it.

It's not really intended to speak to the cases so much as provide the
required processing rules to validate the assertion in a reasonably secure
way. There is some simultaneous treatment of the client authentication case
and the authorization grant case because they have much more in common than
they have that's different. I can make a pass at better pointing out where
the differences are.

> BTW, it would also help if the rules in Section 3 were numbered.

I'll see what I can do. I assume it's possible with the xml2rfc markup but
have never done it.

> permitting a public client to participate in this exchange?

Very similar to SAML Web SSO where the client (HTTP user agent browser in
that case) is unidentified and the bearer assertion is the sole token
provided to identify/authenticate the subject and gain access. In some
cases there is a quite a bit of value in not having to provision or manage
the clients.

> has the right to present the SAML bearer assertion.

An AS is free to deploy that kind of policy as needed for the deployment or
product. But the spec intentionally does not dictate any such policy.  And
intentionally allows for unidentified clients.

> require end-user authentication to have taken place?
It's intended to convey whether or not the issuer actually authenticated
the subject or not. It's a distinction that, based on some conversations
I'd had, seemed like it might be useful for some. But much existing SAML
software doesn't work that way currently, which is why there's not a MUST
there. I'm trying to accommodate existing practice, within reason, while
also provide potentially useful functionality.

> omitted? If so, that should be stated clearly.

I've got a SHOULD NOT there. I don't think a MUST is reasonable based on
what I've seen actual deployments do. Please suggest some text, if you
think it can be improved.

>
>  I think this bullet refers to an advanced use-case and should be moved to
> an independent section.
>

I think it's pretty common actually.

> as identified in draft-ietf-oauth-assertions-**10.
>

No. I mean that the presenter (client) is acting on behalf of the user.
And the user probably isn't present for the transactions. "Autonomous" is a
word that kind of got inherited from the very early OAuth 2.0 drafts (
http://tools.ietf.org/html/draft-ietf-oauth-v2-08#section-1.4.4) and maybe
causes more trouble than it's worth here?

> implementation based on this text.

I agree that it's confusing and I believe it's partly because there's a
mistake in that text. It should say something more like "The presenter
SHOULD be identified in the <NameID> or similar element *within* the
<SubjectConfirmation> element, or by other available means like [
OASIS.saml-deleg-cs<http://tools.ietf.org/html/draft-ietf-oauth-saml2-bearer-15#ref-OASIS.saml-deleg-cs>
]"

Which is less open ended but still pretty open. The <NameID> or similar
text is becasue there can be a <BaseID>, <NameID>, or <EncryptedID> child
of the <SubjectConfirmation> and I was trying to avoid writing all that
out. The "SAML V2.0 Condition for Delegation Restriction" reference (which
probably should be expanded) is to a document that came along well after
regular SAML 2 and isn't widely supported, as far as I know. Neither of
these ways of expressing delegation is really used much in practice, as far
as I know, which makes it difficult to dictate particular requirements here.

> server needs to implement when processing this class of SAML assertions?

I don't understand? That's what 3 is all about. Or should be.

>
> 3) Has there been any interoperability testing of this profile? This is an
> activity we would be interested in.
>

Nothing official that I know of. I'd probably be worthwhile. But of course,
there's a lot involved in something like that.

---

From: Nat Sakimura <[email-masked]>
Date: Sun, 17 Feb 2013 15:04:04 +0900

> refresh_access_token fields.

Say the client registered some value. Sometime later, the server
changed a value due to some policy or security reasons etc. The client
when UPDATES with the previously registered value, what is going to
happen to the changed value?

> client, not resetting it.

For DELETE, I can think of an attack such that

1. Register as a client.
2. Send spam links to random users.
3. When user "authorizes", suck the user data such as contacts out.
4. DELETE the registration and disappear.

To prevent something like this, it should probably be something more
akin to "suspend" rather than completely de-provisioning.

---

From: Mike Jones <[email-masked]>
Date: Sun, 17 Feb 2013 06:11:50 +0000

I agree.  If we have it at all, DELETE should be a declaration by the Client that requests by it should no longer be honored.  It should be up to the Server whether to implement this as suspension or deletion.  At most, I believe it should be an optional operation, which MAY be supported.

				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Nat Sakimura
Sent: Saturday, February 16, 2013 10:04 PM
To: John Bradley
Cc: [email-masked]
Subject: Re: [OAUTH-WG] Registration: RESTful client lifecycle management

> When sending an update, a client MUST send all metadata fields 
> returned from the server in its initial registration or previous read 
> or update call, including its client_id. A server MAY replace any 
> missing or invalid fields with default values, or it MAY return an 
> error as described in the Error Response section. A server MUST return 
> all provisioned fields in its response. A server MUST NOT change the 

Say the client registered some value. Sometime later, the server changed a value due to some policy or security reasons etc. The client when UPDATES with the previously registered value, what is going to happen to the changed value?

1. Register as a client.

To prevent something like this, it should probably be something more akin to "suspend" rather than completely de-provisioning.
_______________________________________________
OAuth mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/oauth

---

From: Justin Richer <[email-masked]>
Date: Mon, 18 Feb 2013 09:22:22 -0500

Nat's attack vector presumes lack of logging on the server side, where 
doing a "delete" means that you can no longer see anything about who did 
what. You could make the same argument if you have a system where users 
can register themselves and delete their accounts at will -- someone 
creates a fly-by-night account, does bad things, deletes the account. If 
the site doesn't have detailed logs in both of these cases, yes, they'll 
be in the dark about the bad things that happened when the 
account/client was active. It's a valuable security consideration, but I 
don't think that it's enough to say that delete is no longer a valid 
operation.

I think it's up to the server what "delete" means under the hood, but 
the important bit for the protocol is that as far as the client is 
concerned, that client_id is dead now. I don't think it's worthwhile to 
specify it as a "suspend" operation, because to me "suspend" implies an 
ability to "unsuspend", and I really don't think we want to get into the 
complicated zombie OAuth client business. But whether on the server side 
"delete" translates to "delete everything from the database immediately 
and burn all records of it" or instead "set a flag on that client and 
all of its outstanding grants so that it can't be used but 
administrators can still poke it with a stick" is completely up to the 
implementation and its security considerations.

That said, I think it would make sense to at least describe this 
potential problem in the security considerations, and note that the 
client MUST NOT use the client_id again.

  -- Justin

---

From: Nat Sakimura <[email-masked]>
Date: Sat, 23 Feb 2013 07:56:27 +0900

Agreed with the security consideration.

Just for the record:
The life cycle as I understand would include the following.

   1. registration (creation)
   2. activation
   3. de-activation
   4. re-activation
   5. archival
   6. deletion

In the above thread, I was talking more about "3. archive".
We do not have to have the full life-cycle model here, but it may be a good
idea to document why we would not.

Nat

2013/2/18 Justin Richer <[email-masked]>

> what. You could make the same argument if you have a system where users can
> register themselves and delete their accounts at will -- someone creates a
> fly-by-night account, does bad things, deletes the account. If the site
> doesn't have detailed logs in both of these cases, yes, they'll be in the
> dark about the bad things that happened when the account/client was active.
> It's a valuable security consideration, but I don't think that it's enough
> to say that delete is no longer a valid operation.
>
> I think it's up to the server what "delete" means under the hood, but the
> important bit for the protocol is that as far as the client is concerned,
> that client_id is dead now. I don't think it's worthwhile to specify it as
> a "suspend" operation, because to me "suspend" implies an ability to
> "unsuspend", and I really don't think we want to get into the complicated
> zombie OAuth client business. But whether on the server side "delete"
> translates to "delete everything from the database immediately and burn all
> records of it" or instead "set a flag on that client and all of its
> outstanding grants so that it can't be used but administrators can still
> poke it with a stick" is completely up to the implementation and its
> security considerations.
>
> That said, I think it would make sense to at least describe this potential
> problem in the security considerations, and note that the client MUST NOT
> use the client_id again.
>
>  -- Justin
>
>
>> I agree.  If we have it at all, DELETE should be a declaration by the
>> Client that requests by it should no longer be honored.  It should be up to
>> the Server whether to implement this as suspension or deletion.  At most, I
>> believe it should be an optional operation, which MAY be supported.
>>
>>                                 -- Mike
>>
>> From: [email-masked] [mailto:[email-masked]**] On Behalf
>> Of Nat Sakimura
>> Say the client registered some value. Sometime later, the server changed
>> a value due to some policy or security reasons etc. The client when UPDATES
>> with the previously registered value, what is going to happen to the
>> changed value?
>>
>>  DELETE to be used correctly is I think going to delete the client_id and
>>>> all associated tokens and cause a ripple effect in removing grants
>>>> associated with that client_id.
>>>>
>> To prevent something like this, it should probably be something more akin
>> to "suspend" rather than completely de-provisioning.
>> ______________________________**_________________
>> OAuth mailing list
>> [email-masked]
>> https://www.ietf.org/mailman/**listinfo/oauth<https://www.ietf.org/mailman/listinfo/oauth>
>> ______________________________**_________________
>> OAuth mailing list
>> [email-masked]
>> https://www.ietf.org/mailman/**listinfo/oauth<https://www.ietf.org/mailman/listinfo/oauth>
>>
>
>