Subject: Re: [OAUTH-WG] Concerning OAuth introspection

From: Justin Richer <[email-masked]>
Date: Tue, 22 Jan 2013 14:00:15 -0500

(CC'ing the working group)

I'm not sure what the "action/operation" flag would accomplish. The idea 
behind having different endpoints in OAuth is that they each do 
different kinds of things. The only "action/operation" that I had 
envisioned for the introspection endpoint is introspection itself: "I 
have a token, what does it mean?"

Note that client_id and client_secret *can* already be used at this 
endpoint if the server supports that as part of their client credentials 
setup. The examples use HTTP Basic with client id and secret right now. 
Basically, the client can authenticate however it wants, including any 
of the methods that OAuth2 allows on the token endpoint. It could also 
authenticate with an access token. At least, that's the intent of the 
introspection draft -- if that's unclear, I'd be happy to accept 
suggested changes to clarify this text.

  -- Justin

On 01/22/2013 01:00 PM, Shiu Fun Poon wrote:
> Justin,
>
> This spec is looking good..
>
> One thing I would like to recommend is to add "action"/"operation" to 
> the request.  (and potentially add client_id and client_secret)
>
> So the request will be like :
> token REQUIRED
> operation (wording to be determine)  OPTIONAL inquire (default) | 
> revoke ...
> resource_id                                    OPTIONAL
> client_id OPTIONAL
> client_secret OPTIONAL
>
> And for the OAuth client information, it should be an optional 
> parameter (in case it is a public client or client is authenticated 
> with SSL mutual authentication).
>
> Please consider.
>
> ShiuFun

---

From: Nat Sakimura <[email-masked]>
Date: Wed, 23 Jan 2013 10:05:32 +0900

"Action" goes against REST principle.
I do not think it is a good idea.

=nat via iPhone

Jan 23, 2013 4:00、Justin Richer <[email-masked]> のメッセージ:

> I'm not sure what the "action/operation" flag would accomplish. The idea behind having different endpoints in OAuth is that they each do different kinds of things. The only "action/operation" that I had envisioned for the introspection endpoint is introspection itself: "I have a token, what does it mean?"
>
> Note that client_id and client_secret *can* already be used at this endpoint if the server supports that as part of their client credentials setup. The examples use HTTP Basic with client id and secret right now. Basically, the client can authenticate however it wants, including any of the methods that OAuth2 allows on the token endpoint. It could also authenticate with an access token. At least, that's the intent of the introspection draft -- if that's unclear, I'd be happy to accept suggested changes to clarify this text.
>
>  -- Justin
>
>> One thing I would like to recommend is to add "action"/"operation" to the request.  (and potentially add client_id and client_secret)
>>
>> operation (wording to be determine)  OPTIONAL inquire (default) | revoke ...
>> resource_id                                    OPTIONAL
>> client_id                                         OPTIONAL
>> client_secret                                   OPTIONAL
>>
>> And for the OAuth client information, it should be an optional parameter (in case it is a public client or client is authenticated with SSL mutual authentication).
>>
>> Please consider.
>>
>> ShiuFun
>
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth

---

From: Justin Richer <[email-masked]>
Date: Wed, 23 Jan 2013 10:19:02 -0500

> For the client_id, if there is no client_secret, how is that 
> information going to flow thru ?  In the oauth spec, the protocol 
> allows you to specify the client_id and secret in the payload.  So it 
> would be good for this spec to follow as closely to the oauth spec, 
> that will be great.
>
The idea of the introspection endpoint is to exactly mimic the OAuth2 
capabilities for client authentication as well as allowing for 
authorization based on a valid OAuth2 access token, as Section 2.1 states:

    The endpoint SHOULD also require some form of authentication to
    access this endpoint, such as the Client Authentication as described
    in OAuth 2 Core Specification
    <http://tools.ietf.org/id/draft-richer-oauth-introspection-01.html#RFC6749>
    [RFC6749] or a separate OAuth2 Access Token.

This means that if you have no client secret, you don't send one. You 
can use Basic or form parameters. If you have a client assertion, you 
use that. If you have an access token, you use that. Basically, however 
your clients normally authenticate with your AS, you can do that here. 
Or if you want to, the token that you're introspecting can be its own 
key -- a use that I haven't called out specifically in the document yet 
because I'm not fully convinced of its utility.

> And for the action/operation, separate endpoint will be one way of 
> handling it.  However are you going to dictate what the endpoint is ?  
> If not, it will make sense for the request to be self-identified.  
> That will provide the most flexibility.
>
Yes, the specification specifically defines a separate endpoint. From 
the introduction:

    This specification defines an Introspection Endpoint that allows the
    holder of a token to query the Authorization Server to discover the
    set of metadata for a token.

And all of section 2 is titled "Introspection Endpoint" for this reason 
as well.

If there is a way either of these points could be made more clear, 
please suggest new language for the specification and I'll incorporate it.

  -- Justin

> Regards.
>
>
> On Tue, Jan 22, 2013 at 2:00 PM, Justin Richer <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>     I'm not sure what the "action/operation" flag would accomplish.
>     The idea behind having different endpoints in OAuth is that they
>     each do different kinds of things. The only "action/operation"
>     that I had envisioned for the introspection endpoint is
>     introspection itself: "I have a token, what does it mean?"
>
>     Note that client_id and client_secret *can* already be used at
>     this endpoint if the server supports that as part of their client
>     credentials setup. The examples use HTTP Basic with client id and
>     secret right now. Basically, the client can authenticate however
>     it wants, including any of the methods that OAuth2 allows on the
>     token endpoint. It could also authenticate with an access token.
>     At least, that's the intent of the introspection draft -- if
>     that's unclear, I'd be happy to accept suggested changes to
>     clarify this text.
>
>      -- Justin
>
>
>>     One thing I would like to recommend is to add
>>     "action"/"operation" to the request.  (and potentially add
>>     client_id and client_secret)
>>
>>     parameter (in case it is a public client or client is
>>     authenticated with SSL mutual authentication).
>>
>>     Please consider.
>>
>>     ShiuFun
>
>

---

From: Justin Richer <[email-masked]>
Date: Wed, 23 Jan 2013 10:47:01 -0500

Which brings up an interesting question for the Registration doc: right
now, it's set up as a single endpoint with three operations. We could
instead define three endpoints for the different operations.

I've not been keen to make that deep of a cutting change to it, but it
would certainly be cleaner and more RESTful API design. What do others
think?

-- Justin

---

From: Sergey Beryozkin <[email-masked]>
Date: Wed, 23 Jan 2013 16:34:39 +0000

> would certainly be cleaner and more RESTful API design. What do others
IMHO the purity should be balanced against the practicality/simplicity
of the implementation.
Talking about 3 endpoints at the spec level may be treated as the exact
requirement to have 3 separate application endpoints for the single type
of activity, the registration. Can the spec be re-worded such that
"resources" are used instead of endpoints or similar, example, "resource
available at /a will support the following, at /b - something else", or
may be something similar,  thus it will read better too from the design
point of view, and let implementers to use 1 endpoint or 3 ones,
whichever way they prefer it

Thanks, Sergey

>> Jan 23, 2013 4:00、Justin Richer<[email-masked]>  のメッセージ:
>>

---

From: Anthony Nadalin <[email-masked]>
Date: Wed, 23 Jan 2013 17:14:50 +0000

Why not just have a physical and logical endpoint options

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Justin Richer
Sent: Wednesday, January 23, 2013 7:47 AM
To: Nat Sakimura
Cc: Shiu Fun Poon; [email-masked]
Subject: Re: [OAUTH-WG] Concerning OAuth introspection

Which brings up an interesting question for the Registration doc: right now, it's set up as a single endpoint with three operations. We could instead define three endpoints for the different operations.

I've not been keen to make that deep of a cutting change to it, but it would certainly be cleaner and more RESTful API design. What do others think?

-- Justin

On 01/22/2013 08:05 PM, Nat Sakimura wrote:
>>> One thing I would like to recommend is to add "action"/"operation" 
>>> to the request.  (and potentially add client_id and client_secret)
>>>

---

From: Eve Maler <[email-masked]>
Date: Wed, 23 Jan 2013 09:18:24 -0800

Agreed that REST purity may come at a cost that's too high. On the other hand, it's a useful exercise to imagine how much more benefit could potentially be gotten "for free" if we look at it through a pure-REST lens, not just with what's already been specified but the whole picture.

If what you're registering is a client descriptor, then creating a new one, updating an existing one, deleting, and even patching could come for free if something like the following framework is used:

http://tools.ietf.org/html/draft-pbryan-http-json-resource-03

With standard libraries possibly floating around to support this framework (I think Paul B wrote one; maybe he open-sourced it?), it starts to become a lot cheaper to support client registration on both sides of the interaction.

	Eve

>>>>> And for the OAuth client information, it should be an optional parameter (in case it is a public client or client is authenticated with SSL mutual authentication).

Eve Maler                                  http://www.xmlgrrl.com/blog
+1 425 345 6756                         http://www.twitter.com/xmlgrrl

---

From: Justin Richer <[email-masked]>
Date: Wed, 23 Jan 2013 12:18:20 -0500

Because then nobody would know how to actually use the thing.

In my opinion, this is a key place where this kind of flexibility is a
very bad thing. Registration needs to work one fairly predictable way.

-- Justin

---

From: Anthony Nadalin <[email-masked]>
Date: Wed, 23 Jan 2013 17:21:16 +0000

Registration has to work in a multi-tenant environment  so flexibility is needed

-----Original Message-----
From: Justin Richer [mailto:[email-masked]] 
Sent: Wednesday, January 23, 2013 9:18 AM
To: Anthony Nadalin
Cc: Nat Sakimura; Shiu Fun Poon; [email-masked]
Subject: Re: [OAUTH-WG] Concerning OAuth introspection

In my opinion, this is a key place where this kind of flexibility is a very bad thing. Registration needs to work one fairly predictable way.

-- Justin

---

From: Justin Richer <[email-masked]>
Date: Wed, 23 Jan 2013 12:26:57 -0500

I completely disagree with this assessment. Multi-tenancy will work just
fine (or even better) if everyone uses the same pattern. Telling someone
"it might be three different urls or it might be all one url with a
parameter" is just asking for a complete disaster. What does the
flexibility of allowing two approaches actually accomplish?

You can argue about the merits of either approach, but having both as
unspecified options for registration, which is meant to help things get
going in a cold-boot environment, is just plain nuts.

-- Justin

---

From: Eve Maler <[email-masked]>
Date: Wed, 23 Jan 2013 09:28:13 -0800

Tony took the words right out of my mouth. :-) Or, at least, the moment someone expresses an actual need for the next piece of flexibility (beyond "Wouldn't it be cool if..."* to "I have a customer that needs..."), you're on the slope towards maybe benefiting from enabling more and more of the HTTP verbs where only one or two made sense before. One way to do this is to work within a pure-REST framework but say that only POST and GET are supported, with all others producing an error. Over time, if DELETE is needed, it's easier to turn it on.

	Eve

* "The only thing worse than generalizing from one example is generalizing from no examples at all." Not sure if Tony is expressing an actual need or not.

---

From: Eve Maler <[email-masked]>
Date: Wed, 23 Jan 2013 09:29:49 -0800

Rudely responding to myself: I'm not saying this approach should definitely be taken, just that it's a good idea to spend 15 minutes looking at the benefits and downsides of it vs. the current laser-focus approach.

	Eve

---

From: Justin Richer <[email-masked]>
Date: Wed, 23 Jan 2013 12:30:54 -0500

But it's already not a fully RESTful setup, and it's not really meant to
be as it stands. I realize that's how the original UMA registration spec
did things, but the rest of OAuth doesn't work that way. I would rather
it be parallel with the rest of the framework, all ideals aside.

Which brings us back to my original point: OAuth2 does a pretty good job
at splitting up different endpoints for different functions. That's what
I'm asking here, more than anything else. Do we want to define three
endpoints:

- client registration endpoint
- client update endpoint
- client secret rotation endpoint

As opposed to a single registration endpoint with a switch?

-- Justin

---

From: Mike Jones <[email-masked]>
Date: Wed, 23 Jan 2013 17:33:07 +0000

No, we want one endpoint.  Keep it simple.

________________________________
From: Justin Richer
Sent: 1/23/2013 9:31 AM
To: Eve Maler
Cc: Shiu Fun Poon; [email-masked]
Subject: Re: [OAUTH-WG] Concerning OAuth introspection

-- Justin

---

From: Anthony Nadalin <[email-masked]>
Date: Wed, 23 Jan 2013 17:46:54 +0000

It will not work the way you have it, as people do multi-tendency different and they are already stuck with the method that they have chosen, so they need the flexability, to restrict this is nuts as people won't use it.

-----Original Message-----
From: Justin Richer [mailto:[email-masked]] 
Sent: Wednesday, January 23, 2013 9:27 AM
To: Anthony Nadalin
Cc: Nat Sakimura; Shiu Fun Poon; [email-masked]
Subject: Re: [OAUTH-WG] Concerning OAuth introspection

I completely disagree with this assessment. Multi-tenancy will work just fine (or even better) if everyone uses the same pattern. Telling someone "it might be three different urls or it might be all one url with a parameter" is just asking for a complete disaster. What does the flexibility of allowing two approaches actually accomplish?

You can argue about the merits of either approach, but having both as unspecified options for registration, which is meant to help things get going in a cold-boot environment, is just plain nuts.

-- Justin

---

From: Justin Richer <[email-masked]>
Date: Wed, 23 Jan 2013 13:05:10 -0500

I am very confused, and I need someone to explain to me what I am
missing. Why won't it work to just pick one? What are people "already
stuck with" that this would affect? It's not like we're trying to unseat
a well-established protocol with a wide installation base here.

How will giving people the choice between:

    /oauth/register?operation=client_register
    /oauth/register?operation=client_update
    /oauth/register?operation=rotate_secret

and:

    /oauth/client_register
    /oauth/client_update
    /oauth/rotate_secret

help multitenancy? How does it even affect that use case? Consider that
the base URL for all of these is completely up to the host environment
(nothing is bound to the root URL). Consider that clients still have to
know what the URL (or URLs) are, in either case. Consider that clients
still need to know how to manage all the parameters and responses.

If anything, keeping it the way that it is with a single URL could be
argued to help multitenancy because setting up routing to multiple URL
endpoints can sometimes be problematic in hosted environments. However,
OAuth already defines a bunch of endpoints, and we have to define at
least one more with this extension, so I'm not convinced that having
three with specific functions is really any different from having one
with three functions from a development, deployment, and implementation
perspective. I can tell you from experience that in our own server code,
the difference is trivial. (And from OAuth1 experience, you can always
have a query parameter as part of your endpoint URL if you need to. You
might hate yourself for doing it that way, but nothing says your base
URL can't already have parameters on it. A client just needs to know how
to appropriately tack its parameters onto an existing URL, and any HTTP
client worth its salt will know how to augment a query parameter set
with new items.)

The *real* difference between the two approaches is a philosophical
design one. The former overloads one URL with multiple functions
switched by a flag, the latter uses the URL itself as an implicit flag.
Under the hood, these could (and in many cases will) be all served by
the same chunks of code. The only difference is how this switch in
functionality is presented.

With that said, can somebody please explain to me how allowing *both* of
these as options simultaneously (what I understand Tony to be
suggesting) is a good idea, or how multitenancy even comes into play?
Because I am completely not seeing how these are related.

Thanks,
-- Justin

---

From: Todd W Lainhart <[email-masked]>
Date: Wed, 23 Jan 2013 13:40:47 -0500

> On the other hand, it's a useful exercise to imagine how much more 
benefit could potentially be gotten "for free" if we look at it through a 
pure-REST lens, not just with what's already been specified but the whole 
picture.

+1

  -- Todd

From:   Eve Maler <[email-masked]>
To:     Sergey Beryozkin <[email-masked]>, 
Cc:     Paul Bryan <[email-masked]>, "[email-masked] WG" 
<[email-masked]>
Date:   01/23/2013 12:18 PM
Subject:        Re: [OAUTH-WG] Concerning OAuth introspection
Sent by:        [email-masked]

Agreed that REST purity may come at a cost that's too high. On the other 
hand, it's a useful exercise to imagine how much more benefit could 
potentially be gotten "for free" if we look at it through a pure-REST 
lens, not just with what's already been specified but the whole picture.

If what you're registering is a client descriptor, then creating a new 
one, updating an existing one, deleting, and even patching could come for 
free if something like the following framework is used:

With standard libraries possibly floating around to support this framework 
(I think Paul B wrote one; maybe he open-sourced it?), it starts to become 
a lot cheaper to support client registration on both sides of the 
interaction.

                 Eve

On 23 Jan 2013, at 8:34 AM, Sergey Beryozkin <[email-masked]> wrote:

>>>> I'm not sure what the "action/operation" flag would accomplish. The 
idea behind having different endpoints in OAuth is that they each do 
different kinds of things. The only "action/operation" that I had 
envisioned for the introspection endpoint is introspection itself: "I have 
a token, what does it mean?"
endpoint if the server supports that as part of their client credentials 
setup. The examples use HTTP Basic with client id and secret right now. 
Basically, the client can authenticate however it wants, including any of 
the methods that OAuth2 allows on the token endpoint. It could also 
authenticate with an access token. At least, that's the intent of the 
introspection draft -- if that's unclear, I'd be happy to accept suggested 
changes to clarify this text.
revoke ...
>>>>> And for the OAuth client information, it should be an optional 
parameter (in case it is a public client or client is authenticated with 
SSL mutual authentication).

---

From: Phil Hunt <[email-masked]>
Date: Wed, 23 Jan 2013 10:54:57 -0800

My understanding is OAuth is an HTTP protocol.  It is not intended to be REST specific or by implication be RESTful.

@independentid
www.independentid.com
[email-masked]

On 2013-01-23, at 10:40 AM, Todd W Lainhart wrote:

> > On the other hand, it's a useful exercise to imagine how much more benefit could potentially be gotten "for free" if we look at it through a pure-REST lens, not just with what's already been specified but the whole picture. 
> 
> +1
> 
>   -- Todd
> 
> 
> 
> 
> 
> 
> 
> Cc:        Paul Bryan <[email-masked]>, "[email-masked] WG" <[email-masked]>

---

From: Eve Maler <[email-masked]>
Date: Wed, 23 Jan 2013 12:12:49 -0800

I'd say OAuth is an HTTP security mechanism or protocol (50,000-foot view). To the extent that it, or its constituent parts, defines endpoints, it also is a security API or set of APIs (10,000-foot view). Since its endpoints use HTTP, this gives the opportunity to ask the question: how RESTful should its APIs be? I'm hearing one firm design principle:

- Make new constituent parts be consonant with the rest of OAuth design

And a couple of competing soft design principles:

- Make it easy to develop endpoints (especially but not exclusively client-side)
- Make it flexible to accommodate lots of situations

I'm suggesting considering another one, possibly ranking it lower than others:

- Make its endpoints operate in a RESTful, resource-oriented way

(While OAuth hasn't gone through this exercise, UMA has, and we included a DP about RESTfulness; you can see the results here: http://kantarainitiative.org/confluence/display/uma/UMA+Requirements That's why we defined draft-hardjono-oauth-resource-reg the way we did.)

The dyn reg spec is a kind of bootstrapping spec, so one can expect that it would be out of the REST mainstream in any case -- its credential provisioning function is sui generis. But the functions to create and update metadata look like pretty ordinary CRUD functions that usually correspond to various POST or PUT patterns in REST. If the client metadata were conceived of as a true web resource, it's not wildly out of left field to consider defining their creation and management in high-REST-maturity ways, and even imagine what (say) DELETE, PATCH, and GET might mean, even if not allowed in the spec today.

(Justin, I promise I'm not trying to give you a hard time. :-)

	Eve

---

From: Justin Richer <[email-masked]>
Date: Wed, 23 Jan 2013 15:22:07 -0500

While Eve is right in principle, I think it's better for everyone if 
things remain consistent across different endpoints where possible. This 
is why registration now does form input and json output, for instance. 
Still simple, not as RESTy, but ultimately REST-friendly, which is all 
OAuth ever sought to be.

  -- Justin

On 01/23/2013 03:12 PM, Eve Maler wrote:
>>>>>> Jan 23, 2013 4:00?Justin Richer<[email-masked]>  ??????:
>>>>>>

---

From: Sergey Beryozkin <[email-masked]>
Date: Thu, 24 Jan 2013 10:56:31 +0000

>     /oauth/register?operation=rotate_secret

I like this most, would rename it to say

/oauth/client/registration
or
/oauth/client-registration

etc

and reword the spec such that it will let those who implement do it with 
one endpoint or many, whatever is preferred

Cheers, Sergey

>> Cc: Nat Sakimura; Shiu Fun Poon;[email-masked]
>>> Cc: Nat Sakimura; Shiu Fun Poon;[email-masked]
>>>> From:[email-masked]  [mailto:[email-masked]] On
>>>> Behalf Of Justin Richer
>>>> Cc: Shiu Fun Poon;[email-masked]

---

From: Sergey Beryozkin <[email-masked]>
Date: Thu, 24 Jan 2013 11:02:05 +0000

> Still simple, not as RESTy, but ultimately REST-friendly, which is all

+1; personally I've no problems for example working with production 
quality WS services supporting a higher-level RS application/services,
but indeed it is important to attempt to keep it as close as possible to 
the original idea of OAuth being REST friendly

thanks, Sergey

>> (While OAuth hasn't gone through this exercise, UMA has, and we included a DP about RESTfulness; you can see the results here:http://kantarainitiative.org/confluence/display/uma/UMA+Requirements  That's why we defined draft-hardjono-oauth-resource-reg the way we did.)
>>
>> On 23 Jan 2013, at 10:54 AM, Phil Hunt<[email-masked]>  wrote:
>>
>>>> From:        Eve Maler<[email-masked]>
>>>> To:        Sergey Beryozkin<[email-masked]>,
>>>> Cc:        Paul Bryan<[email-masked]>,"[email-masked] WG"  <[email-masked]>
>>>> Sent by:[email-masked]
>>>>
>>>>
>>>>
>>>> On 23 Jan 2013, at 8:34 AM, Sergey Beryozkin<[email-masked]>  wrote:
>>>>
>>>> Eve Malerhttp://www.xmlgrrl.com/blog
>>>> +1 425 345 6756http://www.twitter.com/xmlgrrl
>>>>
>> Eve Malerhttp://www.xmlgrrl.com/blog
>> +1 425 345 6756http://www.twitter.com/xmlgrrl
>>
>>
>>
>>

---

From: Justin Richer <[email-masked]>
Date: Thu, 24 Jan 2013 09:26:12 -0500

On 01/24/2013 05:56 AM, Sergey Beryozkin wrote:
> and reword the spec such that it will let those who implement do it 
> with one endpoint or many, whatever is preferred
>

That's the whole point of this discussion -- I don't believe you can 
have it both ways.

In one way, you say there are three endpoints and, if you're keeping 
with the rest of OAuth, you don't give them official URL patterns that 
they must follow. How the client gets those endpoints is up to discovery 
or configuration, but the client has an internal map from each bit of 
functionality to a particular URL that's specific to the service, much 
in the same way that the client today has to map the authorization and 
token endpoints. In the other method, you've got one endpoint that the 
client sends a well-defined parameter to in order to accomplish the same 
goal.

So if you allow both at once, does a client send the "operation" 
parameter or not? Is it looking for one url or three to store in its 
configuration? I don't think this level of flexibility buys you anything 
useful, and I strongly believe that it will deeply hurt the 
functionality of dynamic registration if it's allowed.

As it stands today, you can still make the URL whatever you want. If we 
went with three endpoints you could also make those URLs whatever you 
wanted. Nobody has yet pointed out to me what the actual benefit is of 
making both valid.

I personally prefer the method of three endpoint URLs because it's 
cleaner and semantically equivalent, but I am hesitant to change that 
behavior unless there's strong working group support for it. I haven't 
seen real support for it yet -- it's not a good call to make it fully 
RESTful, and it's not a good call to leave it undefined. A client MUST 
have a very clear recipe of what to do on startup for this to work in 
the wild.

  -- Justin

>>> It will not work the way you have it, as people do multi-tendency 
>>> different and they are already stuck with the method that they have 
>>> chosen, so they need the flexability, to restrict this is nuts as 
>>> people won't use it.
>>>
>>> I completely disagree with this assessment. Multi-tenancy will work 
>>> just fine (or even better) if everyone uses the same pattern. 
>>> Telling someone "it might be three different urls or it might be all 
>>> one url with a parameter" is just asking for a complete disaster. 
>>> What does the flexibility of allowing two approaches actually 
>>> accomplish?
>>>
>>> You can argue about the merits of either approach, but having both 
>>> as unspecified options for registration, which is meant to help 
>>> things get going in a cold-boot environment, is just plain nuts.
>>>
>>>
>>> -- Justin
>>>
>>>
>>>
>>>> In my opinion, this is a key place where this kind of flexibility 
>>>> is a very bad thing. Registration needs to work one fairly 
>>>> predictable way.
>>>>
>>>> -- Justin
>>>>
>>>>> Which brings up an interesting question for the Registration doc: 
>>>>> right now, it's set up as a single endpoint with three operations. 
>>>>> We could instead define three endpoints for the different operations.
>>>>>
>>>>> I've not been keen to make that deep of a cutting change to it, 
>>>>> but it would certainly be cleaner and more RESTful API design. 
>>>>> What do others think?
>>>>>
>>>>> -- Justin
>>>>>
>>>>>
>>>>>>> this endpoint if the server supports that as part of their 
>>>>>>> client credentials setup. The examples use HTTP Basic with 
>>>>>>> client id and secret right now. Basically, the client can 
>>>>>>> authenticate however it wants, including any of the methods that 
>>>>>>> OAuth2 allows on the token endpoint. It could also authenticate 
>>>>>>> with an access token. At least, that's the intent of the

---

From: Brian Campbell <[email-masked]>
Date: Thu, 24 Jan 2013 08:01:08 -0700

Well, you *can* have it both ways. But to your point Justin - what's the
value in it? Allowing for both adds a bunch of unnecessary complexity while
only adding flexibility for the sake of flexibility with no tangible
benefit.

On Thu, Jan 24, 2013 at 7:26 AM, Justin Richer <[email-masked]> wrote:

> That's the whole point of this discussion -- I don't believe you can have
> it both ways.
>

---

From: Sergey Beryozkin <[email-masked]>
Date: Thu, 24 Jan 2013 15:38:08 +0000

> have a very clear recipe of what to do on startup for this to work in

Basically, I haven't thought deeply about it. What I meant was that with

/oauth/client/registration
/oauth/client/somethingelse

I can implement easily by having a single endpoint or 2 ones (with the 
endpoint not necessarily meaning it runs in its own container), but the 
client won't know, I'm assuming 'the endpoint' does not mean its URI 
will need to have a unique port.
Sorry if I've missed the point :-)

Sergey

---

From: Justin Richer <[email-masked]>
Date: Wed, 30 Jan 2013 10:20:29 -0500

> Hi.. Tony.. You are able to present this better than I do.
>
> Justin,
>
> Currently as it is, the spec is unflexible. So when I send a request
> to an endpoint, the endpoint will need to have information like
> /revoke, /introspection, and others. I can imagine the documented
> usage of this will a pages long just to describe all the endpoint that
> is needed to support an application. (so far, /authz, /token,
> /introspection, /revoke, /.....), and this will be painful in the
> multi-tenant environment.
>
> So why not allow the flexibility of using one endpoint /token (example
> only), and make the caller to tell you want the caller wants ? It can
> be an optional field, and a hint to the authorization/token endpoint
> on what you want to do.
>
This is incompatible with OAuth as it stands today, which defines the
auth endpoint and token endpoint as logically separate, and therefore
there is not a parameter defined that would allow for such functionality
switching.

That said, an *installation* could implement it this way if they wanted
to, they'd just have to document the endpoints like this:

token endpoint: /oauth?op=token
auth endpoint: /oauth?op=auth
introspection endpoint: /oauth?op=introspect
revocation endpoint: /oauth?op=revoke

etc. The key difference here is that the "op=" parameter is *system
specific* and is *not* part of the spec itself. And I think that's a
good design to continue to follow.

Right now, the registration endpoint is the only one that defines an
"operation" parameter, and I was positing the question of defining it in
terms of three different endpoints instead. Most of the time, these
endpoints will have different URLs, as outlined below, but specific
instances could use some kind of "operation" parameter if they wanted to.

Defining it as one endpoint with a switch parameter actually decreses
flexibility quite a lot, especially if you're talking about dispatching
to different kinds of functionality all together, which is the use case
you brought up. There are some places where that could make sense, and
the definition of different endpoints allows you to do that in specific
instances of a system without breaking the assumptions of clients.

What Tony was talking about was allowing something to be either three
different URLs *or* using a spec-defined "operation" parameter. That
suggestion is completely nuts, in my opinion.

> And it does not violate the rest/json guideline.
Yes it absolutely does. The REST principle is that a URL represents one
entity and the HTTP verbs represent different actions on that entity.
Using a query parameter to switch is very much directly against REST
guidelines. Not to say that OAuth is RESTful -- it's not, by a long
shot. But it does follow many rest-like principles, the endpoint
definitions being one of them.

>
> Even with oauth specification, it provides a hint on what is to come,
> e.g. grant_type refresh_token, indicates you want to exchange a valid
> refresh_token to an access_token. There is something in the payload
> which tell you what you need to do. In this case, there is nothing in
> the payload which indicate what is expected.
These are functionality switches on the same kind of action, not
dispatch to different actions. you still do authentication/authorization
at the auth endpoint, you still get tokens from the token endpoint, etc.

>
> If you standard that now (on the optional field), there is a chance
> that companies can implement this according to what will work best for
> them, and we actually have a chance to get this working between
> different products.
It's too late to standardize that field in the core, which is really
where it would belong. But as it stands today, an OAuth client is going
to need to be able to handle separate URLs for each defined endpoint
already, so it can already handle the case where it happens to be the
same base URL with different operations.

For what it's worth, what I was trying to get discussion on was whether
it made sense to make Dynamic Registration look like the rest of OAuth
with separate endpoints, or not.

-- Justin

>
>
> On Wed, Jan 23, 2013 at 1:05 PM, Justin Richer <[email-masked]
>     missing. Why won't it work to just pick one? What are people
>     "already stuck with" that this would affect? It's not like we're
>     trying to unseat a well-established protocol with a wide
>     installation base here.
>
>     help multitenancy? How does it even affect that use case? Consider
>     that the base URL for all of these is completely up to the host
>     environment (nothing is bound to the root URL). Consider that
>     clients still have to know what the URL (or URLs) are, in either
>     case. Consider that clients still need to know how to manage all
>     the parameters and responses.
>
>     If anything, keeping it the way that it is with a single URL could
>     be argued to help multitenancy because setting up routing to
>     multiple URL endpoints can sometimes be problematic in hosted
>     environments. However, OAuth already defines a bunch of endpoints,
>     and we have to define at least one more with this extension, so
>     I'm not convinced that having three with specific functions is
>     really any different from having one with three functions from a
>     development, deployment, and implementation perspective. I can
>     tell you from experience that in our own server code, the
>     difference is trivial. (And from OAuth1 experience, you can always
>     have a query parameter as part of your endpoint URL if you need
>     to. You might hate yourself for doing it that way, but nothing
>     says your base URL can't already have parameters on it. A client
>     just needs to know how to appropriately tack its parameters onto
>     an existing URL, and any HTTP client worth its salt will know how
>     to augment a query parameter set with new items.)
>
>     The *real* difference between the two approaches is a
>     philosophical design one. The former overloads one URL with
>     multiple functions switched by a flag, the latter uses the URL
>     itself as an implicit flag. Under the hood, these could (and in
>     many cases will) be all served by the same chunks of code. The
>     only difference is how this switch in functionality is presented.
>
>
>     With that said, can somebody please explain to me how allowing
>     *both* of these as options simultaneously (what I understand Tony
>     to be suggesting) is a good idea, or how multitenancy even comes
>     into play? Because I am completely not seeing how these are related.
>
>     Thanks,
>     -- Justin
>
>
>
>
>>     Cc: Nat Sakimura; Shiu Fun Poon; [email-masked] <mailto:[email-masked]>
>>>     Cc: Nat Sakimura; Shiu Fun Poon; [email-masked] <mailto:[email-masked]>
>>>>     From: [email-masked] <mailto:[email-masked]> [mailto:[email-masked]] On 
>>>>     Behalf Of Justin Richer
>>>>     Cc: Shiu Fun Poon; [email-masked] <mailto:[email-masked]>
>>>>>     Jan 23, 2013 4:00、Justin Richer <[email-masked]> <mailto:[email-masked]> のメッセージ:
>>>>>
>>>>>>     [email-masked] <mailto:[email-masked]>
>>>>     [email-masked] <mailto:[email-masked]>

---

From: John Bradley <[email-masked]>
Date: Wed, 30 Jan 2013 12:55:51 -0300

My feeling was that letting the registration endpoint be a single URL (any url) and using query paramaters was easer for servers and clients.

Saying take the base URI for the registration endpoint and append these paths to it to do different operations seems more likely to go wrong fro developers.

Allowing both bath and query parameters is the worst option.

I am sympathetic with using POST and PUT and perhaps GET but I worry about OAuth developers not getting it.

I also don't get Tony's point about multi tenancy.  If each tenant can have there own registration endpoint I don't see a problem beyond finding the endpoint and that is what we have WF for.

John B.

On 2013-01-24, at 11:26 AM, Justin Richer <[email-masked]> wrote:

>> and reword the spec such that it will let those who implement do it with one endpoint or many, whatever is preferred
>> 
> 
> That's the whole point of this discussion -- I don't believe you can have it both ways.
> 
> In one way, you say there are three endpoints and, if you're keeping with the rest of OAuth, you don't give them official URL patterns that they must follow. How the client gets those endpoints is up to discovery or configuration, but the client has an internal map from each bit of functionality to a particular URL that's specific to the service, much in the same way that the client today has to map the authorization and token endpoints. In the other method, you've got one endpoint that the client sends a well-defined parameter to in order to accomplish the same goal.
> 
> So if you allow both at once, does a client send the "operation" parameter or not? Is it looking for one url or three to store in its configuration? I don't think this level of flexibility buys you anything useful, and I strongly believe that it will deeply hurt the functionality of dynamic registration if it's allowed.
> 
> As it stands today, you can still make the URL whatever you want. If we went with three endpoints you could also make those URLs whatever you wanted. Nobody has yet pointed out to me what the actual benefit is of making both valid.
> 
> I personally prefer the method of three endpoint URLs because it's cleaner and semantically equivalent, but I am hesitant to change that behavior unless there's strong working group support for it. I haven't seen real support for it yet -- it's not a good call to make it fully RESTful, and it's not a good call to leave it undefined. A client MUST have a very clear recipe of what to do on startup for this to work in the wild.
> 
> -- Justin
> 
>> 
>>> 
>>>

---

From: Justin Richer <[email-masked]>
Date: Wed, 30 Jan 2013 11:17:41 -0500

> Saying take the base URI for the registration endpoint and append these paths to it to do different operations seems more likely to go wrong fro developers.
Right, and to clarify, this isn't what I was saying. The spec wouldn't 
specify the path at all, just say that they're three different endpoint 
URLs. The same way that we specify that the auth endpoint and token 
endpoint are different URLs.

I think my example might have been misleading. The URLs could just as 
easily be:

client_register -> /register_a_new_client
rotate_secret -> /client/go_get_a_secret_or_something
client_update-> /maintenance/update_client_information

> I also don't get Tony's point about multi tenancy.  If each tenant can have there own registration endpoint I don't see a problem beyond finding the endpoint and that is what we have WF for.
Exactly. And to Bill's point in another thread, we could also register a 
link type for each endpoint to help facilitate discovery: 
http://tools.ietf.org/html/draft-wmills-oauth-lrdd-06

  -- Justin

---

From: Mike Jones <[email-masked]>
Date: Wed, 30 Jan 2013 16:42:34 +0000

I believe that what we have now - a single endpoint with an "operation" parameter, is more natural than having a different endpoint per operation.  In all likelihood, the implementation of all the operations (client_register, client_update, and rotate_secret) would end up going through the same code path anyway, using an operation parameter.  So let's just keep expressing it that way on the wire too.

Having to maintain and register many endpoints for one logical set of functionality would just make things harder in a practical sense.  Let's leave things the way they are.

				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Justin Richer
Sent: Wednesday, January 30, 2013 8:18 AM
To: John Bradley
Cc: [email-masked]
Subject: Re: [OAUTH-WG] Concerning OAuth introspection

> Saying take the base URI for the registration endpoint and append these paths to it to do different operations seems more likely to go wrong fro developers.
Right, and to clarify, this isn't what I was saying. The spec wouldn't specify the path at all, just say that they're three different endpoint URLs. The same way that we specify that the auth endpoint and token endpoint are different URLs.

I think my example might have been misleading. The URLs could just as easily be:

client_register -> /register_a_new_client rotate_secret -> /client/go_get_a_secret_or_something
client_update-> /maintenance/update_client_information

> I also don't get Tony's point about multi tenancy.  If each tenant can have there own registration endpoint I don't see a problem beyond finding the endpoint and that is what we have WF for.
Exactly. And to Bill's point in another thread, we could also register a link type for each endpoint to help facilitate discovery: 
http://tools.ietf.org/html/draft-wmills-oauth-lrdd-06

  -- Justin

>>>> case. Consider that clients still need to know how to manage all the parameters and responses.
>>>>
>>>> and we have to define at least one more with this extension, so I'm 
>>>> not convinced that having three with specific functions is really 
>>>> any different from having one with three functions from a 
>>>> development, deployment, and implementation perspective. I can tell 
>>>> you from experience that in our own server code, the difference is 
>>>> trivial. (And from OAuth1 experience, you can always have a query 
>>>> parameter as part of your endpoint URL if you need to. You might 
>>>> hate yourself for doing it that way, but nothing says your base URL 
>>>> can't already have parameters on it. A client just needs to know 
>>>> how to appropriately tack its parameters onto an existing URL, and 
>>>> any HTTP client worth its salt will know how to augment a query 
>>>> parameter set with new items.)
>>>>
>>>> Under the hood, these could (and in many cases will) be all served 
>>>> by the same chunks of code. The only difference is how this switch 
>>>> in functionality is presented.
>>>>
>>>>
>>>> to be

---

From: Sergey Beryozkin <[email-masked]>
Date: Wed, 30 Jan 2013 17:01:00 +0000

> Having to maintain and register many endpoints for one logical set of functionality would just make things harder in a practical sense.  Let's leave things the way they are.

For whatever it is worth: -1 to using operation parameters;

honestly I haven't thought, with my WS experience, that I will 
contribute to this discussion :-), but "/oauth?operation=register" or 
similar will just get REST gurus having a lot of criticism on it, it 
won't of course the implementers from supporting it but this will just 
distract many people from adopting OAuth2, this minor fact alone, when 
all start saying, look, in OAuth2 they use query parameters as actions...

Just my 2c, Sergey

>> On 2013-01-24, at 11:26 AM, Justin Richer<[email-masked]>  wrote:
>>

---

From: Anthony Nadalin <[email-masked]>
Date: Wed, 30 Jan 2013 21:38:11 +0000

I would not say that this is incompatible with OAUTH at all , as OAUTH has a physical and logical endpoints. We had to live through the Web Service endpoint nightmare were we had to have separate services, nuts

From: Justin Richer [mailto:[email-masked]]
Sent: Wednesday, January 30, 2013 7:20 AM
To: Shiu Fun Poon
Cc: Anthony Nadalin; Nat Sakimura; [email-masked]
Subject: Re: [OAUTH-WG] Concerning OAuth introspection

Hi.. Tony.. You are able to present this better than I do.
Justin,
Currently as it is, the spec is unflexible.   So when I send a request to an endpoint, the endpoint will need to have information like /revoke, /introspection, and others.  I can imagine the documented usage of this will a pages long just to describe all the endpoint that is needed to support an application.  (so far, /authz, /token, /introspection, /revoke, /.....), and this will be painful in the multi-tenant environment.

So why not allow the flexibility of using one endpoint /token (example only), and make the caller to tell you want the caller wants ?  It can be an optional field, and a hint to the authorization/token endpoint on what you want to do.
This is incompatible with OAuth as it stands today, which defines the auth endpoint and token endpoint as logically separate, and therefore there is not a parameter defined that would allow for such functionality switching.

That said, an *installation* could implement it this way if they wanted to, they'd just have to document the endpoints like this:

etc. The key difference here is that the "op=" parameter is *system specific* and is *not* part of the spec itself. And I think that's a good design to continue to follow.

Right now, the registration endpoint is the only one that defines an "operation" parameter, and I was positing the question of defining it in terms of three different endpoints instead. Most of the time, these endpoints will have different URLs, as outlined below, but specific instances could use some kind of "operation" parameter if they wanted to.

Defining it as one endpoint with a switch parameter actually decreses flexibility quite a lot, especially if you're talking about dispatching to different kinds of functionality all together, which is the use case you brought up. There are some places where that could make sense, and the definition of different endpoints allows you to do that in specific instances of a system without breaking the assumptions of clients.

What Tony was talking about was allowing something to be either three different URLs *or* using a spec-defined "operation" parameter. That suggestion is completely nuts, in my opinion.

And it does not violate the rest/json guideline.
Yes it absolutely does. The REST principle is that a URL represents one entity and the HTTP verbs represent different actions on that entity. Using a query parameter to switch is very much directly against REST guidelines. Not to say that OAuth is RESTful -- it's not, by a long shot. But it does follow many rest-like principles, the endpoint definitions being one of them.

Even with oauth specification, it provides a hint on what is to come, e.g. grant_type refresh_token, indicates you want to exchange a valid refresh_token to an access_token.  There is something in the payload which tell you what you need to do.  In this case, there is nothing in the payload which indicate what is expected.
These are functionality switches on the same kind of action, not dispatch to different actions. you still do authentication/authorization at the auth endpoint, you still get tokens from the token endpoint, etc.

If you standard that now (on the optional field), there is a chance that companies can implement this according to what will work best for them, and we actually have a chance to get this working between different products.
It's too late to standardize that field in the core, which is really where it would belong. But as it stands today, an OAuth client is going to need to be able to handle separate URLs for each defined endpoint already, so it can already handle the case where it happens to be the same base URL with different operations.

For what it's worth, what I was trying to get discussion on was whether it made sense to make Dynamic Registration look like the rest of OAuth with separate endpoints, or not.

 -- Justin

On Wed, Jan 23, 2013 at 1:05 PM, Justin Richer <[email-masked]<mailto:[email-masked]>> wrote:
I am very confused, and I need someone to explain to me what I am missing. Why won't it work to just pick one? What are people "already stuck with" that this would affect? It's not like we're trying to unseat a well-established protocol with a wide installation base here.

and:
/oauth/client_register
/oauth/client_update
/oauth/rotate_secret

help multitenancy? How does it even affect that use case? Consider that the base URL for all of these is completely up to the host environment (nothing is bound to the root URL). Consider that clients still have to know what the URL (or URLs) are, in either case. Consider that clients still need to know how to manage all the parameters and responses.

If anything, keeping it the way that it is with a single URL could be argued to help multitenancy because setting up routing to multiple URL endpoints can sometimes be problematic in hosted environments. However, OAuth already defines a bunch of endpoints, and we have to define at least one more with this extension, so I'm not convinced that having three with specific functions is really any different from having one with three functions from a development, deployment, and implementation perspective. I can tell you from experience that in our own server code, the difference is trivial. (And from OAuth1 experience, you can always have a query parameter as part of your endpoint URL if you need to. You might hate yourself for doing it that way, but nothing says your base URL can't already have parameters on it. A client just needs to know how to appropriately tack its parameters onto an existing URL, and any HTTP client worth its salt will know how to augment a query parameter set with new items.)

The *real* difference between the two approaches is a philosophical design one. The former overloads one URL with multiple functions switched by a flag, the latter uses the URL itself as an implicit flag. Under the hood, these could (and in many cases will) be all served by the same chunks of code. The only difference is how this switch in functionality is presented.

With that said, can somebody please explain to me how allowing *both* of these as options simultaneously (what I understand Tony to be suggesting) is a good idea, or how multitenancy even comes into play? Because I am completely not seeing how these are related.

Thanks,
 -- Justin

-----Original Message-----

To: Anthony Nadalin

Cc: Nat Sakimura; Shiu Fun Poon; [email-masked]<mailto:[email-masked]>

-- Justin

Registration has to work in a multi-tenant environment  so flexibility

is needed

-----Original Message-----

To: Anthony Nadalin

Cc: Nat Sakimura; Shiu Fun Poon; [email-masked]<mailto:[email-masked]>

-- Justin

-----Original Message-----

From: [email-masked]<mailto:[email-masked]> [mailto:[email-masked]] On

Behalf Of Justin Richer

To: Nat Sakimura

Cc: Shiu Fun Poon; [email-masked]<mailto:[email-masked]>

-- Justin

=nat via iPhone

Jan 23, 2013 4:00、Justin Richer <[email-masked]><mailto:[email-masked]> のメッセージ:

 -- Justin

Justin,

token                                             REQUIRED

resource_id                                    OPTIONAL

client_id                                         OPTIONAL

client_secret                                   OPTIONAL

Please consider.

ShiuFun

OAuth mailing list

[email-masked]<mailto:[email-masked]>

OAuth mailing list

[email-masked]<mailto:[email-masked]>

---

From: Mike Jones <[email-masked]>
Date: Wed, 30 Jan 2013 21:51:58 +0000

I’ll note that the OAuth token endpoint changes behaviors depending upon the grant_type and whether code or refresh_token parameters are present.  The first case is described at http://tools.ietf.org/html/rfc6749#section-4.1.3.  The second case is described at http://tools.ietf.org/html/rfc6749#section-6.

There are already a bunch of ways in which OAuth is not RESTful in a strict sense of the term.  It doesn’t seem to be a problem in practice.

                                                                -- Mike

From: [email-masked] [mailto:[email-masked]] On Behalf Of Anthony Nadalin
Sent: Wednesday, January 30, 2013 1:38 PM
To: Justin Richer; Shiu Fun Poon
Cc: [email-masked]
Subject: Re: [OAUTH-WG] Concerning OAuth introspection

From: Justin Richer [mailto:[email-masked]]
Sent: Wednesday, January 30, 2013 7:20 AM
To: Shiu Fun Poon
Cc: Anthony Nadalin; Nat Sakimura; [email-masked]<mailto:[email-masked]>
Subject: Re: [OAUTH-WG] Concerning OAuth introspection

 -- Justin

and:
/oauth/client_register
/oauth/client_update
/oauth/rotate_secret

Thanks,
 -- Justin

-----Original Message-----

To: Anthony Nadalin

-- Justin

is needed

-----Original Message-----

To: Anthony Nadalin

-- Justin

-----Original Message-----

Behalf Of Justin Richer

To: Nat Sakimura

-- Justin

=nat via iPhone

 -- Justin

Justin,

token                                             REQUIRED

resource_id                                    OPTIONAL

client_id                                         OPTIONAL

client_secret                                   OPTIONAL

Please consider.

ShiuFun

OAuth mailing list

OAuth mailing list

---

From: Justin Richer <[email-masked]>
Date: Wed, 30 Jan 2013 17:08:23 -0500

I completely agree that OAuth is not RESTful in any meaningful sense of
the term (and have stated so several times in this thread). I'm not at
all against using query parameters to change behaviors. That's why
they're there. But I'll point out that the examples that you give are
still *doing* the same thing qualitatively (returning a token, in this
instance), even though the mechanisms for doing so are a bit different.
They're still basically the same "action", and if there were a
protocol-wide "operation=" parameter as Shiu Fun Poon is suggesting,
they would all have the same value for it. The client registration
endpoint is different, because even though all the actions are *about*
client registration, they're different actions. This is the whole
purpose of the "operation=" parameter in the first place. That's the
reason that I brought up this idea of defining them as separate endpoints.

Regardless, the group seems about even split on one mode versus the
other. As such, I'm inclined to leave the "operation=" parameter in
place on the registration endpoint even though I don't prefer it.

I still am very strongly against the idea of defining a protocol-wide
"operation=" parameter for switching between all endpoints, even if it
were possible to do such a thing.

-- Justin

On 01/30/2013 04:51 PM, Mike Jones wrote:
>
> I’ll note that the OAuth token endpoint changes behaviors depending
> upon the grant_type and whether code or refresh_token parameters are
> present. The first case is described at
> http://tools.ietf.org/html/rfc6749#section-4.1.3
> <http://tools.ietf.org/html/rfc6749#section-4.1.3>. The second case is
> described at http://tools.ietf.org/html/rfc6749#section-6.
>
> There are already a bunch of ways in which OAuth is not RESTful in a
> strict sense of the term. It doesn’t seem to be a problem in practice.
>
> -- Mike
>
> *From:[email-masked] [mailto:[email-masked]] *On
> Behalf Of *Anthony Nadalin
> *Sent:* Wednesday, January 30, 2013 1:38 PM
> *To:* Justin Richer; Shiu Fun Poon
> *Cc:* [email-masked]
> *Subject:* Re: [OAUTH-WG] Concerning OAuth introspection
>
> I would not say that this is incompatible with OAUTH at all , as OAUTH
> has a physical and logical endpoints. We had to live through the Web
> Service endpoint nightmare were we had to have separate services, nuts
>
> *From:*Justin Richer [mailto:[email-masked]]
> *Sent:* Wednesday, January 30, 2013 7:20 AM
> *To:* Shiu Fun Poon
> *Cc:* Anthony Nadalin; Nat Sakimura; [email-masked]
> <mailto:[email-masked]>
> *Subject:* Re: [OAUTH-WG] Concerning OAuth introspection
>
>     Currently as it is, the spec is unflexible. So when I send a
>     request to an endpoint, the endpoint will need to have information
>     like /revoke, /introspection, and others. I can imagine the
>     documented usage of this will a pages long just to describe all
>     the endpoint that is needed to support an application. (so far,
>     /authz, /token, /introspection, /revoke, /.....), and this will be
>     painful in the multi-tenant environment.
>
>     So why not allow the flexibility of using one endpoint /token
>     (example only), and make the caller to tell you want the caller
>     wants ? It can be an optional field, and a hint to the
>     authorization/token endpoint on what you want to do.
>
> there is not a parameter defined that would allow for such
> functionality switching.
>
> That said, an *installation* could implement it this way if they
> wanted to, they'd just have to document the endpoints like this:
>
> "operation" parameter, and I was positing the question of defining it
> in terms of three different endpoints instead. Most of the time, these
> flexibility quite a lot, especially if you're talking about
> dispatching to different kinds of functionality all together, which is
> the use case you brought up. There are some places where that could
> make sense, and the definition of different endpoints allows you to do
> that in specific instances of a system without breaking the
> assumptions of clients.
>
> Yes it absolutely does. The REST principle is that a URL represents
> one entity and the HTTP verbs represent different actions on that
> entity. Using a query parameter to switch is very much directly
> against REST guidelines. Not to say that OAuth is RESTful -- it's not,
> by a long shot. But it does follow many rest-like principles, the
> endpoint definitions being one of them.
>
>
>     Even with oauth specification, it provides a hint on what is to
>     come, e.g. grant_type refresh_token, indicates you want to
>     exchange a valid refresh_token to an access_token. There is
>     something in the payload which tell you what you need to do. In
>     this case, there is nothing in the payload which indicate what is
>     expected.
>
> dispatch to different actions. you still do
> authentication/authorization at the auth endpoint, you still get
> tokens from the token endpoint, etc.
>
>     If you standard that now (on the optional field), there is a
>     chance that companies can implement this according to what will
>     work best for them, and we actually have a chance to get this
>     working between different products.
>
> where it would belong. But as it stands today, an OAuth client is
> going to need to be able to handle separate URLs for each defined
> endpoint already, so it can already handle the case where it happens
> to be the same base URL with different operations.
>
> For what it's worth, what I was trying to get discussion on was
> whether it made sense to make Dynamic Registration look like the rest
> of OAuth with separate endpoints, or not.
>
> -- Justin
>
>
>         I am very confused, and I need someone to explain to me what I
>         am missing. Why won't it work to just pick one? What are
>         people "already stuck with" that this would affect? It's not
>         like we're trying to unseat a well-established protocol with a
>         wide installation base here.
>
>         help multitenancy? How does it even affect that use case?
>         Consider that the base URL for all of these is completely up
>         to the host environment (nothing is bound to the root URL).
>         Consider that clients still have to know what the URL (or
>         URLs) are, in either case. Consider that clients still need to
>         know how to manage all the parameters and responses.
>
>         If anything, keeping it the way that it is with a single URL
>         could be argued to help multitenancy because setting up
>         routing to multiple URL endpoints can sometimes be problematic
>         in hosted environments. However, OAuth already defines a bunch
>         of endpoints, and we have to define at least one more with
>         this extension, so I'm not convinced that having three with
>         specific functions is really any different from having one
>         with three functions from a development, deployment, and
>         implementation perspective. I can tell you from experience
>         that in our own server code, the difference is trivial. (And
>         from OAuth1 experience, you can always have a query parameter
>         as part of your endpoint URL if you need to. You might hate
>         yourself for doing it that way, but nothing says your base URL
>         can't already have parameters on it. A client just needs to
>         know how to appropriately tack its parameters onto an existing
>         URL, and any HTTP client worth its salt will know how to
>         augment a query parameter set with new items.)
>
>         itself as an implicit flag. Under the hood, these could (and
>         in many cases will) be all served by the same chunks of code.
>         The only difference is how this switch in functionality is
>         presented.
>
>
>         *both* of these as options simultaneously (what I understand
>         Tony to be suggesting) is a good idea, or how multitenancy
>         even comes into play? Because I am completely not seeing how
>         these are related.
>
>         Thanks,
>         -- Justin
>
>
>

---

From: Sergey Beryozkin <[email-masked]>
Date: Wed, 30 Jan 2013 22:24:06 +0000

On 30/01/13 22:08, Justin Richer wrote:
> the term (and have stated so several times in this thread).

That is fine, this is not the issue, OAuth2 itself does not have to be 
'pure' but having individual bits from which the whole ecosystem is 
build upon offering a RESTful interface when possible is very important 
IMHO and in this case it is possible.

What if the introspection endpoint would also offer an ability to search 
? Some query parameters will mean 'action', some - something else, not 
cool really

Anyway, too much noise I guess from someone who is not even a member of 
the working group, sorry :-)

Thanks, Sergey

> I'm not at
>> http://tools.ietf.org/html/rfc6749#section-4.1.3. The second case is
>>             Cc: Nat Sakimura; Shiu Fun Poon;[email-masked]  <mailto:[email-masked]>
>>
>>                 Cc: Nat Sakimura; Shiu Fun Poon;[email-masked]  <mailto:[email-masked]>
>>
>>                     From:[email-masked]  <mailto:[email-masked]>  [mailto:[email-masked]] On
>>
>>                     Behalf Of Justin Richer
>>
>>                     Cc: Shiu Fun Poon;[email-masked]  <mailto:[email-masked]>
>>
>>                         Jan 23, 2013 4:00、Justin Richer<[email-masked]>  <mailto:[email-masked]>  のメッセージ:
>>
>>
>>

---

From: Justin Richer <[email-masked]>
Date: Wed, 30 Jan 2013 17:27:24 -0500

On 01/30/2013 05:24 PM, Sergey Beryozkin wrote:
> build upon offering a RESTful interface when possible is very 
> important IMHO and in this case it is possible.
>
> What if the introspection endpoint would also offer an ability to 
> search ? Some query parameters will mean 'action', some - something 
> else, not cool really

If a service were to offer other functionalities from the same URL as 
the token endpoint, and those other functionalities were switched by 
some kind of parameter, then this is well outside the definition of the 
introspection endpoint.

>
> Anyway, too much noise I guess from someone who is not even a member 
> of the working group, sorry :-)

In the IETF, if you post to the list, you're in the working group. 
Welcome. :)

  -- Justin

>>>             It will not work the way you have it, as people do 
>>> multi-tendency different and they are already stuck with the method 
>>> that they have chosen, so they need the flexability, to restrict 
>>> this is nuts as people won't use it.
>>>
>>>
>>>
>>>             I completely disagree with this assessment. 
>>> Multi-tenancy will work just fine (or even better) if everyone uses 
>>> the same pattern. Telling someone "it might be three different urls 
>>> or it might be all one url with a parameter" is just asking for a 
>>> complete disaster. What does the flexibility of allowing two 
>>> approaches actually accomplish?
>>>
>>>
>>>
>>>             You can argue about the merits of either approach, but 
>>> having both as unspecified options for registration, which is meant 
>>> to help things get going in a cold-boot environment, is just plain 
>>> nuts.
>>>
>>>
>>>
>>>
>>>
>>>             -- Justin
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>                 In my opinion, this is a key place where this kind 
>>> of flexibility is a very bad thing. Registration needs to work one 
>>> fairly predictable way.
>>>
>>>
>>>
>>>                 -- Justin
>>>
>>>
>>>
>>>                     From:[email-masked] 
>>> <mailto:[email-masked]> [mailto:[email-masked]] On
>>>
>>>                     Behalf Of Justin Richer
>>>
>>>                     Which brings up an interesting question for the 
>>> Registration doc: right now, it's set up as a single endpoint with 
>>> three operations. We could instead define three endpoints for the 
>>> different operations.
>>>
>>>
>>>
>>>                     I've not been keen to make that deep of a 
>>> cutting change to it, but it would certainly be cleaner and more 
>>> RESTful API design. What do others think?
>>>
>>>
>>>
>>>                     -- Justin
>>>
>>>
>>>
>>>
>>>
>>>                         Jan 23, 2013 4:00、Justin 
>>> Richer<[email-masked]> <mailto:[email-masked]>  のメッセージ:
>>>
>>>
>>>
>>>                             I'm not sure what the "action/operation" 
>>> flag would accomplish. The idea behind having different endpoints in 
>>> OAuth is that they each do different kinds of things. The only 
>>> "action/operation" that I had envisioned for the introspection 
>>> endpoint is introspection itself: "I have a token, what does it mean?"
>>>
>>>
>>>
>>>                             Note that client_id and client_secret 
>>> *can* already be used at this endpoint if the server supports that 
>>> as part of their client credentials setup. The examples use HTTP 
>>> Basic with client id and secret right now. Basically, the client can 
>>> OAuth2 allows on the token endpoint. It could also authenticate with 
>>> an access token. At least, that's the intent of the introspection 
>>> draft -- if that's unclear, I'd be happy to accept suggested changes 
>>> to clarify this text.
>>>
>>>
>>>
>>>                               -- Justin
>>>
>>>
>>>
>>>                                 operation (wording to be 
>>> determine)    OPTIONAL inquire (default) | revoke ...
>>>
>>> resource_id OPTIONAL
>>>
>>> client_id OPTIONAL
>>>
>>> client_secret OPTIONAL
>>>
>>>
>>>
>>>                                 And for the OAuth client 
>>> information, it should be an optional parameter (in case it is a 
>>> public client or client is authenticated with SSL mutual 
>>> authentication).
>>>
>>>
>>>
>>>                                 Please consider.
>>>
>>>
>>>
>>>                                 ShiuFun
>>>

---

From: Sergey Beryozkin <[email-masked]>
Date: Wed, 30 Jan 2013 22:30:59 +0000

> In the IETF, if you post to the list, you're in the working group.

Nice :-), thanks

Cheers, Sergey

>>>> In my opinion, this is a key place where this kind of flexibility is
>>>> a very bad thing. Registration needs to work one fairly predictable
>>>> way.
>>>>
>>>>
>>>>
>>>> -- Justin
>>>>
>>>>
>>>>
>>>> I've not been keen to make that deep of a cutting change to it, but
>>>> it would certainly be cleaner and more RESTful API design. What do
>>>> others think?
>>>>
>>>>
>>>>
>>>> -- Justin
>>>>
>>>>
>>>>
>>>>
>>>>
>>>> envisioned for the introspection endpoint is introspection itself:
>>>> "I have a token, what does it mean?"
>>>>
>>>>
>>>>
>>>> endpoint if the server supports that as part of their client
>>>> secret right now. Basically, the client can authenticate however it
>>>> wants, including any of the methods that OAuth2 allows on the token
>>>> endpoint. It could also authenticate with an access token. At least,
>>>> that's the intent of the introspection draft -- if that's unclear,
>>>> I'd be happy to accept suggested changes to clarify this text.
>>>>
>>>>
>>>>
>>>> -- Justin
>>>>
>>>>
>>>>

---

From: John Bradley <[email-masked]>
Date: Wed, 30 Jan 2013 20:24:22 -0300

That is better, but I don't see an advantage to that over using a query parameter.

They are equally restful or not as the case may be.

To be more restful I think you want a single endpoint using HTTP verbs.

POST /reg_endpoint?paramaters …  -> register
PUT  /reg_endpoint?client_id=12345&paramaters -> update
PUT /reg_endpoint?client_id=12345&rotate_secret=true

The downside is developers understanding 

On 2013-01-30, at 1:17 PM, Justin Richer <[email-masked]> wrote:

> Exactly. And to Bill's point in another thread, we could also register a link type for each endpoint to help facilitate discovery: http://tools.ietf.org/html/draft-wmills-oauth-lrdd-06
> 
> -- Justin
> 
>> 
>> John B.
>>

---

From: Phil Hunt <[email-masked]>
Date: Wed, 30 Jan 2013 16:11:07 -0800

I disagree at this point that making changes to make oauth more restful is a good thing.  Doing so either means breaking changes or adding options that mean unnecessary complication.

When oauth started rest was not the mandate. The current standard supports all kinds of http services and that marks success. 

If it ain't broke don't fix it.  

Phil

Sent from my phone.