Reddit as an OAuth provider for a Java backend

OAuth (2) and Java work well together, there are plenty of libraries available which handle the general case and the more specific peculiarities of the various OAuth providers. Despite solid implementations like my favourite Spring Social [1] framework the state of OAuth is at best fragmented. Not only because Spring Social is not as well documented as the rest of the Spring framework (just check how many people are having trouble getting OAuth access tokens) but mainly because every OAuth provider does it their own way.

In terms of documentation the far worst I have encountered so far is reddit’s API [2] – I write this with confidence after having connected to Weibo’s OAuth API [3]

which is mostly documented in Chinese.

I am documenting here the shortcomings of reddit’s documentation and the necessary implementation tweaks made to be able to authenticate and consume reddit’s API (2013-09-09). Although they provide some code examples, they mostly build on proprietary python libraries so most of what is documented here comes from googling, forums and digging into their python programmes.

Mandatory state parameter: The documentation implies that the “state” parameter to the authorization URL is optional (“you can pass a value…”). It is not.

Basic HTTP authentication: Requests to retrieve access tokens must be POSTed (a GET won’t do) with an HTTP Basic authentication. The documentation links to a wikipedia article [4] on HTTP Basic authentication which states that credentials can be coded into the URL, but reddit supports credentials only in the HTTP header.

grant_type: this URL parameter is necessary in order to acquire an access token and must have the value “authorization_code”. I got this from the code examples and didn’t find any other documentation for it.

Token bearer: once you do have the access token you probably want to call the API. In order to do so, the access token must be passed again as an HTTP Authorization header but with the “bearer” scheme:

headers.put(“Authorization”, “bearer “+accessToken);

Refreshing a token requires the clientId and clientSecret in both Basic HTTP auth and request parameters, also a parameter grant_type=refresh_token