Doorkeeper - awesome oauth provider for your Rails app.

Doorkeeper is a gem that makes it easy to introduce OAuth 2 provider functionality to your Rails or Grape application.

Documentation valid for master branch

Please check the documentation for the version of doorkeeper you are using in: https://github.com/doorkeeper-gem/doorkeeper/releases

Table of Contents

• Useful links
• Installation
• Configuration
  • Active Record
  • Other ORMs
  • Routes
  • Authenticating
  • Internationalization (I18n)
• Protecting resources with OAuth (a.k.a your API endpoint)
  • Protect your API with OAuth when using Grape
  • Route Constraints and other integrations
  • Access Token Scopes
  • Custom Access Token Generator
  • Authenticated resource owner
  • Applications list
• Other customizations
• Upgrading
• Development
• Contributing
• Other resources
  • Wiki
  • Screencast
  • Client applications
  • Contributors
  • IETF Standards
  • License

Useful links

• For documentation, please check out our wiki
• For general questions, please post it in stack overflow

Installation

Put this in your Gemfile:

gem 'doorkeeper'

Run the installation generator with:

rails generate doorkeeper:install

This will install the doorkeeper initializer into config/initializers/doorkeeper.rb.

Configuration

Active Record

By default doorkeeper is configured to use active record, so to start you have to generate the migration tables:

rails generate doorkeeper:migration

You may want to add foreign keys to your migration. For example, if you plan on using User as the resource owner, change the line in the migration file:

t.integer    :resource_owner_id, null: false

to:

t.references :user, foreign_key: true, null: false

Then run migrations:

rake db:migrate

Other ORMs

See doorkeeper-mongodb project for mongoid and mongomapper support. Follow along the implementation in that repository to extend doorkeeper with other ORMs.

Routes

The installation script will also automatically add the Doorkeeper routes into your app, like this:

Rails.application.routes.draw do
  use_doorkeeper
  # your routes
end

This will mount following routes:

GET       /oauth/authorize/:code
GET       /oauth/authorize
POST      /oauth/authorize
DELETE    /oauth/authorize
POST      /oauth/token
POST      /oauth/revoke
resources /oauth/applications
GET       /oauth/authorized_applications
DELETE    /oauth/authorized_applications/:id
GET       /oauth/token/info

For more information on how to customize routes, check out this page on the wiki.

Authenticating

You need to configure Doorkeeper in order to provide resource_owner model and authentication block in config/initializers/doorkeeper.rb:

Doorkeeper.configure do
  resource_owner_authenticator do
    User.find_by_id(session[:current_user_id]) || redirect_to(login_url)
  end
end

This code is run in the context of your application so you have access to your models, session or routes helpers. However, since this code is not run in the context of your application's ApplicationController it doesn't have access to the methods defined over there.

You may want to check other ways of authentication here.

Internationalization (I18n)

See language files in the I18n repository.

Protecting resources with OAuth (a.k.a your API endpoint)

To protect your API with OAuth, you just need to setup before_actions specifying the actions you want to protect. For example:

class Api::V1::ProductsController < Api::V1::ApiController
  before_action :doorkeeper_authorize! # Require access token for all actions

  # your actions
end

You can pass any option before_action accepts, such as if, only, except, and others.

Protect your API with OAuth when using Grape

As of PR 567 doorkeeper has helpers for Grape. One of them is doorkeeper_authorize! and can be used in a similar way as an example above. Note that you have to use require 'doorkeeper/grape/helpers' and helpers Doorkeeper::Grape::Helpers.

For more information about integration with Grape see the Wiki.

require 'doorkeeper/grape/helpers'

module API
  module V1
    class Users < Grape::API
      helpers Doorkeeper::Grape::Helpers

      before do
        doorkeeper_authorize!
      end

      # ...
    end
  end
end

Route Constraints and other integrations

You can leverage the Doorkeeper.authenticate facade to easily extract a Doorkeeper::OAuth::Token based on the current request. You can then ensure that token is still good, find its associated #resource_owner_id, etc.

module Constraint
  class Authenticated

    def matches?(request)
      token = Doorkeeper.authenticate(request)
      token && token.accessible?
    end

  end
end

For more information about integration and other integrations, check out the related wiki page.

Access Token Scopes

You can also require the access token to have specific scopes in certain actions:

First configure the scopes in initializers/doorkeeper.rb

Doorkeeper.configure do
  default_scopes :public # if no scope was requested, this will be the default
  optional_scopes :admin, :write
end

And in your controllers:

class Api::V1::ProductsController < Api::V1::ApiController
  before_action -> { doorkeeper_authorize! :public }, only: :index
  before_action only: [:create, :update, :destroy] do
    doorkeeper_authorize! :admin, :write
  end
end

Please note that there is a logical OR between multiple required scopes. In above example, doorkeeper_authorize! :admin, :write means that the access token is required to have either :admin scope or :write scope, but not need have both of them.

If want to require the access token to have multiple scopes at the same time, use multiple doorkeeper_authorize!, for example:

class Api::V1::ProductsController < Api::V1::ApiController
  before_action -> { doorkeeper_authorize! :public }, only: :index
  before_action only: [:create, :update, :destroy] do
    doorkeeper_authorize! :admin
    doorkeeper_authorize! :write
  end
end

In above example, a client can call :create action only if its access token have both :admin and :write scopes.

Custom Access Token Generator

By default a 128 bit access token will be generated. If you require a custom token, such as JWT, specify an object that responds to .generate(options = {}) and returns a string to be used as the token.

Doorkeeper.configure do
  access_token_generator "Doorkeeper::JWT"
end

JWT token support is available with Doorkeeper-JWT.

Authenticated resource owner

If you want to return data based on the current resource owner, in other words, the access token owner, you may want to define a method in your controller that returns the resource owner instance:

class Api::V1::CredentialsController < Api::V1::ApiController
  before_action :doorkeeper_authorize!
  respond_to    :json

  # GET /me.json
  def me
    respond_with current_resource_owner
  end

  private

  # Find the user that owns the access token
  def current_resource_owner
    User.find(doorkeeper_token.resource_owner_id) if doorkeeper_token
  end
end

In this example, we're returning the credentials (me.json) of the access token owner.

Applications list

By default, the applications list (/oauth/applications) is public available. To protect the endpoint you should uncomment these lines:

# config/initializers/doorkeeper.rb
Doorkeeper.configure do
  admin_authenticator do |routes|
    Admin.find_by_id(session[:admin_id]) || redirect_to(routes.new_admin_session_url)
  end
end

The logic is the same as the resource_owner_authenticator block. Note: since the application list is just a scaffold, it's recommended to either customize the controller used by the list or skip the controller at all. For more information see the page in the wiki.

Other customizations

• Associate users to OAuth applications (ownership)
• CORS - Cross Origin Resource Sharing

Upgrading

If you want to upgrade doorkeeper to a new version, check out the upgrading notes and take a look at the changelog.

Doorkeeper follows semantic versioning.

Development

To run the local engine server:

bundle install
bundle exec rails server

By default, it uses the latest Rails version with ActiveRecord. To run the tests with a specific ORM and Rails version:

rails=4.2.0 orm=active_record bundle exec rake

Or you might prefer to run script/run_all to integrate against all ORMs.

Contributing

Want to contribute and don't know where to start? Check out features we're missing, create example apps, integrate the gem with your app and let us know!

Also, check out our contributing guidelines page.

Other resources

Wiki

You can find everything about doorkeeper in our wiki here.

Screencast

Check out this screencast from railscasts.com: #353 OAuth with Doorkeeper

Client applications

After you set up the provider, you may want to create a client application to test the integration. Check out these client examples in our wiki or follow this tutorial here.

Contributors

Thanks to all our awesome contributors!

IETF Standards

• The OAuth 2.0 Authorization Framework
• OAuth 2.0 Threat Model and Security Considerations
• OAuth 2.0 Token Revocation

License

MIT License. Copyright 2011 Applicake.