github/developer.github.com — pull request #204 by technoweenie (2013-01-31 18:03:48+00:00)
Title: remove mention of state from oauth step 2

I think our docs are incorrect with how the state attribute is described.

> The client MUST implement CSRF protection for its redirection URI. This is typically accomplished by requiring any request sent to the redirection URI endpoint to include a value that binds the request to the user-agent's authenticated state (e.g. a hash of the session cookie used to authenticate the user-agent). The client SHOULD utilize the "state" request parameter to deliver this value to the authorization server when making an authorization request.
>
> Once authorization has been obtained from the end-user, the authorization server redirects the end-user's user-agent back to the client with the required binding value contained in the "state" parameter. The binding value enables the client to verify the validity of the request by matching the binding value to the user-agent's authenticated state. The binding value used for CSRF protection MUST contain a non-guessable value (as described in Section 10.10), and the user-agent's authenticated state (e.g. session cookie, HTML5 local storage) MUST be kept in a location accessible only to the client and the user-agent (i.e., protected by same-origin policy).

[OAuth2 draft](http://tools.ietf.org/html/draft-ietf-oauth-v2-26#section-10.12).

This [StackOverflow answer](http://stackoverflow.com/questions/11071482/oauth2-0-server-stack-how-to-use-state-to-prevent-csrf-for-draft2-0-v20) writes it a little more clearly:

> So, before the client application kicks off the OAuth flow by redirecting the user to the provider, the client application creates a random state value and typically store it in a server-side session. Then, as the user completes the OAuth flow, you check to make sure state value matches the value stored in the user's server-side session-- as that indicates the user had initiated the OAuth flow.

[Google's OAuth 2.0 docs](https://developers.google.com/accounts/docs/OAuth2Login) describes state like so:

> This optional parameter indicates any state which may be useful to your application upon receipt of the response. The Google Authorization Server roundtrips this parameter, so your application receives the same value it sent. Possible uses include redirecting the user to the correct resource in your site, nonces, and cross-site-request-forgery mitigations.

According to this, we are doing the correct thing with the state parameter, and it's our documentation that is incorrect. We are simply passing it through if given, so that 3rd party sites can do the optional (but encouraged) state validation on their own.

/cc @github/api @github/security