Grape: API Authentication w/ Devise

Now that we have dealt with exceptions in our API we need to provide various methods of authentication. We’re going to be talking grape and devise.

There’re several scenarios and issues to consider.

We want some public APIs not to require authentication or registration at all. In our case this is only ping, the idea being that an absolute minimum set of code runs underneath.
We want public APIs that require the caller to register an application. This gives us some ability to do accounting as well as to block a misbehaving application in the wild.
We want users to be able to login via OAuth2 and we’d like to distinguish users between administrators and other types of users.
When a user is logged into the website with a form, we’d like to allow browsing and exercising the API without having to do OAuth.

Here’s what we did. It’s far from ideal, please comment and suggest ways to move forward, especially if you think something belongs in Grape or Devise proper.

No Authentication

No authentication is easy. We don’t do anything.

get "ping" do
  "pong"
end

A User Logged in with a Form

A previously logged in user is authenticated with Devise (based on Warden). There’s nothing special to do for the API except to insert an authenticated_user method in those APIs that require it.

get "me" do
  authenticated_user
  current_user.as_json
end

The authenticated_user method uses warden.

def authenticated
  if warden.authenticated?
    return true
  else
    error!('401 Unauthorized', 401)
  end
end

def current_user
  warden.user
end

Client Applications

We have a straightforward way to register ClientApplications which yield an application ID and secret key. Both are generated as random hashes. Somewhere in the registration process an administrator approves an app and gives the user who owns the app access to these values.

Access Grants

Before we hookup user authentication, note that we have multiple authentication schemes that yield some kind of access. We can all it an AccessGrant. We want the grant to expire. We’ll store the grant in the back-end so that we can check the grant after it has been handed out. A future version may improve on this by signing and serializing the grant to the client, therefore avoiding the database hit.

class AccessGrant
  include Mongoid::Document
  include Mongoid::Timestamps

  field :code, :type => String
  field :access_token, :type => String
  field :refresh_token, :type => String
  field :access_token_expires_at, :type => Time

  referenced_in :user
  referenced_in :application, :class_name => "ClientApplication"

  def self.find_access(access_token)
    where(:access_token => access_token).
      any_of(
             {:access_token_expires_at => nil},
             {:access_token_expires_at.gt => Time.now}).first
  end

  before_create :gen_tokens

  def self.prune!
    where(:created_at.lt => 3.days.ago).delete_all
  end

  def self.authenticate(code, application_id)
    where(:code => code, :application_id => application_id).first
  end

  def start_expiry_period!
    self.update_attribute(:access_token_expires_at, 2.days.from_now)
  end

  def redirect_uri_for(redirect_uri)
    if redirect_uri =~ /\?/
      redirect_uri + "&code=#{code}&response_type=code"
    else
      redirect_uri + "?code=#{code}&response_type=code"
    end
  end

  protected

  def gen_tokens
    self.code, self.access_token, self.refresh_token = SecureRandom.hex(16), SecureRandom.hex(16), SecureRandom.hex(16)
  end

end

XApp

Our simpler scenario includes registered applications making calls without users being logged in. @sarcilav labeled this XApp.

To get an XApp token one would call the xapp_token API method with the client ID and secret. The authenticated method will now look for an xapp_token parameter.

get "xapp_token" do
  application = ClientApplication.authenticate(params[:client_id], params[:client_secret])
  error!("401 Unauthorized", 401) if application.nil?
  AccessGrant.prune!
  access_grant = AccessGrant.create(:application => application)
  error!("401 Unauthorized", 401) if access_grant.new_record?
  access_grant.start_expiry_period!
  {
      :xapp_token => access_grant.access_token,
      :refresh_token => access_grant.refresh_token,
      :expires_in => access_grant.access_token_expires_at
  }
end

def authenticated
  if warden.authenticated?
    return true
  elsif params[:xapp_token] and
      AccessGrant.find_access(params[:xapp_token])
    return true
  else
    error!('401 Unauthorized', 401)
  end
end

This is an improvement over schemes like BASIC authentication. We’re only sending actual credentials (client ID and secret) once during authentication, which would happen under SSL. If subsequent unprotected traffic were to be logged and the logs stolen, the XApp token would have a limited value since it expires.

We found that the XApp authentication model is ideal for client apps that don’t require user registration.

OAuth2

OAuth2 is the preferred mechanism for authenticating users. It takes the login out of the hands of the client application – login happens in an external browser, therefore offering the best protection to the user.

Let’s start from the the tail-end. Assume the client application has gotten some kind of _access_token _and can pass it to each API. This should allow us to lookup an access grant and eventually a user. Let’s add this to the User model.

def self.find_for_token_authentication(params = {})
  access = AccessGrant.find_access(params["access_token"])
  return access.user if access
end

How does a user obtain such a token with OAuth2? We’ll need two routes.

match '/oauth2/authorize'    => 'oauth#authorize',    :via => [:get, :post]
match '/oauth2/access_token' => 'oauth#access_token', :via => [:get, :post]

OAuth2 starts by redirecting users to /oauth2/authorize?client_id=[client id]&redirect_uri=[redirect url]&response_type=code. This should render a login page. If the user chooses to login, he will be redirected back to the redirect url specified with the authorization code. The application should make a request to /oauth2/access_token?client_id=[client id]&client_secret=[client secret]&redirect_uri=[redirect url]&grant_type=[authorization code]&code=code which will return the JSON { "access_token": [access token], "refresh_token": [refresh token], "expires_in": "yyyy-mm-ddThh:mm:ss TZ" }.

class OauthController < ApplicationController

  before_filter :authenticate_user!, :except => [:access_token]
  skip_before_filter :verify_authenticity_token, :only => [:access_token]

  def authorize
    AccessGrant.prune!
    access_grant = current_user.access_grants.create(:application => get_application)
    redirect_to access_grant.redirect_uri_for(params[:redirect_uri])
  end

  def access_token
    application = ClientApplication.authenticate(params[:client_id], params[:client_secret])
    if application.nil?
      render :json => {:error => "Could not find application"}
      return
    end
    access_grant = AccessGrant.authenticate(params[:code], application.id)
    if access_grant.nil?
      render :json => {:error => "Could not authenticate access code"}
      return
    end
    access_grant.start_expiry_period!
    render :json => {
        :access_token => access_grant.access_token,
        :refresh_token => access_grant.refresh_token,
        :expires_in => access_grant.access_token_expires_at
    }
  end

  protected

  def get_application
    @application ||= ClientApplication.where(:app_id => params[:client_id]).first
  end

end

Finally, we can rewrite our API authenticate method appropriately and implement current_user. The latter can also tell us whether a user is an administrator or not.

helpers do
  def warden
    env['warden']
  end
  def authenticated
    if warden.authenticated?
      return true
    elsif params[:access_token] and
        User.find_for_token_authentication("access_token" => params[:access_token])
      return true
    elsif params[:xapp_token] and
        AccessGrant.find_access(params[:xapp_token])
      return true
    else
      error!('401 Unauthorized', 401)
    end
  end
  def current_user
    warden.user || User.find_for_token_authentication("access_token" => params[:access_token])
  end
  def is_admin?
    current_user && current_user.is_admin?
  end
  # returns 401 if there's no current user
  def authenticated_user
    authenticated
    error!('401 Unauthorized', 401) unless current_user
  end
  # returns 401 if not authenticated as admin
  def authenticated_admin
    authenticated
    error!('401 Unauthorized', 401) unless is_admin?
  end
end

This is a little thick. Maybe someone can take a stab at sinking some of this into Grape as authentication middleware?

Daniel Doubrovkine

Grape: API Authentication w/ Devise rails | ruby | security