This short post serves as an additional resource to GitHub’s guide on how to use OAuth for their API. The official guide gives a more generic explanation of the authentication process, rather than describing a single library. That is fine, however, in case you’re using the official Octokit toolkit to access the API, you can make things even simpler for yourself.
I try not to repeat too many things here, so please refer to the original guide in case something doesn’t make sense. I’ll be using Sinatra as the backend framework of choice, just as the original guide does, but you should be able to do the same with any other toolkit as well.
The Stages of Authentication
The process of OAuth authentication can be broken down to three stages. First, you need to redirect the user to GitHub to request access. When the user authorises your request, GitHub will redirect them to your callback URL that you need to set up when you register your app. The redirection will come with a code parameter. You will be required to send this back to GitHub along with your application’s id and secret. If all three are correct, GitHub will issue an access token that you can use to perform actions on behalf of the user. What you are allowed to do is limited by the scope for which the token was issued.
That isn’t too difficult, right? Basically, the only tricky part is constructing the HTTP requests and parsing the responses. Now, there is where Octokit can be useful. Let’s take it stage by stage.
This is simple, all you need is to paste your application’s client_id and the requested scopes to the URL and redirect the user to it. Octokit has a handy method that will form the correct URL for you automatically.
The user approved your application with Github and is now being sent back from there to your site. For this, Github will use the callback you defined when registering the app and redirect everyone there with a specific code. Now you need to authenticate yourself as the application. You are required to respond with your application’s credentials. Again, there’s a very convenient function in Octokit, so you don’t need to do this by hand.
If your credentials were correct, you will receive the access token you need to make API calls on behalf of the user in question. Here, we’ll just store it in the session and redirect back to the main application.
3. Access Token
It is time to initialise the API client with the token we got from the previous step. But what if the user managed to revoke in the meantime? It is important to check whether the token is still valid.
And in case the token was all right, we can finally start to make calls on behalf of the user.
The Complete Source
Here is the full source of the example above that I tested.
To use the above app, you’ll also need to have the following
views/email.erb template prepared. This is for the page that will Sinatra display when successfully authenticated.
All you need to do is to run the application using the
ruby app.rb command and point your favourite browser to
localhost:4567. Also, don’t forget to set the
GH_APP_SECRET_ID environment variables with you application’s credentials.
That’s it, you need about 60 lines of code and you’re done. It is that easy to setup a Ruby application to use the Github API. You’d normally use Octokit to make the API calls, but you can use the same library to avoid much of the boilerplate that is required during the OAuth process and make it even simpler for yourself.