Re: [OAUTH-WG] Registration: Scope Values

On Thu, Apr 18, 2013 at 11:15 AM, Justin Richer <jricher@mitre.org> wrote:

> clientProperties = oauth2.register("http://server/register"<http://server/register>,
> "My Client", "a b c d", ["http://client/return" <http://client/return>]);
>
> The server registers you, and clientProperties gets a client_id, a
> client_name of "My Client", and a scope field of "a b d" since the server
> said you couldn't dynamically register for "c" for whatever reason.
>
> Now let's say that you use the library to request authorization to do
> something on the API. Your app can look inside of clientProperties.scope to
> see what scopes you can do something with.
>

So, your implication is that when the server says “a b d” that means that
you’d better not ask for any other scopes.  I agree.  This seems like the
only useful interpretation. So why shouldn’t we say that in the spec?  -T

> This will have the string "a b", which means something (to the app) in the
> context of the API it's registering for, and it knows it wants a token for
> "a b". Apps are going to need to know that, but the library will do what
> the app tells it to. So the app calls the library:
>
> oauth2.authorize("http://server/authorize" <http://server/authorize>,
> "code", "a b", "http://client/return" <http://client/return>, "STATEVALUE@
> #$I(RJ@#")
>
> A dumb app could even pass in whatever the value of clientProperties.scope
> is (or a blank value) to try to get all of its scopes. Or the app could
> know that the scopes are structured and call:
>
> oauth2.authorize("http://server/authorize" <http://server/authorize>,
> "code", "a:read b:readwrite", "http://client/return"<http://client/return>,
> "STATEVALUE@#$I(RJ@#")
>
> Eventually you get back a code, then a token:
>
> token = oauth2.token("http://server/token" <http://server/token>, code,
> clientProperties)
>
> (note that clientProperties will have the client_id, client_secret,
> redirect_uri, and anything else needed here.)
>
> Now, this token will *also* have a "scope" field. Let's say that the user
> only authorized you for scope "a". If you want to be smart about it, you
> can avoid calling endpoints that require "b". Or you could just try it and
> be prepared to deal with a failing token, like all OAuth clients must be
> able to do anyway.
>
> I hope this makes sense, please forgive the off-the-cuff pseudocode.
>
>  -- Justin
>
>
> On 04/18/2013 01:56 PM, Tim Bray wrote:
>
> On Thu, Apr 18, 2013 at 10:47 AM, Justin Richer <jricher@mitre.org> wrote:
>
>
>>  It's very useful for a generic *library* that handles the authorization
>> layer for an application to have a slot for registering scopes and finding
>> out what scopes the app's been registered for.
>>
>
>  I don’t see how it’s useful in the slightest if there’s no defined
> semantic for what “registration” actually means, i.e. what result is to be
> expected when sending or receiving a list of scopes.   -T
>
>
>>
>>
>>
>> On 04/18/2013 01:04 PM, Mike Jones wrote:
>>
>>  Saying anything normative about “enforcing restrictions” is going
>> beyond RFC 6749 semantics.  Indeed, you’d said that “I agree that we
>> shouldn't try to "solve" scope in registration.”, but talking about
>> restrictions is going down the slippery “solving it” path.
>>
>>
>>
>> At most we can say that the two parties are making declarations to one
>> another about scopes that they may choose to use, but we can’t assume that
>> this is an exclusive list and that other scope values such as “
>> urn:example:channel=HBO&urn:example:rating=G,PG-13” might not be used,
>> even if the client registers saying that it intends to use the “OATC” scope
>> value.  We could maybe even say that some services may use a static set of
>> scopes and might choose to limit the scopes that a client may use to those
>> that it declared to the server or to those that the server returned to the
>> client.  That’s a HINT that some services might do this.  But we can’t say
>> anything normative about such possible behaviors, because it goes beyond
>> RFC 6749.
>>
>>
>>
>>                                                             -- Mike
>>
>>
>>
>> *From:* Richer, Justin P. [mailto:jricher@mitre.org <jricher@mitre.org>]
>> *Sent:* Thursday, April 18, 2013 9:26 AM
>> *To:* Anthony Nadalin
>> *Cc:* Tim Bray; Mike Jones; oauth@ietf.org
>> *Subject:* Re: [OAUTH-WG] Registration: Scope Values
>>
>>
>>
>> This doesn't actually break the semantics because the client MUST accept
>> what the server tells it over anything that it asks for in the first place.
>> The server has the final say. So in this case, if your client asks for
>> nothing, the server says "A B C", the client now knows it can ask for "A B
>> C" scopes.
>>
>>
>>
>> I'm still in favor of not putting the restricting language in the scope
>> definition at all, instead have it say something like:
>>
>>
>>
>>  “Space-separated list of scope values (as described in OAuth 2.0 Section 3.3
>> [RFC6749] <http://tools.ietf.org/html/rfc6749#section-3.3>) that the
>> Client can use when requesting access tokens from the Authorization Server.
>> As scope values are service specific, the means of the Authorization Server
>> enforcing this restriction are outside the scope of this specification.”
>>
>>
>>
>> Couple this with the overall paragraph that says that the client is
>> requesting values that the server is potentially overriding with its
>> declarations, and I think that addresses everything without getting into
>> confusing language that doesn't add to interoperability.
>>
>>
>>
>>  -- Justin
>>
>>
>>
>> On Apr 18, 2013, at 12:13 PM, Anthony Nadalin <tonynad@microsoft.com>
>> wrote:
>>
>>
>>
>>   If I don’t specify a scope, then the server can allocate a default (or
>> default set), thus that breaks the semantics you describe
>>
>>
>>
>> *From:* oauth-bounces@ietf.org [mailto:oauth <oauth>-bounces@ietf.org] *On
>> Behalf Of *Tim Bray
>> *Sent:* Thursday, April 18, 2013 9:04 AM
>> *To:* Mike Jones
>> *Cc:* oauth@ietf.org
>> *Subject:* Re: [OAUTH-WG] Registration: Scope Values
>>
>>
>>
>> I’m unconvinced, Mike.  Obviously you’re right about the looseness of
>> OAuth2 scope specification, but this is a very specific semantic of what
>> happens when you register, and I don’t think we’re bound by history here.
>> If we can’t safely say anything about what the list of scopes means, then
>> I'm with you let's take them out.  But the most obvious intended semantic
>> is (from the client) “I promise to ask only for these” and from the server
>> “These are the only ones I’ll give you tokens for.”  Or does someone have
>> use-cases for an alternative semantic?
>>
>>
>>
>> To make this concrete, I propose the following:
>>
>> “Space-separated list of scope values (as described in OAuth 2.0 Section 3.3
>> [RFC6749] <http://tools.ietf.org/html/rfc6749#section-3.3>) that the
>> client is declaring to the server that it will restrict itself to when
>> requesting access tokens, and that the server is declaring to the client
>> that it is registered to use when requesting access tokens.  Clients
>> SHOULD assume that servers will refuse to grant access tokens for scopes
>> not in the list provided by the server.”
>>
>>
>>
>>
>>
>> On Thu, Apr 18, 2013 at 8:55 AM, Mike Jones <Michael.Jones@microsoft.com>
>> wrote:
>>
>>  I don’t think it’s possible to define what it means in an interoperable
>> way because OAuth didn’t specify scopes in an interoperable way.  No, I
>> don’t like that either, but I think that’s where things are.  That’s why I
>> was advocating deleting this registration feature entirely.
>>
>>
>>
>> But understanding it might be useful in some contexts, I’m OK keeping it,
>> provided we be clear that the semantics of “registered to use” are
>> service-specific.
>>
>>
>>
>>                                                             -- Mike
>>
>>
>>
>> *From:* Tim Bray [mailto:twbray@google.com]
>> *Sent:* Thursday, April 18, 2013 8:36 AM
>> *To:* Mike Jones
>> *Cc:* Justin Richer; oauth@ietf.org
>>
>>
>> *Subject:* Re: [OAUTH-WG] Registration: Scope Values
>>
>>
>>
>> On the server-to-client side, what does “registered to use” mean?  Does
>> it mean that the client should assume that any scopes not on the list WILL
>> not be granted, MAY not be granted.... or what?  Is this already covered
>> elsewhere? -T
>>
>>
>>
>> On Thu, Apr 18, 2013 at 8:28 AM, Mike Jones <Michael.Jones@microsoft.com>
>> wrote:
>>
>> Thanks, Justin.  I agree with the need for the generic two-sided
>> language.  I’d still keep this language for scope, because we want to
>> capture the “declaring” aspect in this case:
>>
>>
>>
>> “Space separated list of scope values (as described in OAuth 2.0 Section 3.3
>> [RFC6749] <http://tools.ietf.org/html/rfc6749#section-3.3>) that the
>> client is declaring to the server that it may use when requesting access
>> tokens and that the server is declaring to the client that it is registered
>> to use when requesting access tokens.”.
>>
>>
>>
>> You should probably also reinforce that scope values are service-specific
>> and may not consist only of a static set of string values, and that
>> therefore, in some cases, an exhaustive list of registered scope values is
>> not possible.
>>
>>
>>
>>                                                             -- Mike
>>
>>
>>
>> *From:* Justin Richer [mailto:jricher@mitre.org]
>> *Sent:* Monday, April 15, 2013 12:29 PM
>>
>>
>> *To:* Mike Jones
>> *Cc:* Tim Bray; oauth@ietf.org
>> *Subject:* Re: [OAUTH-WG] Registration: Scope Values
>>
>>
>>
>> I think that because the "declaration" issue affects all parameters in
>> the list, not just scope, we should adopt this in a higher level paragraph
>> and leave it out of the individual parameter descriptions. Thus, something
>> like this inserted as the second paragraph in section 2:
>>
>> The client metadata values serve two parallel purposes in the overall
>> OAuth Dynamic Registration protocol:
>>
>>  - the Client requesting its desired values for each parameter to the
>> Authorization Server in a [register] or [update] request,
>>  - the Authorization Server informing the Client of the current values of
>> each parameter that the Client has been registered to use through a [client
>> information response].
>>
>> An Authorization Server MAY override any value that a Client requests
>> during the registration process (including any omitted values) and replace
>> the requested value with a default. The normative indications in the
>> following list apply to the Client's declaration of its desired values.
>>
>> The Authorization Server SHOULD provide documentation for any fields that
>> it requires to be filled in by the client or to have particular values or
>> formats. Extensions and profiles...
>>
>>
>> And then remove the sidedness-language from the scope parameter and any
>> other parameters where it might have crept in inadvertently.
>>
>>  -- Justin
>>
>> On 04/15/2013 01:29 PM, Mike Jones wrote:
>>
>>  We could fix the one-sided language by changing
>>
>> “Space separated list of scope values (as described in OAuth 2.0 Section 3.3
>> [RFC6749] <http://tools.ietf.org/html/rfc6749#section-3.3>) that the
>> client is declaring that it may use when requesting access tokens.”
>>
>> to
>>
>> “Space separated list of scope values (as described in OAuth 2.0 Section 3.3
>> [RFC6749] <http://tools.ietf.org/html/rfc6749#section-3.3>) that the
>> client is declaring to the server that it may use when requesting access
>> tokens and that the server is declaring to the client that it is registered
>> to use when requesting access tokens.”.
>>
>>
>>
>> Again, I chose the “registered to use” language carefully – because in
>> the general case it’s not a restriction on the values that the client can
>> use – just a statement by the server to the client that it is registered to
>> use those particular values.  In both cases, the parties are making
>> declarations to one another.
>>
>>
>>
>> If you adopt that language (or keep the original language), then yes, I’d
>> consider this closed.
>>
>>
>>
>>                                                             -- Mike
>>
>>
>>
>> *From:* Justin Richer [mailto:jricher@mitre.org <jricher@mitre.org>]
>> *Sent:* Monday, April 15, 2013 9:57 AM
>> *To:* Mike Jones
>> *Cc:* Tim Bray; oauth@ietf.org
>> *Subject:* Re: [OAUTH-WG] Registration: Scope Values
>>
>>
>>
>> I absolutely do not want to delete this feature, as (having implemented
>> it) I think it's very useful. This is a very established pattern in manual
>> registration: I know of many, many OAuth2 servers and clients that are set
>> up where the client must pre-register a set of scopes.
>>
>> I don't like the language of "the client is declaring" because it's too
>> one-sided. The client might not have declared anything, and it might be the
>> server that's declaring something to the client. Deleting the "is
>> declaring" bit removes that unintended restriction of the language while
>> keeping the original meaning intact. I actually thought that I had fixed
>> that before the last draft went in but apparently I missed this one.
>>
>> I will work on clarifying the intent of the whole metadata set in its
>> introductory paragraph(s) so that it's clear that all of these fields are
>> used in both of these situations:
>>
>>  1) The client declaring to the server its desire to use a particular
>> value
>>  2) The server declaring to the client that it has been registered with a
>> particular value
>>
>> This should hopefully clear up the issue in the editor's note that I
>> currently have at the top of that section right now, too.
>>
>> Mike, since you were the one who originally brought up the issue, and
>> you're fine with the existing text, can I take this as closed now? Assuming
>> that you agree with deleting "is declaring" for reasons stated above, I'm
>> fine with leaving everything else as is and staying quiet on what the
>> server has to do with the scopes.
>>
>>  -- Justin
>>
>> On 04/15/2013 12:44 PM, Mike Jones wrote:
>>
>>  I think that the existing wording is superior to the proposed changed
>> wording.  The existing wording is:
>>
>>
>>
>>    scope
>>
>>       OPTIONAL.  Space separated list of scope values (as described in
>>
>>       OAuth 2.0 Section 3.3 [RFC6749]<http://tools.ietf.org/html/rfc6749#section-3.3>)
>> that the client is declaring that
>>
>>       it may use when requesting access tokens.  If omitted, an
>>
>>       Authorization Server MAY register a Client with a default set of
>>
>>       scopes.
>>
>>
>>
>> For instance, the current “client is declaring” wording will always be
>> correct, whereas as the change to “client can use” wording implies a
>> restriction on client behavior that is not always applicable.  The “client
>> is declaring” wording was specific and purposefully chosen, and I think
>> should be retained.  In particular, we can’t do anything that implies that
>> only the registered scopes values can be used.  At the OAuth spec level,
>> this is a hint as to possible future client behavior – not a restriction on
>> future client behavior.
>>
>>
>>
>> Also, for the reasons that Tim stated, I’m strongly against any
>> “matching” or “regex” language in the spec pertaining to scopes – as it’s
>> not actionable.
>>
>>
>>
>> So I’d propose that we leave the existing scope wording in place.
>> Alternatively, I’d also be fine with deleting this feature entirely, as I
>> don’t think it’s useful in the general case.
>>
>>
>>
>>                                                             -- Mike
>>
>>
>>
>> *From:* oauth-bounces@ietf.org [mailto:oauth-bounces@ietf.org<oauth-bounces@ietf.org>
>> ]*On Behalf Of *Justin Richer
>> *Sent:* Monday, April 15, 2013 8:05 AM
>> *To:* Tim Bray; oauth@ietf.org
>> *Subject:* Re: [OAUTH-WG] Registration: Scope Values
>>
>>
>>
>> On 04/15/2013 10:52 AM, Tim Bray wrote:
>>
>>
>>   I’d use the existing wording; it’s perfectly clear.  Failing that, if
>> there’s strong demand for registration of structured scopes, bless the use
>> of regexes, either PCREs or some careful subset.
>>
>>
>> Thanks for the feedback -- Of these two choices, I'd rather leave it
>> as-is.
>>
>>
>>
>>
>>
>> However, I’d subtract the sentence “If omitted, an Authorization Server
>> MAY register a Client with a default set of  scopes.”  It adds no value; if
>> the client doesn’t declare scopes, the client doesn’t declare scopes,
>> that’s all.  -T
>>
>>
>> Remember, all of these fields aren't just for the client *request*,
>> they're also for the server's *response* to either a POST, PUT, or GET
>> request. (I didn't realize it, but perhaps the wording as stated right now
>> doesn't make that clear -- I need to fix that.) The value that it adds is
>> if the client doesn't ask for any particular scopes, the server can still
>> assign it scopes and the client can do something smart with that. Dumb
>> clients are allowed to ignore it if it doesn't mean anything to them.
>>
>> This is how our server implementation actually works right now. If the
>> client doesn't ask for anything specific at registration, the server hands
>> it a bag of "default" scopes. Same thing happens at auth time -- if the
>> client doesn't ask for any particular scopes, the server hands it all of
>> its registered scopes as a default. Granted, on our server, scopes are just
>> simple strings right now, so they get compared at the auth endpoint with an
>> exact string-match metric and set-based logic.
>>
>>  -- Justin
>>
>>
>>
>>
>>
>> On Mon, Apr 15, 2013 at 7:35 AM, Justin Richer <jricher@mitre.org> wrote:
>>
>> What would you suggest for wording here, then? Keeping in mind that we
>> cannot (and don't want to) prohibit expression-based scopes.
>>
>>  -- Justin
>>
>>
>>
>> On 04/15/2013 10:33 AM, Tim Bray wrote:
>>
>>  No, I mean it’s not interoperable at the software-developer level.  I
>> can’t register scopes at authorization time with any predictable effect
>> that I can write code to support, either client or server side, without
>> out-of-line non-interoperable knowledge about the behavior of the server.
>>
>>
>>
>> I guess I’m just not used to OAuth’s culture of having no expectation
>> that things will be specified tightly enough that I can write code to
>> implement as specified.  -T
>>
>>
>>
>> On Mon, Apr 15, 2013 at 7:15 AM, Justin Richer <jricher@mitre.org> wrote:
>>
>> Scopes aren't meant to be interoperable between services since they're
>> necessarily API-specific. The only interoperable bit is that there's *some*
>> place to put the values and that it's expressed as a bag of space-separated
>> strings. How those strings get interpreted and enforced (which is really
>> what's at stake here) is up to the AS and PR (or a higher-level protocol
>> like UMA).
>>
>>  -- Justin
>>
>>
>>
>> On 04/15/2013 10:13 AM, Tim Bray wrote:
>>
>> This, as written, has zero interoperability.  I think this feature can
>> really only be made useful in the case where scopes are fixed strings.
>>
>> -T
>>
>> On Apr 15, 2013 6:54 AM, "Justin Richer" <jricher@mitre.org> wrote:
>>
>> You are correct that the idea behind the "scope" parameter at
>> registration is a constraint on authorization-time scopes that are made
>> available. It's both a means for the client to request a set of valid
>> scopes and for the server to provision (and echo back to the client) a set
>> of valid scopes.
>>
>> I *really* don't want to try to define a matching language for scope
>> expressions. For that to work, all servers would need to be able to process
>> the regular expressions for all clients, even if the servers themselves
>> only support simple-string scope values. Any regular expression syntax we
>> pick here is guaranteed to be incompatible with something, and I think the
>> complexity doesn't buy much. Also, I think you suddenly have a potential
>> security issue if you have a bad regex in place on either end.
>>
>> As it stands today, the server can interpret the incoming registration
>> scopes and enforce them however it wants to. The real trick comes not from
>> assigning the values to a particular client but to enforcing them, and I
>> think that's always going to be service-specific. We're just not as clear
>> on that as we could be.
>>
>> After looking over everyone's comments so far, I'd like to propose the
>> following text for that section:
>>
>>
>>     scope
>>
>>       OPTIONAL.  Space separated list of scope values (as described in
>>
>>       OAuth 2.0 Section 3.3 [RFC6749] <http://tools.ietf.org/html/rfc6749#section-3.3>) that the client can use when
>>
>>       requesting access tokens.  As scope values are service-specific,
>>
>>       the Authorization Server MAY define its own matching rules when
>>
>>       determining if a scope value used during an authorization request
>>
>>       is valid according to the scope values assigned during
>>
>>       registration. Possible matching rules include wildcard patterns,
>>
>>       regular expressions, or exactly matching the string. If omitted,
>>
>>       an Authorization Server MAY register a Client with a default
>>
>>       set of scopes.
>>
>>
>> Comments? Improvements?
>>
>>  -- Justin
>>
>>
>>   On 04/14/2013 08:23 PM, Manger, James H wrote:
>>
>> Presumably at app registration time any scope specification is really a constraint on the scope values that can be requested in an authorization flow.
>>
>>
>>
>> So ideally registration should accept rules for matching scopes, as opposed to actual scope values.
>>
>>
>>
>> You can try to use scope values as their own matching rules. That is fine for a small set of "static" scopes. It starts to fail when there are a large number of scopes, or scopes that can include parameters (resource paths? email addresses?). You can try to patch those failures by allowing services to define service-specific special "wildcard" scope values that can only be used during registration (eg "read:*").
>>
>>
>>
>> Alternatively, replace 'scope' in registration with 'scope_regex' that holds a regular expression that all scope values in an authorization flow must match.
>>
>>
>>
>> --
>>
>> James Manger
>>
>> _______________________________________________
>>
>> OAuth mailing list
>>
>> OAuth@ietf.org
>>
>> https://www.ietf.org/mailman/listinfo/oauth
>>
>>
>>
>>
>> _______________________________________________
>> OAuth mailing list
>> OAuth@ietf.org
>> https://www.ietf.org/mailman/listinfo/oauth
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>> _______________________________________________
>> OAuth mailing list
>> OAuth@ietf.org
>> https://www.ietf.org/mailman/listinfo/oauth
>>
>>
>>
>>
>>
>
>