Subject: [OAUTH-WG] Simpilfying use of assertions when requesting an access token

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 2 Sep 2010 14:11:22 -0700

I would like to make this change in -11:

Instead of the current user of the 'assertion' grant type -

  POST /token HTTP/1.1
  Host: server.example.com
  Content-Type: application/x-www-form-urlencoded

  grant_type=assertion&
  assertion_type=urn%3Aoasis%3Anames%3Atc%3ASAML%3A2.0%3Aassertion&
  assertion=PHNhbWxwOl[...omitted for brevity...]ZT4%3D

Drop the 'assertion' grant type and put the assertion type directly in the grant_type parameter:

  POST /token HTTP/1.1
  Host: server.example.com
  Content-Type: application/x-www-form-urlencoded

  grant_type=urn%3Aoasis%3Anames%3Atc%3ASAML%3A2.0%3Aassertion&
  assertion=PHNhbWxwOl[...omitted for brevity...]ZT4%3D

In other words, the grant_type parameter value will be defined as:

-          authorization_code

-          password

-          client_credentials

-          refresh_token

-          an abolute URI (extensions)

I considered turning all the values into URIs but found it to be counter-intuitive. The practice of using "official" short names and extension URIs is well established and is already the general architecture used here. This just makes it cleaner.

I ran this idea by Brian Campbell and Chuck Mortimore who are generally supportive of the idea.

Any objections?

EHL

---

From: Justin Richer <[email-masked]>
Date: Thu, 2 Sep 2010 17:27:20 -0400

+1

I've never liked the notion of not being able to extend the "grant type"
field, and this change addresses that particular gripe.

Just so I'm clear here: an extension that defines its own url-defined
grant type can also legally add and remove parameters from the endpoint,
right?

 -- Justin

On Thu, 2010-09-02 at 17:11 -0400, Eran Hammer-Lahav wrote:
> Instead of the current user of the ‘assertion’ grant type –
> 
>  
> 
>   POST /token HTTP/1.1
> 
>   Host: server.example.com
> 
> Drop the ‘assertion’ grant type and put the assertion type directly in
> the grant_type parameter:
> 
>  
> 
>   POST /token HTTP/1.1
> 
>   Host: server.example.com
> 
> I considered turning all the values into URIs but found it to be
> counter-intuitive. The practice of using “official” short names and
> extension URIs is well established and is already the general
> architecture used here. This just makes it cleaner. 
> 
>  
>

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 2 Sep 2010 14:28:20 -0700

Yes.

-----Original Message-----
From: Justin Richer [mailto:[email-masked]] 
Sent: Thursday, September 02, 2010 2:27 PM
To: Eran Hammer-Lahav
Cc: OAuth WG ([email-masked])
Subject: Re: [OAUTH-WG] Simpilfying use of assertions when requesting an access token

+1

Just so I'm clear here: an extension that defines its own url-defined grant type can also legally add and remove parameters from the endpoint, right?

 -- Justin

---

From: David Recordon <[email-masked]>
Date: Thu, 2 Sep 2010 17:21:16 -0700

I like that this also collapses the grant_type=assertion and
assertion_type=foo.

On Thu, Sep 2, 2010 at 2:28 PM, Eran Hammer-Lahav <[email-masked]>wrote:

> Just so I'm clear here: an extension that defines its own url-defined grant
> type can also legally add and remove parameters from the endpoint, right?
>
>  -- Justin
>
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth
>

---

From: Torsten Lodderstedt <[email-masked]>
Date: Fri, 3 Sep 2010 17:54:28 +0200

+1 

we just discussed the need for adding grant types in order support Telekom-specific user authentication mechanisms. So this proposal comes right in time :-)

regards,
Torsten.

---

From: David Waite <[email-masked]>
Date: Fri, 10 Sep 2010 01:37:21 -0600

I think combining the grant_type and assertion_type together is a great idea. However, I have recently been wondering if it would be a good idea to unify all the access grants to use the same parameters. 

For instance, you could have the parameters:

	grant_type - the type of access grant (of course)
	grant_qualifier - an identifier or URI associated with the grant
	grant_value - the data (such as an opaque or secret value) used for a particular type of access grant

So for the grant types mentioned below, you would have:

	password:
		a grant_qualifier of the user identifier, and a grant_value of their password

	client_credentials:
		a grant_qualifier of the client identifier, and a grant_value of the shared secret

	refresh_token:
		no grant_qualifier, a grant_value of the refresh token

	authorization_code:
		a grant_qualifier of the callback URI used to return the authorization code to the client, and a grant_value of the actual code

	<SAML assertion extension URI>:
		no grant_qualifier, a grant_value of the assertion as a string

This would seem to have the following benefits:
	- A number of query parameters defined to be used only in cases of a particular grant_type value would be eliminated
	- The qualifier/value would provide a guideline for structuring new grant types
	- The "grant_" prefix for the parameters could provide a logical grouping for any additional parameters, if a new grant type required more than the qualifier/value pair above.

I must admit however, I had difficulty figuring out how to phrase 'qualifier' so that it would apply to a callback URI. I think it makes sense in that an authorization code is issued against and only valid for a specific callback URI, but would understand if this came off feeling like overloading that parameter.

-David Waite

On Sep 2, 2010, at 3:11 PM, Eran Hammer-Lahav wrote:

> Drop the ‘assertion’ grant type and put the assertion type directly in the grant_type parameter:
>  
>   POST /token HTTP/1.1
>   Host: server.example.com
> I considered turning all the values into URIs but found it to be counter-intuitive. The practice of using “official” short names and extension URIs is well established and is already the general architecture used here. This just makes it cleaner.
>

---

From: David Recordon <[email-masked]>
Date: Fri, 10 Sep 2010 01:05:22 -0700

One of the things I really liked about WRAP (which we've largely preserved
in 2.0) is more specific flows for the different use cases. I generally
don't think that we should make this anymore generic than it already is. I
do think that merging the assertion type into the grant type parameter is
the right decision for the assertion use cases.

On Fri, Sep 10, 2010 at 12:37 AM, David Waite
<[email-masked]>wrote:

> I think combining the grant_type and assertion_type together is a great
> idea. However, I have recently been wondering if it would be a good idea to
> unify all the access grants to use the same parameters.
>
>                a grant_qualifier of the callback URI used to return the
> authorization code to the client, and a grant_value of the actual code
>
>        - A number of query parameters defined to be used only in cases of a
> particular grant_type value would be eliminated
>        - The "grant_" prefix for the parameters could provide a logical
> grouping for any additional parameters, if a new grant type required more
> than the qualifier/value pair above.
>
> I must admit however, I had difficulty figuring out how to phrase
> 'qualifier' so that it would apply to a callback URI. I think it makes sense
> in that an authorization code is issued against and only valid for a
> specific callback URI, but would understand if this came off feeling like
> overloading that parameter.
>
> -David Waite
>
> extension URIs is well established and is already the general architecture
> used here. This just makes it cleaner.
> >

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Fri, 10 Sep 2010 07:59:47 -0700

While making the spec somewhat shorter, it doesn't make it more readable or easier to implement. Getting rid of the assertion grant type and sub type parameter makes that part simpler and makes extensions more intuitive. I have looked into most abstraction ideas and have rules most of them out because they hurt the readability of the spec, even if they make it more consistent.

In -11 I am moving half way back to separate profiles for each flow.

EHL

> From: David Waite [mailto:[email-masked]]
> Sent: Friday, September 10, 2010 12:37 AM
> To: OAuth WG ([email-masked])
> Cc: Eran Hammer-Lahav
> I think combining the grant_type and assertion_type together is a great idea.
> However, I have recently been wondering if it would be a good idea to unify
> all the access grants to use the same parameters.
> 
> I must admit however, I had difficulty figuring out how to phrase 'qualifier' so
> that it would apply to a callback URI. I think it makes sense in that an
> authorization code is issued against and only valid for a specific callback URI,
> but would understand if this came off feeling like overloading that
> parameter.
> 
> -David Waite
> 
> > I considered turning all the values into URIs but found it to be counter-
> intuitive. The practice of using "official" short names and extension URIs is
> well established and is already the general architecture used here. This just
> makes it cleaner.
> >

---

From: Brian Campbell <[email-masked]>
Date: Tue, 21 Sep 2010 15:11:15 -0600

Following from that (Justin: "url-defined grant type can also legally
add and remove parameters from the endpoint, right?" / Eran: "Yes")
does the assertion parameter still make sense to have in the core
spec?  I had sort of assumed that it would be going away in favor of
whatever parameters any url-defined grant type would deem necessary.
However, Eran's "working copy" of draft -11 as of 2010-09-03 still has
the assertion parameter.  Is that area still being worked on or was
the intent to leave the parameter in for -11?

---

From: Justin Richer <[email-masked]>
Date: Tue, 21 Sep 2010 17:30:56 -0400

I personally think it makes a certain amount of sense to have the
assertion parameter: if you have only one thing to say, here's where to
say it. And I think that we've got a few cases of assertions with only a
single string to assert. However, I was always concerned with that
single parameter as the *only* allowed parameter, which Eran has said
won't be a problem. That said, if there's a movement for dropping it in
favor of extension-defined parameter sets, I won't block it.

 -- Justin

---

From: Brian Campbell <[email-masked]>
Date: Tue, 21 Sep 2010 16:19:48 -0600

I'm not sure one email from me asking for clarification exactly counts
as a movement ;-)   I was just thinking that it'd be more consistent
to have each uri-defined grant type define it's own parameter set.
Really this is what is already happening with the core defined short
names - the "authorization_code" grant type defines the "code" param,
the "password" grant type defines the "username" and "password"
params, and "refresh_token" defines "refresh_token".   The
"client_credentials" grant type is a little different in that it
doesn't directly define parameters but defers to a different part of
the spec to do that but a uri extension could conceivably do something
similar (point to other specs or other layers in the protocol stack or
whatever).

Having said all that, however, I do see the logic in what you said
about having the one assertion parameter.  But, I dunno, it just seems
a little awkward there all by itself.

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Wed, 22 Sep 2010 09:53:08 -0700

It's a question of use cases. Right now, a single assertion parameter seems to be useful. But there is no strong reason why the SAML spec can't register that as an extension. The thing is, once that is done, other specs using the same parameter (say, a future SAML spec for a newer version) will need to update the registry and potentially the RFC of the extension... Not pretty.

So if we have consensus that an assertion parameter is better than a saml2 and saml3 parameters for each extension, I'd say keep it in.

EHL

> From: Brian Campbell [mailto:[email-masked]]
> Sent: Tuesday, September 21, 2010 3:20 PM
> To: Justin Richer
> Cc: Eran Hammer-Lahav; OAuth WG ([email-masked])
> Really this is what is already happening with the core defined short names -
> the "authorization_code" grant type defines the "code" param, the
> "password" grant type defines the "username" and "password"
> "client_credentials" grant type is a little different in that it doesn't directly
> define parameters but defers to a different part of the spec to do that but a
> uri extension could conceivably do something similar (point to other specs or
> other layers in the protocol stack or whatever).
> 
> Having said all that, however, I do see the logic in what you said about having
> the one assertion parameter.  But, I dunno, it just seems a little awkward
> there all by itself.
> 
> 
> > assertion parameter: if you have only one thing to say, here's where
> > to say it. And I think that we've got a few cases of assertions with
> > only a single string to assert. However, I was always concerned with
> > that single parameter as the *only* allowed parameter, which Eran has
> > said won't be a problem. That said, if there's a movement for dropping
> > it in favor of extension-defined parameter sets, I won't block it.
> >
> >  -- Justin
> >
> >> However, Eran's "working copy" of draft -11 as of 2010-09-03 still
> >> has the assertion parameter.  Is that area still being worked on or
> >> was the intent to leave the parameter in for -11?
> >>
> >>
> >> >> counter-intuitive. The practice of using "official" short names
> >> >> and extension URIs is well established and is already the general

---

From: Brian Campbell <[email-masked]>
Date: Thu, 23 Sep 2010 15:08:30 -0600

Do parameters defined by grant types really need a registry?  I mean,
a client only presents one access grant request at a time so it's not
like there's potential for name conflicts. Am I missing something?

---

From: Marius Scurtescu <[email-masked]>
Date: Thu, 23 Sep 2010 14:27:49 -0700

> like there's potential for name conflicts. Am I missing something?

There could be conflicts with other extensions that send parameters
alongside a grant request, no?

Marius

---

From: Brian Campbell <[email-masked]>
Date: Fri, 24 Sep 2010 08:09:49 -0600

Yeah, that is true.  One of my reasons for bringing this up was in
consideration of proposing a similar simplification around client
authentication.  But clearly client authn and grants can and will be
presented together in the same request.  I was aware of the potential
for name conflicts but didn't really think it though to the point of
needing a registry.  I still think there's potential for the core spec
to be simplified, shortened and for grants and client authn to be more
consistent.  But perhaps the value of that is too much diminished by
requiring registry(s).  There's always name prefixes or name-spaces...
 but I'll drop it unless there's actual interest out there in pursuing
the ideas (which there doesn't seem to be).