Subject: [OAUTH-WG] TODO: Mike J./Chuck M. (or me) to draft 4.5.1 subsection on assertions

From: Brian Campbell <[email-masked]>
Date: Tue, 24 May 2011 08:25:12 -0600

One of the action items out of yesterday's meeting was to draft some
text for a section 4.5.1 in core that defined the optional but
recommended use of an "assertion" parameter for extension grants where
the use of a single parameter to carry the grant/assertion was
possible.  Below is a first cut at some proposed text that hopefully
avoids some of the awkwardness that EHL described in previous attempts
to introduce such a parameter.  Comments or edits or editorial
improvements are, of course, welcome.  But I think this hopefully
captures the intent of what was discussed yesterday (and before).

If we get some consensus to make this change, I think a couple of
other actions are implied.

- The IANA assertion parameter registration request
(http://tools.ietf.org/html/draft-ietf-oauth-saml2-bearer-04#section-4.1)
should be removed from the SAML draft and put into
http://tools.ietf.org/html/draft-ietf-oauth-v2

- The http://tools.ietf.org/html/draft-jones-oauth-jwt-bearer-00 spec
will change the parameter it uses from jwt to assertion and drop the
registration request for jwt
(http://tools.ietf.org/html/draft-jones-oauth-jwt-bearer-00#section-4.1)

--- proposed text for sections 4.5 & 4.5.1 ---

4.5. Extensions

   The client uses an extension grant type by specifying the grant type
   using an absolute URI (defined by the authorization server) as the
   value of the "grant_type" parameter of the token endpoint, and by
   adding any additional parameters necessary.

   If the access token request is valid and authorized, the
   authorization server issues an access token and optional refresh
   token as described in Section 5.1.  If the request failed client
   authentication or is invalid, the authorization server returns an
   error response as described in Section 5.2.

4.5.1 Assertion Based Extension Grants

  If the value of the extension grant can be serialized into a single
  parameter, as is case with a number of assertion formats, it is
  RECOMMENDED that that a parameter named "assertion" be used to
  carry the value.

   assertion
         REQUIRED.  The assertion. The format and encoding of the
             assertion is defined by the authorization server or
             extension specification.

   For example, to request an access token using a SAML 2.0 assertion
   grant type as defined by [I-D.ietf-oauth-saml2-bearer], the client
   makes the following HTTP request using transport-layer security (line
   breaks are for display purposes only):

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

   grant_type=http%3A%2F%2Foauth.net%2Fgrant_type%2Fsaml%2F2.0%2F
   bearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDUtM
   [...omitted for brevity...]V0aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24-

---

From: Anthony Nadalin <[email-masked]>
Date: Tue, 24 May 2011 19:01:36 +0000

I think that this will be better moved into a separate document on assertions (were both authorization and authentication are talked about) and not to include in 4.5.1 but would like to see a reference in 4.5.1 to the new document

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Brian Campbell
Sent: Tuesday, May 24, 2011 7:25 AM
To: oauth
Subject: [OAUTH-WG] TODO: Mike J./Chuck M. (or me) to draft 4.5.1 subsection on assertions

One of the action items out of yesterday's meeting was to draft some text for a section 4.5.1 in core that defined the optional but recommended use of an "assertion" parameter for extension grants where the use of a single parameter to carry the grant/assertion was possible.  Below is a first cut at some proposed text that hopefully avoids some of the awkwardness that EHL described in previous attempts to introduce such a parameter.  Comments or edits or editorial improvements are, of course, welcome.  But I think this hopefully captures the intent of what was discussed yesterday (and before).

If we get some consensus to make this change, I think a couple of other actions are implied.

- The http://tools.ietf.org/html/draft-jones-oauth-jwt-bearer-00 spec will change the parameter it uses from jwt to assertion and drop the registration request for jwt
(http://tools.ietf.org/html/draft-jones-oauth-jwt-bearer-00#section-4.1)

--- proposed text for sections 4.5 & 4.5.1 ---

4.5. Extensions

   assertion

   POST /token HTTP/1.1
   Host: server.example.com

   grant_type=http%3A%2F%2Foauth.net%2Fgrant_type%2Fsaml%2F2.0%2F
   bearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDUtM
   [...omitted for brevity...]V0aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24-
_______________________________________________
OAuth mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/oauth

---

From: Brian Campbell <[email-masked]>
Date: Wed, 25 May 2011 07:54:08 -0600

That is another way to approach it and I understand there has been
some talk about that lately.  While there are admittedly some
commonalities between assertion based grants and an HTTP parameter
based client authentication extension point, I personally think that
lumping them together is unnecessarily confusing.   It is also a more
significant change and it seems like, at this point in the process, it
might be better to aim for more concise and targeted changes.

---

From: Anthony Nadalin <[email-masked]>
Date: Wed, 25 May 2011 17:07:39 +0000

In our case they are tightly bound as the assertions (same assertion) will be used for authentication and also to grant authorization as this is what was in scope with WRAP, so not addressing the assertion authentication is an issue for us and I assume others also. 

-----Original Message-----
From: Brian Campbell [mailto:[email-masked]] 
Sent: Wednesday, May 25, 2011 6:54 AM
To: Anthony Nadalin
Cc: oauth
Subject: Re: [OAUTH-WG] TODO: Mike J./Chuck M. (or me) to draft 4.5.1 subsection on assertions

That is another way to approach it and I understand there has been some talk about that lately.  While there are admittedly some commonalities between assertion based grants and an HTTP parameter based client authentication extension point, I personally think that
lumping them together is unnecessarily confusing.   It is also a more
significant change and it seems like, at this point in the process, it might be better to aim for more concise and targeted changes.

On Tue, May 24, 2011 at 1:01 PM, Anthony Nadalin <[email-masked]> wrote:
> I think that this will be better moved into a separate document on 
> assertions (were both authorization and authentication are talked 
> about) and not to include in 4.5.1 but would like to see a reference 
> in 4.5.1 to the new document
>
> (http://tools.ietf.org/html/draft-ietf-oauth-saml2-bearer-04#section-4
> .1) should be removed from the SAML draft and put into

---

From: Brian Campbell <[email-masked]>
Date: Wed, 25 May 2011 13:22:17 -0600

It's not exactly clear to me what that means.

Near the end of the interim meeting on Monday there was a specific
discussion that resulted in a TODO item to draft a 4.5.1 subsection.
That's what I've done here and I believe it captures the intent
discussed at the meeting.  I've written a small proposal for specific
text to be included in the core specification and described the
subsequent changes (simplifications actually) that would follow in
companion specification.

I've made a specific and actionable proposal.  I'm happy to discuss
the merits of the proposal and if the WG should accept it or not.

If you feel that your proposal of a separate document is more
appropriate, I'd suggest you actually write such a document and
describe how it impacts existing drafts so that it can be reviewed and
discussed. My understanding (Chairs, correct me if I'm wrong) is that
such a document would need to be accepted as a working group item in
order to be referenced from draft-ietf-oauth-v2 or used/referenced by
draft-ietf-oauth-saml2.

---

From: Anthony Nadalin <[email-masked]>
Date: Wed, 25 May 2011 22:03:29 +0000

So the separate document was already discussed in the design team and in the meeting on Monday, the action item was given to look at creating a separate document for assertion covering authentication and authorization.

-----Original Message-----
From: Brian Campbell [mailto:[email-masked]] 
Sent: Wednesday, May 25, 2011 12:22 PM
To: Anthony Nadalin
Cc: oauth
Subject: Re: [OAUTH-WG] TODO: Mike J./Chuck M. (or me) to draft 4.5.1 subsection on assertions

Near the end of the interim meeting on Monday there was a specific discussion that resulted in a TODO item to draft a 4.5.1 subsection.
That's what I've done here and I believe it captures the intent discussed at the meeting.  I've written a small proposal for specific text to be included in the core specification and described the subsequent changes (simplifications actually) that would follow in companion specification.

I've made a specific and actionable proposal.  I'm happy to discuss the merits of the proposal and if the WG should accept it or not.

If you feel that your proposal of a separate document is more appropriate, I'd suggest you actually write such a document and describe how it impacts existing drafts so that it can be reviewed and discussed. My understanding (Chairs, correct me if I'm wrong) is that such a document would need to be accepted as a working group item in order to be referenced from draft-ietf-oauth-v2 or used/referenced by draft-ietf-oauth-saml2.

On Wed, May 25, 2011 at 11:07 AM, Anthony Nadalin <[email-masked]> wrote:
> commonalities between assertion based grants and an HTTP parameter based client authentication extension point, I personally think that lumping them together is unnecessarily confusing.   It is also a more significant change and it seems like, at this point in the process, it might be better to aim for more concise and targeted changes.
>
>

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Wed, 25 May 2011 20:22:06 -0700

We are taking multiple paths trying to find the best balance.

There is an effort to draft a new document describing client authentication using assertions. That effort seems to expand to encompass all assertion related business. I'm supportive of that approach. This document may or may not swallow the SAML bearer document - I don't have an opinion on that.

There is another effort to take a narrow approach and to simply move the common fragment (the 'assertion' parameter) out of the SAML bearer spec and back into v2. I'm also supportive of that approach. This is the proposed text listed below.

How can I be supportive of both? Well, both sounds promising and will produce a useful document structure. However, as someone who has no intention of using assertions of any kind with OAuth, I can't really say which will make developers' life easier. 

EHL

> From: [email-masked] [mailto:[email-masked]] On Behalf
> Of Anthony Nadalin
> Sent: Wednesday, May 25, 2011 3:03 PM
> To: Brian Campbell
> Cc: oauth
> So the separate document was already discussed in the design team and in
> the meeting on Monday, the action item was given to look at creating a
> separate document for assertion covering authentication and authorization.
> 
> That's what I've done here and I believe it captures the intent discussed at
> the meeting.  I've written a small proposal for specific text to be included in
> the core specification and described the subsequent changes (simplifications
> actually) that would follow in companion specification.
> 
> I've made a specific and actionable proposal.  I'm happy to discuss the merits
> of the proposal and if the WG should accept it or not.
> 
> If you feel that your proposal of a separate document is more appropriate,
> I'd suggest you actually write such a document and describe how it impacts
> existing drafts so that it can be reviewed and discussed. My understanding
> (Chairs, correct me if I'm wrong) is that such a document would need to be
> accepted as a working group item in order to be referenced from draft-ietf-
> oauth-v2 or used/referenced by draft-ietf-oauth-saml2.
> 
> > In our case they are tightly bound as the assertions (same assertion) will be
> used for authentication and also to grant authorization as this is what was in
> scope with WRAP, so not addressing the assertion authentication is an issue
> for us and I assume others also.
> >
> based client authentication extension point, I personally think that lumping
> them together is unnecessarily confusing.   It is also a more significant change
> and it seems like, at this point in the process, it might be better to aim for
> more concise and targeted changes.
> >
> >
> >> One of the action items out of yesterday's meeting was to draft some text
> for a section 4.5.1 in core that defined the optional but recommended use of
> an "assertion" parameter for extension grants where the use of a single
> parameter to carry the grant/assertion was possible.  Below is a first cut at
> some proposed text that hopefully avoids some of the awkwardness that
> EHL described in previous attempts to introduce such a
> parameter.  Comments or edits or editorial improvements are, of course,
> welcome.  But I think this hopefully captures the intent of what was
> discussed yesterday (and before).
> >>

---

From: Brian Campbell <[email-masked]>
Date: Thu, 26 May 2011 15:07:56 -0600

A new document describing client authentication using assertions via
HTTP parameters that *does not* expand to encompass all assertion
related business, I believe, will also produce a useful document
structure.  At the same time it introduces fewer changes, while still
arriving at the same functionality, to documents that I thought were
being pushed towards last call.  It just seems to me that that option
should be on the table as well.  Just because two things both use the
word "assertion" doesn't necessarily mean they belong together.