Subject: [OAUTH-WG] Feedback on draft-ieft-oauth-v2-13.txt

From: "Freeman, Tim" <[email-masked]>
Date: Tue, 15 Mar 2011 21:56:23 +0000

Hi, I've been out of this for a while working on something else.  To get back
in, I read through the latest draft and have some feedback.  The fact that I've
been paying attention to other things for a while means my feedback has a
different slant from that of people who have been engaged.  On the one hand,
I'm can more easily see terms that are not defined before they are used, since
I don't remember what they mean.  On the other hand, my feedback might be wrong
in ways that have been talked to death in the 719 recent emails to the oauth
mailing list that I haven't yet read.  Thus, be sure not to spend much effort
skipping over redundant junk.  For what it's worth, here are my notes.

Tim Freeman
Email: [email-masked]
Desk in Palo Alto: (650) 857-2581
Home: (408) 774-1298
Cell: (408) 348-7536

Section 1.4, Authorization Grant: They're intermediate credentials representing
the resource owner authorization.  What's a resource owner authorization?
If it's the resource owner's authorization to do something, it might be good to
say what the something is.

I had to read ahead a bit to figure out that authorization codes are
authorization grants.  Section 1.4 before the beginning of section 1.4.1 should
say that the subsequent subsections describe a variety of types of
authorization grants.

Section 1.4.2. "user-agent" is used without first being defined.  I suppose
that in practice it means "browser", but you didn't use the word "browser" so I
suppose you had some other possible user agents in mind.  Examples would be
helpful.

Section 2, "Protocol endpoints".  The word "endpoint" is used without first
being defined.  Using it in the section title is fine, but the reader has to
start guessing a meaning at "The authorization process utilizes two
endpoints:".  In section 2.1 you assume that endpoints have URI's; since
"endpoint" is undefined, it's unclear whether that assumption is warranted.

Section 2.1.1, "Redirection URI".  "If a redirection URI was registered, the
authorization server MUST compare any redirection URI received at the
authorization endpoint with the registered URI."  Section 2.1 says the
authorization endpoint is where the user (presumably also the resource owner,
using the user-agent) interacts with the authorization server.  Therefore, I
conclude that the communication path between the client and the authorization
server in figure 3 does not happen by the authorization endpoint, since the
client is not the user.  I suspect it's the token endpoint, since there's a
token in Figure 3 step E.  (If that's wrong, section 2.1 needs to be changed to
say that the client uses the authorization endpoint too.)  Section 2.1.1 says
"If a redirection URI was registered, the authorization server MUST compare any
redirection URI received at the authorization endpoint with the registered
URI."  Thus I conclude that that phrase requires the authorization server to
check the redirection URI at step A of figure 3, but not step D, since that
communication comes from the client instead of the user and therefore is not
going to the authorization endpoint.  If there is no requirement to check the
redirection URI in step D, it's unclear why it's there.

Section 3 "Client Authentication".  I think the intent is that client
identifiers are public, since they are disclosed to the user-agent in section
4.1, "Authorization Code".  You might want to say so, otherwise one might
reason that clients are required to publish their client identifiers (in
section 4.1), and client identifiers are part of the client credentials
(section 3), no clients can keep their credentials confidential, so no
authorization servers should issue client credentials to any clients.  
Perhaps client identifiers are not part of the client credentials?

Section 4, "Obtaining Authorization".  Change "requesting" to "request" in "The
authorization is expressed in the form of an authorization grant which the
client uses to requesting the access token."

Figure 3 in section 4.1.  "User authenticates" is a two-way communication
because the authorization server will typically prompt the user to authenticate,
but the arrow only points from user-agent to authorization server, so there is
no opportunity to prompt.  I think you want arrows pointing in both directions
on the "User authenticates" path.

Figure 3 says that communication D from the client to authorization server
includes the redirect URI, but the text for communication D does not say that.
We should get clear on whether the redirect URI is public or not.  If it's
public, and the client, all possible entities wishing to impersonate the
client, and the authorization server all know it, then there's no value in
communicating it from the client to the authorization server.  If it's private,
that should be specified when the redirection URI is introduced at step A, and
the alternative of omitting it because it's common knowledge to the client and
the authentication server (in section 2.1.1, first paragraph) goes away since
it's disclosed to (possibly adversarial) user agents in Figure 3, step A.

Figure 3 step B: You'll need to make clear that if the resource owner is a
human, there will be a need to uniquely identify the client and the requested
resource in a human-readable way.  For example, if the actual client is
"Microsoft, Inc.", and I am able to register a client "M1crosoft, Inc.", and
humans in practice cannot distinguish "Microsoft" from "M1crosoft", people
might give my client authorizations that they intended to give to Microsoft.  

I can imagine using social engineering to leave the user in the middle of one
OAuth exchange while they start another in another window, and if popup windows
are used for interacting with the user while authenticating, they might
authenticate the wrong client.  In other words, the rhythm of the interaction
is not a reliable cue to tell a human which client he's authenticating to, so
the human-readable name of the client must be unambiguously stated on the
screen when the user is accepting or denying the authorization.

The human-readable name corresponding to a client id has to come from a
database on the authorization server, since the client cannot be trusted to
provide it.

A similar scenario can be created where imperfect human reading comprehension
can cause authentication to the wrong resource, if the operators of the
authorization server allow arbitrary names for resources.

Figure 3 step C: The redirection URI also has to include the client's state, if
the client specified state in step A, right?  Otherwise the client doesn't get
the state and the state cannot fulfill its function of disambiguating
concurrent requests.

Figure 3 step E: The description does not mention that the redirect URI is part
of the information being validated, but it is offered as input to the process
in step D.  You should say in the description of E what that input is used for.

Section 4.1.3: At the end of this section, you say the authorization server
much check that the redirection URI matches the redirection URI used by the
authorization server to deliver the authorization code.  This should be
mentioned at step D of figure 3.  The scenario where you lose if check is not
done should be stated, since it's not obvious.

I skipped sections 4.2, 4.3, and 4.4, since that's not the kind of
authorization I need to do.

Section 9: "Security Considerations" are TBD?  Okay, on reviewing the
announcement, this version wasn't meant to be a final draft.  No problem.
Maybe my suggestion above about human-readable names for clients and resources
will give rise to some text here.

Section 10.2.2: It says the "state" parameter can be present in the
authorization request and authorization response.  I suppose the authorization
response is the response to the authorization request, but in the figures up to
this point the phrases "authorization grant" (Figure 1) or "authorization code"
(Figure 3) are used, not authorization response.  I see that there is a section
4.1.2 "Authorization Response".  It would be good to identify which arrows in
Figures 1 and 3 are Authorization Responses (I suspect B and C, respectively).
It looks like that text would not fit into the space available in the figure,
but it would fit well in the steps listed below each of the figures.

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 24 Mar 2011 23:40:46 -0700

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf
> Of Freeman, Tim
> Sent: Tuesday, March 15, 2011 2:56 PM

<snip>

I think authorization, user-agent, endpoint are well understood terms among those working with HTTP which OAuth clearly requires a certain level of familiarity, but I'll sprinkle some references to make it clearer.

> authorization endpoint is where the user (presumably also the resource
> owner, using the user-agent) interacts with the authorization server.
> Therefore, I conclude that the communication path between the client and
> the authorization server in figure 3 does not happen by the authorization
> endpoint, since the client is not the user.

The authorization endpoint response to the user-agent, redirects it back to the client's callback URI.

>  I suspect it's the token endpoint,
> since there's a token in Figure 3 step E.  (If that's wrong, section 2.1 needs to
> be changed to say that the client uses the authorization endpoint too.)

Yes.

> Section 2.1.1 says "If a redirection URI was registered, the authorization
> server MUST compare any redirection URI received at the authorization
> endpoint with the registered URI."  Thus I conclude that that phrase requires
> the authorization server to check the redirection URI at step A of figure 3, but
> not step D, since that communication comes from the client instead of the
> user and therefore is not going to the authorization endpoint.  If there is no
> requirement to check the redirection URI in step D, it's unclear why it's there.

The client sets the redirection URI used by the resource owner to communicate with the authorization endpoint. Once complete, the client uses the same redirection URI value to obtain a token. In the second step, it is used for verification and protection against an attack, not to redirect anything. Explaining the purpose of the redirection URI in step E belongs in the security considerations section.
 
> Section 3 "Client Authentication".  I think the intent is that client identifiers
> are public, since they are disclosed to the user-agent in section 4.1,
> "Authorization Code".  You might want to say so, otherwise one might reason
> that clients are required to publish their client identifiers (in section 4.1), and
> client identifiers are part of the client credentials (section 3), no clients can
> keep their credentials confidential, so no authorization servers should issue
> client credentials to any clients.

New text:

        Client credentials are used to identify and authenticate the client. The client
        credentials include a client identifier - a unique string issued to the client to
        identify itself to the authorization server. The client identifier is not a secret, it is
        exposed to the resource owner, and MUST NOT be used alone for client authentication. Client
        authentication is accomplished via additional means such as a matching client password.

> because the authorization server will typically prompt the user to
> authenticate, but the arrow only points from user-agent to authorization
> server, so there is no opportunity to prompt.  I think you want arrows
> pointing in both directions on the "User authenticates" path.

The arrow passes through the user-agent to the resource-owner... the limitations of ascii art.

> We should get clear on whether the redirect URI is public or not.  If it's public,
> and the client, all possible entities wishing to impersonate the client, and the
> authorization server all know it, then there's no value in communicating it
> from the client to the authorization server.  If it's private, that should be
> specified when the redirection URI is introduced at step A, and the
> alternative of omitting it because it's common knowledge to the client and

It's a session fixation attack protection which I can't recall anymore. It's explained somewhere in the list archives.
 
> OAuth exchange while they start another in another window, and if popup
> windows are used for interacting with the user while authenticating, they
> might authenticate the wrong client.  In other words, the rhythm of the
> interaction is not a reliable cue to tell a human which client he's
> authenticating to, so the human-readable name of the client must be
> unambiguously stated on the screen when the user is accepting or denying
> the authorization.
> 
> A similar scenario can be created where imperfect human reading
> comprehension can cause authentication to the wrong resource, if the
> operators of the authorization server allow arbitrary names for resources.

All good feedback for the security considerations section.

> authorization request and authorization response.  I suppose the
> authorization response is the response to the authorization request, but in
> the figures up to this point the phrases "authorization grant" (Figure 1) or
> "authorization code"
> It looks like that text would not fit into the space available in the figure, but it
> would fit well in the steps listed below each of the figures.

Just (C).

EHL

---

From: "Freeman, Tim" <[email-masked]>
Date: Fri, 25 Mar 2011 18:47:38 +0000

Snipping out everything I agree with, there's only this remaining, including some context so this email might make sense in isolation:

Eran:
>The client sets the redirection URI used by the resource owner to communicate 
>with the authorization endpoint. 

Agreed.

>Once complete, the client uses the same 
>redirection URI value to obtain a token. 

Agreed.

>In the second step, it is used for 
>verification and protection against an attack, not to redirect anything. 

I agree with that statement.  My point was that the spec should say so.  Since in Section 2.1 "Authorization Endpoint" you have the sentence

   If a redirection URI was registered, the authorization
   server MUST compare any redirection URI received at the authorization
   endpoint with the registered URI.

IMO somewhere in Section 2.2 "Token Endpoint" you want to at least have a sentence like

   If a redirection URI was registered, the authorization
   server MUST compare any redirection URI received at the token
   endpoint with the registered URI.

or perhaps

   If a redirection URI was registered, the authorization
   server MUST compare any redirection URI received at the token
   endpoint with the redirection URI used earlier at the authorization 
   endpoint.

depending on what you meant.  IMO the latter is more secure.
 
>Explaining the purpose of the redirection URI in step E belongs in the 
>security considerations section.

I suppose we agree that the security considerations section should say why we're doing it, but so far we're failing to discuss whether step E should say what we're doing.  IMO step E of Figure 3 should change from:

        The authorization server validates the client credentials and
        the authorization code and if valid, responds back with an
        access token.

to:

        The authorization server validates the client credentials and
        the authorization code and checks that the redirect URI matches 
        the value used at step A.  If all these checks pass, it responds 
        with an access token.

Actually, I'm a little confused here.  The spec seems to allow registering some but not all components of the redirect URI.  In that case, should step E be checking that all of the redirect URI is equal to the value used in step A, or checking that it's consistent with those components that were registered?  The security works better if you do the former, but I'm not aware that the spec says that anywhere.
 
Tim Freeman

-----Original Message-----
From: Eran Hammer-Lahav [mailto:[email-masked]] 
Sent: Thursday, March 24, 2011 11:41 PM
To: Freeman, Tim; [email-masked]
Subject: RE: Feedback on draft-ieft-oauth-v2-13.txt

<snip>

Yes.

 

New text:

 

Just (C).

EHL

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Fri, 25 Mar 2011 12:35:18 -0700

> From: Freeman, Tim [mailto:[email-masked]]
> Sent: Friday, March 25, 2011 11:48 AM

> Tim:
> > Section 2.1.1 says "If a redirection URI was registered, the
> > authorization endpoint with the registered URI."  Thus I conclude that
> > that phrase requires the authorization server to check the redirection
> > URI at step A of figure 3, but not step D, since that communication
> > comes from the client instead of the user and therefore is not going
> > to the authorization endpoint.  If there is no requirement to check the
> >The client sets the redirection URI used by the resource owner to
> >communicate with the authorization endpoint.
> 
> Agreed.
> 
> >Once complete, the client uses the same redirection URI value to obtain
> >a token.
> 
> Agreed.
> 
> I agree with that statement.  My point was that the spec should say so.  Since
> in Section 2.1 "Authorization Endpoint" you have the sentence
> 

Since the redirection URI is required to be explicitly included when using the authorization code grant type, the fact whether it was pre-registered is irrelevant at this point. The client simply has to provide the redirection URI where the code was received which will surface anyone messing with the flow in the middle and manipulating the code.

I have tweaked the language around the redirection verification in a few places in -14. Can you take a look again and see if it works better for you?

> I suppose we agree that the security considerations section should say why
> we're doing it, but so far we're failing to discuss whether step E should say
> what we're doing.  IMO step E of Figure 3 should change from:
> 

How about:

              The authorization server validates the client credentials, the authorization code,
              and ensures the redirection URI received matches the URI used to redirect the client
              in step (C). If valid, responds back with an access token.

EHL

---

From: "Freeman, Tim" <[email-masked]>
Date: Sat, 26 Mar 2011 00:30:21 +0000

> Since the redirection URI is required to be explicitly included 
> when using the authorization code grant type, the fact whether it 
> was pre-registered is irrelevant at this point. 

That makes sense, thanks.

> The client simply has to provide the redirection URI where the code 
> was received which will surface anyone messing with the flow in the 
> middle and manipulating the code.
>
> I have tweaked the language around the redirection verification in a 
> few places in -14. Can you take a look again and see if it works better 
> for you?

I looked a bit and didn't see the change beyond the Figure 3 step (E) revision you mention below.  It might be there, I didn't look for long.  I'm inclined to drop the issue at this point.  I'm sure you did something reasonable.

Makes perfect sense technically, but I have minor grammar issues: the list separated by commas feels irregular.  I think the English teacher would write "Parallelism" in the margin in red ink.  Also, the second sentence has no subject, and "responds back" is redundant.  I would write:

>     The authorization server validates the client credentials, validates the authorization code,
>     in step (C). If valid, the authorization server responds with an access token.
 
Tim Freeman

-----Original Message-----
From: Eran Hammer-Lahav [mailto:[email-masked]] 
Sent: Friday, March 25, 2011 12:35 PM
To: Freeman, Tim; [email-masked]
Subject: RE: Feedback on draft-ieft-oauth-v2-13.txt

How about:

EHL