[OAUTH-WG] More draft-ietf-oauth-assertions-03 comments

["Tschofenig, Hannes (NSN - FI/Espoo)" <[e-mail]>]

Here a few minor comments:

The specification does not provide a lot of hints for the client when an
error occurs. For example, Section 4.1.1 only says "invalid_client" is
something goes wrong with the assertion processing in case of client
authentication. The same is true for the authorization grant error
response in Section 4.2.1. 

What about errors like?
*	Assertion was not fresh - replay detected (based on the
assertion ID)
*	Issuer unknown or not trusted
*	Assertion couldn't be parsed
*	The assertion format is unknown
*	Signature covering the assertion couldn't be verified
*	Audience does not match
*	Assertion expired (based on 'expired at' element)
*	Missing mandatory elements in the assertion

There are a lot of "SHOULDs" in the specification and I was wondering
why this has to be the case. Typically, there has to be a good reason
why there is a SHOULD rather than a MUST or at least an explanation in
case there are different processing alternatives. 

For example, Section 5.2 says: 
"When the client is acting on behalf of itself, the
      Principal SHOULD be the "client_id".
" 

When the client is acting on his own behalf then it would be good to say
in what cases the principal element does not contain the client_id. In
general, it seems that the client_id and the principal are pretty much
the same thing (the fields just appear twice). 

The same issue regarding the "SHOULD" shows up in other places as well,
such as with the issuer in the same section: "If an assertion is
self-asserted, the
      Issuer SHOULD be the "client_id"." 

Again same section: "The Audience SHOULD be the URL of the Authorization
      Server's Token Endpoint."

In case it is not an URL what else should it be? When can this other
case happen?

You also write: "The assertion MUST contain an Issuer." 
That's great but what is the relationship if the assertion already
contains an issuer as part of the signature that covers the party that
signed the assertion (which is the case in SAML). Do they have to match?

Section 6.3 and Section 6.4 say:

" 
   o  The grant_type HTTP request parameter MUST indicate the assertion
      format.
"

Is this correct? Shouldn't it be rather 

"
   o  The "client_assertion_type" HTTP parameter MUST identify the
      assertion format.
"
 
Difference between Section 6.3 and 6.3: anonymous user or not

These two sections are identical with one exception: the content of the
principal element. 
Wouldn't it make sense to merge the two cases and then to indicate that
the content of the principal element varies? 

In Section 6.2 you write: 

When a client is accessing resources on behalf of itself, it SHOULD
   do so in a manner analogous to the Client Credentials flow defined in
   Section 4.4
<http://tools.ietf.org/html/draft-ietf-oauth-assertions-03>  of OAuth
2.0 [I-D.ietf-oauth-v2
<http://tools.ietf.org/html/draft-ietf-oauth-assertions-03> ].

Use  "Client Credentials Grant flow" instead of "Client Credentials
flow"

In Section 6.3 you write:

"
When a client is accessing resources on behalf of a user, it SHOULD
   be treated as using an assertion as an Authorization Grant according
   to Section 4.2
<http://tools.ietf.org/html/draft-ietf-oauth-assertions-03> . 
"

This is a confusing sentence. I believe what you are trying to say is
that the description in Section 4.2 MUST be followed.
 
IANA consideration section: This section is essentially the
communication you have with IANA to request values to be added to
existing registries. It helps them to be specific about what information
you want to get added to what registry. 

For example, Section 8.1 registers an additional parameter called
"assertion". It would be useful to just say that this is a new entry to
the "OAuth Parameters Registry" established in Section 11.2 of
[I-D.ietf-oauth-v2
<http://tools.ietf.org/html/draft-ietf-oauth-assertions-03> ]. 

As a minor nit here The parameter usage location indicates "client
authentication, token request". Client authentication is not a valid
location per Section 11.2.1. 

The same comment applies to Section 8.2 and Section 8.3.

Ciao
Hannes