doorkeeper 0 rspec travis-ci ruby Rubygems

Doorkeeper is an OAuth 2 provider for Rails.

Doorkeeper - awesome oauth provider for your Rails app.

Build Status Dependency Status Code Climate Gem Version

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

Documentation valid for master branch

Please check the documentation for the version of doorkeeper you are using in:

Table of Contents

Useful links

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


  • Ruby >1.9.3
  • Rails >3.1
  • ORM ActiveRecord, Mongoid, MongoMapper


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.


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

Don’t forget to run the migration with:

rake db:migrate

Mongoid / MongoMapper

Doorkeeper currently supports MongoMapper, Mongoid 2 and 3. To start using it, you have to set the orm configuration:

Doorkeeper.configure do
  orm :mongoid2 # or :mongoid3, :mongoid4, :mongo_mapper

Mongoid indexes

Make sure you create indexes for doorkeeper models. You can do this either by running rake db:mongoid:create_indexes or (if you’re using Mongoid 2) by adding autocreate_indexes: true to your config/mongoid.yml

MongoMapper indexes

Generate the db/indexes.rb file and create indexes for the doorkeeper models:

rails generate doorkeeper:mongo_mapper:indexes
rake db:index


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

Rails.application.routes.draw do
  # your routes

This will mount following routes:

GET       /oauth/authorize/:code
GET       /oauth/authorize
POST      /oauth/authorize
PUT       /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.


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

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

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.

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

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

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?


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

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

For a more detailed explanation about scopes usage, check out the related page in the wiki.

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


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

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)

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


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


To run the local engine server:

rails=3.2.8 orm=active_record bundle install
rails=3.2.8 orm=active_record bundle exec rails server

By default, it uses the latest Rails version with ActiveRecord. To run the

rails=3.2.8 orm=active_record bundle exec rake “`

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


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


You can find everything about doorkeeper in our wiki here.

Live demo

Check out this live demo hosted on heroku. For more demos check out the wiki.


Check out this screencast from #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.


Thanks to all our awesome contributors!


MIT License. Copyright 2011 Applicake.

Related Repositories



Doorkeeper is an OAuth 2 provider for Rails. ...



An example OAuth 2 provider application using the Doorkeeper gem, Rails and Devise ...



JWT Token support for Doorkeeper ...



Integration Grape with Doorkeeper ...



Assertion grant extension for Doorkeeper. Born from: IN NEED OF MAINTAINER. ...

Top Contributors

felipeelias tute piotrj jasl petergoldstein jaimeiniesta simonbnrd amkirwan martin-ifg carols10cents stas kenn kris-at-tout carvil edpaget epchris miyagawa ianunruh ryanjones idlecool chitsaou antek-drzewiecki asoules amatsuda antekpiechnik john-griffin stevenharman towerhe mtparet macb


-   v2.0.1 zip tar
-   v2.0.0 zip tar
-   v2.0.0.rc3 zip tar
-   v2.0.0.rc2 zip tar
-   v2.0.0.rc1 zip tar
-   v2.0.0.alpha1 zip tar
-   v1.4.1 zip tar
-   v1.4.0 zip tar
-   v1.3.1 zip tar
-   v1.3.0 zip tar
-   v1.2.0 zip tar
-   v1.1.0 zip tar
-   v1.0.0 zip tar
-   v1.0.0.rc2 zip tar
-   v1.0.0.rc1 zip tar
-   v0.7.4 zip tar
-   v0.7.3 zip tar
-   v0.7.2 zip tar
-   v0.7.1 zip tar
-   v0.7.0 zip tar
-   v0.6.7 zip tar
-   v0.6.6 zip tar
-   v0.6.5 zip tar
-   v0.6.4 zip tar
-   v0.6.3 zip tar
-   v0.6.2 zip tar
-   v0.6.1 zip tar
-   v0.6.0 zip tar
-   v0.6.0.rc1 zip tar
-   v0.5.0 zip tar