This submodule implements additional Goodreads API calls that require OAuth to access a specific Goodreads user’s information.

OAuth can be a very intimidating addition to a module. It needn’t be.

In its simplest, OAuth is a way for your website (a Consumer) to get, or in some changes change, more/less private information from another website (a Provider) on behalf of a User, without that User giving you their username or password for the Provider website.

The process OAuth uses to accomplish that is byzantinely complex internally, but for the average user of this module you won’t have to know a whole lot about how it accomplishes the magic. The process uses the same developer key and developer secret you need for the base Goodreads module, so there isn’t any special configuration required.

When you enable this submodule, each user will get a new capability to link their Goodreads account to your website, once linked they won’t have to ever answer that question again. You’ve seen OAuth in action on Facebook, Twitter, etc when at some point you see a page on those sites that says “Authorize xyz to use your account” or “xyz wants access to your account.” For instance, when a Drupal user clicks links their account on your website to their Goodreads account, they will see something like:

Once that User allows access for your site to access their Goodreads account, the submodule stores a special access token that can be used to automatically identify your site and the fact the User has given you permission to interact with their Goodreads account.

A key point to remember is enabling the module doesn't link a user to their Goodreads account, the user must edit their profile, go to the Goodreads tab and click on the link button, then allow the Drupal site access to their Goodreads data.

In more detail, the steps required to use the Goodreads OAuth API’s are:

1. Register as a Goodreads developer at http://www.goodreads.com/api/keys. You need to be logged into Goodreads (which obviously means you need to join Goodreads). When you register, you will be given your developer key and secret. Enter these into the Goodreads module settings page. You needed to do this step to use any Goodreads API.
2. Install and enable the Goodreads OAuth module. The Goodreads OAuth module will add a tab to the user profile page to allow a user to link their Drupal account to their Goodreads account. The module also creates a link, /goodreads/user/authorize, that you can use to start the Goodreads OAuth process in other places.
3. When the link Goodreads account button or link is clicked, the module will redirect the user’s browser to the Goodreads website. That will display a page like

   for the user to Allow access.

4. Assuming the user allows access, the user's Goodreads user ID, access token and access secret are stored in the Goodreads OAuth token table for later use by any Goodreads API functions that require OAuth authorization.