[OAUTH-WG] misc comments on draft

[Brian Eaton <[e-mail]>]

Just went through the draft - it is coming along nicely.  Thanks!

This is all comments on language.  I have a few more substantive
comments that I will send separately.

“or to limit access to the methods supported by these resources.”

This didn’t parse for me.

“The use of OAuth with any other transport protocol than HTTP
[RFC2616] (or HTTP over TLS 1.0 as defined by [RFC2818] is undefined.”

Why even say this?  Should we also rule out the use of OAuth as laundry soap?

“authorization endpoint” and “token endpoint”

Maybe call these “authorization URL” and “token URL”?

access token definition is: “A unique identifier used by the client”

I agree with Dick, tokens are not identifiers.

“These authorization flows can be separated into three groups:”

This is really dense text, might be worth a bit more prose here.



“User-Agent Flow - This flow is designed for clients running inside a
user-agent (typically a web browser), and therefore cannot receive
incoming requests from the authorization server.”

This just ain’t true.  These clients can receive HTTP redirects, the
exact same way that a web server can.  How about

“User-Agent flow - this flow is designed for clients running inside a
web browser.  The flow is optimized for clients that cannot use client
secrets and must run without server-side code.”

And for the web server flow...

“This flow is designed for clients running inside an HTTP server.”

There is a typo in the description of the device flow

“Device Flow - This flow is suitable for clients executing on devices
that cannot open a web browser, but where the end user has separate
access to a web browser on another computer.”



“When issuing an access token, the scope, duration, and other access
attributes granted by the resource owner must be retained and enforced
by the resource server when receiving a protected resource request and
by the authorization server when receiving a token refresh request
made with the access token issued.”

That’s a mouthful.  How about

“Authorization servers issue tokens with scope, duration, and other
access attributes granted by the resource owner.  These restrictions
must be enforced by the resource server when receiving protected
resource requests, and by the authorization server when receiving
token refresh requests.”

“the resource owner first authenticate with”

typo.  “The resource owner first authenticates with”

“ include a query components”
typo.  “include a query component”, or “include query components”


“Clients should avoid making assumptions about the size of tokens and
other values received from the authorization server, which are left
undefined by this specification. Servers should document the expected
size of any value they issue.”

I had trouble parsing this.

How about “Token size limits are undefined by this specification.
Clients should avoid making assumptions about the size of tokens
received from the authorization server.  Servers should document the
expected sizes of tokens they issue.”


Client Credentials:

“symmetric shared secrets”... this seems to make assumptions about
HMAC being used.  Not sure I have something constructive to say.

typo.  How about “Authorization servers SHOULD NOT issue client
secrets to clients incapable of keeping their secrets confidential.”


3.5.1 User-Agent Flow

Same complaints as earlier about the description of the user-agent
flow in the introduction...

“client is incapable of receiving incoming requests” -- this isn’t true.

“the access token is encoded into the redirection URI which exposes it
to the end user and other applications residing on the computer or
device.” -- this isn’t necessarily true, depends on the device.

“authenticates the end user (via the user-agent)” - do we need to say this?

Step D in the flow (fetch to web server) often doesn’t happen, the
script tends to be cached on the user-agent.

Proposed alternate text:

The user-agent flow is a user delegation flow suitable for client
applications residing in a user-agent, typically implemented in a
browser using a scripting language such as JavaScript.  These clients
cannot keep client secrets confidential, and cannot interact directly
with authorization and resource servers.  Communication is based on
browser redirects, and authentication of the client is based on the
browser same-origin policy.


a) The client sends the user-agent to the authorization server and
includes its client identifier and redirection URI in the request.

b) authorization server establishes whether the end user grants or
denies the client's access request.

c) Assuming the end user granted access, the authorization server
redirects the user-agent to the redirection URI provided earlier. The
redirection URI includes the access token in the URI fragment.

d) script on the user-agent extracts and uses the access token.


“parameter value MUST be set to user_agent (case sensitive).”  - Do we
need to say case sensitive everywhere we mean case sensitive?  Perhaps
early on in the doc we should state that all parameters and values are
case sensitive unless stated otherwise?

“SOULD” -> SHOULD

“The redirection URI MUST NOT includes a query component as defined by
[RFC3986] section 3 if the state parameter is present.” -> Wow.  This
is convoluted.  How did we get here?

“secret_type” - wouldn’t this flow always return a bearer token?


Web Server Flow comments

“The verification code SHOULD expire shortly after it is issued and
allowed for a single use.”

How about “The verification code MUST expire shortly after it is
issued.  Verification codes MAY be single use tokens.”

“using an HTTP redirection response, or by other means available to it
via the end user's user-agent.” - can we simplify this text?  It
occurs in several places, and it always strikes me as redundant.
Maybe omit it entirely?

Definition of bearer token “a bearer token (an access token without a
matching secret)”... this strikes me as a pretty important concept.
Maybe move it up into the definitions section?

“OPTIONAL. The parameter value MUST be set to either
redirect_uri_mismatch or expired_verification_code (case sensitive).”

There are other error cases, e.g. a bad client id, or a bad client
secret.  Also note that authorization servers are unlikely to store
state about expired verification codes.  It won’t be possible to tell
whether a verification code has expired, or was never issued in the
first place.  How about these errors:
   redirect_uri_mismatch: it’s gonna happen.
   client_authentication_failure: if client id or client secret is wrong
   bad_verification_code


Device Profile comments - sent separately.


End User Credential Flows

“ (typically a username and password)”... always a username and
password, otherwise the protocol doesn’t work at all.

There is only a single flow defined in the spec, so might as well
compress this section to “Username and Password Delegation Flow”

The spec should define what the “unauthorized_client” error code means?


Autonomous Client Flows

Client secret flow:
“memorize” -> “memorized”

Can we change the type field to be “client_credentials” instead of “client_cred”

What does “unauthorized_client” mean in this context?

Assertion profile:
What does unauthorized_client mean in this context?


Accessing a protected resource

“matchin secret”

“When an access token includes a matching secret, the secret is not
included directly in the request but” <and the sentence ends>

URI Query Parameter

Typos:  and its includes the requested resource

That typo is repeated one or two other places.

Cheers,
Brian