Hire a door keeper for your Rails app

Implementing Oauth2 Authentication with doorkeeper

Posted on May 20, 2015

Oauth 2.0 is a very common protocol to implement the authorization of web, desktop or mobile applications and third-party (e.g., Facebook, Google, ...) or personal providers.

Suppose you're developing an API, like my previous post =], and want your mobile app to access it. Notice that both API and app are in-site systems but the API must be publicly accessible.

Oauth3 is perfect for that! You just need be an Oauth 2 provider and have a access policy in your resource. Basically, you need to be available 24x7 to check the credentials of anyone at your door and decide who can access your API's resources. In summary, what you need is a trustful door keeper!

Hiring the door keeper

Doorkeeper gem is an awesome alternative for implementing an Oauth 2.0 provider in Rails. After adding the gem to your project, you just have to install it:

$ rails generate doorkeeper:install

This will generate a doorkeeper file: config/initializers/doorkeeper.rb. In this file is possible to define different types of resource authorization, access token expiration time, and so on.

Since we want to connect our mobile app and our API, we don't need external providers. A good strategy is to implement an authorization based on the validation of the client credentials.

Basically, our server receives user's login and password and returns an access token (if the credentials are valid). Then, the client can access our API by passing the token in the header of next HTTP requests. To implement the credential authorization using doorkeeper, add this into config/initializers/doorkeeper.rb file:

Doorkeeper.configure do
  resource_owner_from_credentials do |routes|
    u = User.find_for_database_authentication(:email => params[:username])
    u if u && u.valid_password?(params[:password])
  end
end

After this block, in the same file, you also have to add:

Doorkeeper.configuration.token_grant_types << "password"

To finish the installation, you have set up your database to keep Oauth 2.0 models (tokens, applications, ...)

$ rails generate doorkeeper:migration && rake db:migrate

After running this command, you finish the doorkeeper configuration. Your database is ready to keep doorkeeper models. Some routes are also added to your project such as POST /oauth/token.

Through this route, the client must pass the credentials a JSON object:

{
  grant_type: "password",
  username: "john.snow@mail.com",
  password: "123"
}

As a response, a client receives an access token that must be pass in the header of the next HTTP requests:

 Authorization Bearer adf4c4518fdab788ea68be4c161794f0f9c470fa606aaa8b768deda14da19307

Don't forget that you must provide a SSL connection to traffic user's credentials!!! Other routes and authentication/authorization strategies are well documented at the doorkeeper github project.

Letting your resources protected

After setting up your API to use doorkeeper it's time to set which resources demands Oauth 2.0 authorization. This is very straightforward:

class Api::UsersController < ApplicationController
  before_action :doorkeeper_authorize!
end

The code above is enough to protect this resource from non-authorized requests. This means that all API clients must provide a valid access token to access any User's action.

Although we protected our API from non-authorized users, you have to define which user can access what and when. This task is very particular to each business so it falls beyond the responsibility of an Oauth provider.

Basically, an access policy must verify if the access token owner is also an owner or can access a resource. With doorkepper is easy to retrieve the access token owner by calling doorkeeper_token.resource_owner_id anywhere in your code.

Having the owner id, we can easily retrieving more user info and release or block the resources access. There are good gems to implement authorization policies such as pundit.

That's it! This post didn't cover all doorkeeper features but I really hope to help you to get started in Oauth 2.0 + Rails. I highly recommend to read the official doorkeeper documentation. Thanks for reading !!!