Hey -
I've got a bunch of nit-type comments on oauth2 draft 9. I'm going to
bundle them all together here.
There are a few more significant issues, those I'll start separate threads for.
Introduction, paragraph 2:
"In the traditional client-server authentication model,... presenting
the resource owner's credentials.... etc..."
I think this paragraph could be made a little more blunt to good
effect. How about something like this:
"In the traditional client-server model, third-party applications
request access to the user's password in order to authenticate and
gain access to the user's resources. This creates several problems:
- the third-party application is required to save the user's password,
in clear-text, in order to access the user's data in the future.
- servers that need to allow third-party access must support password
authentication, despite the fundamental security weaknesses created by
passwords.
- the third-party application gains overly broad access to the user's data.
OAuth addresses these problems by introducing a third role to the
traditional client-server authentication model, the resource owner.
In OAuth, the client (which is usually not the resource owner, but is
acting on their behalf) requests access to resources controlled by the
resource owner and hosted by the resource server."
"In OAuth, the client (which is usually not the resource owner, but is
acting on its behalf)"
I'd suggest saying "acting on their behalf". Using "its" is slightly
confusing, it's a little unclear whether the possessive pronoun refers
to the client or the resource owner.
Introduction, paragraph 6:
I love that the photo printing example has been so consistent for so
long! Let's hope we never need to describe this again.
This section calls the photo sharing service both the resource server
and the authorization server. Might be better to call out the
authorization server with a separate name here. How about this:
"Instead, she authenticates directly with an authentication service
trusted by the photo sharing service (authorization server) which
issues the printing service delegation-specific credentials (token)."
Terminology:
token: some of these sentences are long, and can reasonably be broken
up. "Specific scope, duration, and other authorization attributes"
also reads badly for me. I can't pin down what it is (I think the
sentence is grammatically correct), it just sounds wrong. How about
this:
token: A string representing an access authorization issued to the
client. The string is usually opaque to the client. Tokens represent
specific scopes and durations of access, granted by the resource
owner, and enforced by the resource server and authorization servers.
The token may self-contain the authorization information in a
verifiable manner (i.e. the token may consist of some data and
signature). Alternatively, the token may denote an identifier used to
retrieve the authorization information."
I'd also add this sentence at the end
"tokens may be pure capabilities, or specific authentication
credentials may be required in order for a client to use a token."
Capability is a term-of-art, it will put people who are looking at the
security of the spec in the right mood. Even if people don't like my
phrasing, let's please find a way to work it into the definition.
The indentation in this section threw me off, I don't think it's
necessary. I think we could just define "resource owner" and
"end-user" at the top level. Likewise for token, access token, and
refresh token. (Look, I said at the beginning of this note these were
nits.)
Introduction
"The client should not interact directly with the resource owner":
this just isn't true. This is like saying that the printing service
should not interact with the user who wants to use them.
How about "The client should not request the resource owner's
credentials directly. Instead it should request authorization via..."
"The process used to obtain an authorization code utilized the
end-user's user-agent and is described in Section 3."
I think there's a shift in tense there that reads funny. Also lots of
repetition of "uses/used/utilized/end-user/user-agent". How about
"The process used to obtain the end-users authorization involves the
end-user's user-agent and is described in section 3."
"basic credentials". This makes sense if you've read the BNF in the
http basic auth spec, and is otherwise weird. I think everywhere that
refers in prose to the username and password should call them
"username and password" or "password credentials". Let's not use
"basic credentials" at all. We could use "basic-credentials" in BNF
that refers to the exact format used by the HTTP spec, but otherwise
let's skip it.
1.4.1 Web Server Flow
Missing a period.
"The web client initiates the flow by redirecting the end-user's
user-agent to the end-user authorization endpoint as described in
Section 3 >.< The client..."
1.4.2 User-Agent
"an access token requests" reads wrong, looks like half of this
sentence got edited one way and half another. How about "Unlike other
profiles in which the client makes separate end-user authorization
request and access token requests,..."
Description of the user-agent profile has long sentences, and the
description of the client secret bits read weird. But I think this
section isn't true any longer anyway... I'll save that for a more
substantive e-mail.
1.4.3 "Native Application"
"Native Application Profile" or "Native application Flow" would both
be better titles. Just "Native Application" sounds funny.
"generally discouraged as it hands the end-user's password directly to
the 3rd party." It's a little unclear who the 3rd party is here.
I think this section could be better written as follows:
* Prompt end users for their password and use them directly to obtain
an access token. This is generally discouraged, as it requires that
the application save the password in clear-text. It also requires
that the server support password authentication."
1.4.4 Autonomous
I think we need a better definition of Autonomous Clients, but I'm
damned if I can think of one right now.
"The scope of the access
token is limited to the protected resources under the control of
the client, or that of another resource owner previously arranged
with the authorization server."
That sounds a lot more complicated than it is.
How about "The access token does not allow the client to act on behalf
of an end-user. The token identifies the client, and so is scoped to
the resources to which the client has direct access."
2. Client Credentials
"regardless whether the credentials are identical". How about
"regardless of whether the credentials are identical."
But honestly I don't understand why this paragraph is necessary.
Clients should obey the spec.
3. Obtaining End-User Authorization
"the end-user access grant is expressed as an authorization code..."
I don't think that's true in all of the profiles. How about "The
client is issued tokens that represent the access granted by the
end-user."
4.1.2
" The authorization server MUST validate the client credentials and
end-user credentials and if valid issues an access token response as
described in Section 4.2."
There's a change of tense in there. Should be "and if valid issue an
access token response..."
4.2 Access Token Response
Extra comma. Should be "The sizes of tokens and other values received
from the authorization server are left undefined by this
specification."
Cheers,
Brian
_______________________________________________
OAuth mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/oauth
