Subject: [OAUTH-WG] OAuth 2.0 v21 Nits and Typos

From: "Anganes, Amanda L" <[email-masked]>
Date: Mon, 19 Sep 2011 11:22:34 -0400

Lots of minor grammar and wording catches here. I apologize if any of these were already brought up and addressed.

1.2.3, second paragraph: "When issuing an implicit grant, the authorization server does not authenticate the client and in some cases, the client identity can be verified..." should be "When issuing an implicit grant, the authorization server does not authenticate the client. In some cases, the client identity can be verified..."

1.5, first paragraph. Last sentence should be changed to "Issuing a refresh token is optional. If an authorization server issues a refresh token, it is included when issuing an access token."

2.1, definition of public client: last sentence ends with "via any other mean" which should be "via any other means".
2.1, definition of native applications: "On the other hand, dynamically issued credentials such as access tokens or refresh tokens, can receive an acceptable level of protection" should be "On the other hand, dynamically issued credentials such as access tokens or refresh tokens can receive an acceptable level of protection" (final comma is unnecessary).

3.1, second paragraph. Add a comma after "beyond the scope of this specification", so it reads "The means through which the client obtains the location of the authorization endpoint are beyond the scope of this specification, but the location is typically provided in the service documentation".

3.2.1, first sentence. Unnecessary comma between "requirements" and "MUST"; should read "Confidential clients, clients issued client credentials, or clients assigned other authentication requirements MUST authenticate..."

4.1, section (E): last sentence is missing a subject. "If valid, responds back with an..." should read "If valid, the authorization server responds back with an..."

4.1.2 and 4.1.2.1, also 4.2.2 and 4.2.2.1, state description: last sentence is missing a MUST. Should read "REQUIRED if the state parameter was present in the client authorization request. The state parameter MUST be set to the exact value received from the client."

4.1.3, redirect_uri description: Change "REQUIRED, if the redirect_uri parameter was included in the authorization request described in Section 4.1.1, and their values MUST be identical" to "REQUIRED, if the redirect_uri parameter was included in the authorization request as described in Section 4.1.1. If included, the two values MUST be identical".

4.1.3, final paragraph ("The authorization server MUST: ..."). Is any additional normative language required for lists such as this in order to specify that the AS must do ALL of the items in the list? Similar MUST lists appear elsewhere throughout the rest of the document.
Also, final bullet should be reworded; suggest "ensure that the redirect_uri parameter is present if the redirect_uri parameter was included in the initial authorization request as described in Section 4.1.1, and if included ensure that their values are identical".

4.2, first paragraph: clarify that implicit grants can be used only for access tokens by including the word "only" here: "The implicit grant type is used to obtain access tokens only..."

4.3.2, paragraph after term parameter descriptions: "If the client type is confidential or was issued client credentials" should be reworded to "If the client type is confidential or the client was issued client credentials".

9, bullets following second paragraph: Change this to a definition list format instead of a bulleted list.
9, final bullet following "when choosing between an external or embedded user-agent...": Last sentence starts "Embedded user-agent educate..." but should be "Embedded user-agents educate..."

10.2, second paragraph: last sentence is a fragment. Reword to "For example, the authorization server should engage the resource owner to assist in identify the client and its origin."

10.5, second paragraph, first sentence: extraneous comma between "authorization server" and "is". Should be "...verify that the resource owner who granted authorization at the authorization server is the same resource owner..."

10.6, last paragraph, first sentence: extraneous comma between "authorization code" and "is the same". Should be "... the authorization server MUST ensure that the redirection URI used to obtain the authorization code is the same as the redirection URI provided ..."
Last sentence should be reworded; suggest "The authorization server MUST require public clients and SHOULD require confidential clients to register their redirection URIs. If a redirection URI is provided in the authorization request, the authorization server MUST validate the URI received against the registered value."

10.14, first sentence. Reads awkwardly and should be reworded; suggest "A code injection attack occurs when an unsanitized input or otherwise external variable is used to modify application logic."

11.1, 11.2, 11.3, 11.4: second to last paragraph is missing "(s)" on the end of "Designated Expert" : "Decisions (or lack thereof) made by the Designated Expert can be..." should be "Decisions (or lack thereof) made by the Designated Expert(s) can be..."

11.2, second paragraph has extraneous comma after "or the token endpoint response" : "...the token endpoint request, or the token endpoint response, are registered" should be "...the token endpoint request, or the token endpoint response are registered".

11.2.1, "Parameter usage location" description should have references to the relevant sections of this spec, as 11.4.1 does.

--Amanda Anganes
The MITRE Corporation

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 20 Sep 2011 13:19:27 -0700

Thanks.

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf
> Of Anganes, Amanda L
> Sent: Monday, September 19, 2011 8:23 AM
> To: [email-masked]
> Subject: [OAUTH-WG] OAuth 2.0 v21 Nits and Typos
> 
> 1.2.3, second paragraph: "When issuing an implicit grant, the authorization
> server does not authenticate the client and in some cases, the client identity
> can be verified..." should be "When issuing an implicit grant, the authorization
> server does not authenticate the client. In some cases, the client identity can
> be verified..."
>
> 1.5, first paragraph. Last sentence should be changed to "Issuing a refresh
> token is optional. If an authorization server issues a refresh token, it is
> included when issuing an access token."
>
> 2.1, definition of native applications: "On the other hand, dynamically issued
> credentials such as access tokens or refresh tokens, can receive an
> acceptable level of protection" should be "On the other hand, dynamically
> issued credentials such as access tokens or refresh tokens can receive an
> acceptable level of protection" (final comma is unnecessary).
>
> 3.1, second paragraph. Add a comma after "beyond the scope of this
> specification", so it reads "The means through which the client obtains the
> location of the authorization endpoint are beyond the scope of this
> specification, but the location is typically provided in the service
> documentation".
 >
> 3.2.1, first sentence. Unnecessary comma between "requirements" and
> "MUST"; should read "Confidential clients, clients issued client credentials, or
> clients assigned other authentication requirements MUST authenticate..."
>
> 4.1, section (E): last sentence is missing a subject. "If valid, responds back
> with an..." should read "If valid, the authorization server responds back with
> an..."
>
> 4.1.2 and 4.1.2.1, also 4.2.2 and 4.2.2.1, state description: last sentence is
> missing a MUST. Should read "REQUIRED if the state parameter was present
> in the client authorization request. The state parameter MUST be set to the
> exact value received from the client."
>
> 4.1.3, redirect_uri description: Change "REQUIRED, if the redirect_uri
> parameter was included in the authorization request described in Section
> 4.1.1, and their values MUST be identical" to "REQUIRED, if the redirect_uri
> parameter was included in the authorization request as described in Section
> 4.1.1. If included, the two values MUST be identical".
>
> 4.1.3, final paragraph ("The authorization server MUST: ..."). Is any additional
> normative language required for lists such as this in order to specify that the
> AS must do ALL of the items in the list? Similar MUST lists appear elsewhere
> throughout the rest of the document.

The entire list is required.

> Also, final bullet should be reworded; suggest "ensure that the redirect_uri
> parameter is present if the redirect_uri parameter was included in the initial
> authorization request as described in Section 4.1.1, and if included ensure
> that their values are identical".
> 
> 4.2, first paragraph: clarify that implicit grants can be used only for access
> tokens by including the word "only" here: "The implicit grant type is used to
> obtain access tokens only..."

That might not be accurate with extensions.

> 4.3.2, paragraph after term parameter descriptions: "If the client type is
> confidential or was issued client credentials" should be reworded to "If the
> client type is confidential or the client was issued client credentials".
> 

This is not definitions.

> 9, final bullet following "when choosing between an external or embedded
> user-agent...": Last sentence starts "Embedded user-agent educate..." but
> should be "Embedded user-agents educate..."
> 
> 10.2, second paragraph: last sentence is a fragment. Reword to "For
> example, the authorization server should engage the resource owner to
> assist in identify the client and its origin."
> 
> 10.5, second paragraph, first sentence: extraneous comma between
> "authorization server" and "is". Should be "...verify that the resource owner
> who granted authorization at the authorization server is the same resource
> owner..."
> 
> 10.6, last paragraph, first sentence: extraneous comma between
> "authorization code" and "is the same". Should be "... the authorization
> server MUST ensure that the redirection URI used to obtain the
> authorization code is the same as the redirection URI provided ..."
> Last sentence should be reworded; suggest "The authorization server MUST
> require public clients and SHOULD require confidential clients to register their
> redirection URIs. If a redirection URI is provided in the authorization request,
> the authorization server MUST validate the URI received against the
> registered value."
> 
> 10.14, first sentence. Reads awkwardly and should be reworded; suggest "A
> code injection attack occurs when an unsanitized input or otherwise external
> variable is used to modify application logic."
> 
> 11.1, 11.2, 11.3, 11.4: second to last paragraph is missing "(s)" on the end of
> "Designated Expert" : "Decisions (or lack thereof) made by the Designated
> Expert can be..." should be "Decisions (or lack thereof) made by the
> Designated Expert(s) can be..."
> 
> 11.2, second paragraph has extraneous comma after "or the token endpoint
> response" : "...the token endpoint request, or the token endpoint response,
> are registered" should be "...the token endpoint request, or the token
> endpoint response are registered".
> 
> 11.2.1, "Parameter usage location" description should have references to the
> relevant sections of this spec, as 11.4.1 does.

No similar references available.

EHL