Doorkeeper is a gem that makes it easy to introduce OAuth 2 provider functionality to your Rails or Grape application.
Please check the documentation for the version of doorkeeper you are using in: https://github.com/doorkeeper-gem/doorkeeper/releases
- See the wiki
- For general questions, please post in Stack Overflow
- Installation
- Configuration
- Protecting resources with OAuth (a.k.a your API endpoint)
- Other customizations
- Upgrading
- Development
- Contributing
- Other resources
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.
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, add the following line to the migration file
for each table that includes a resource_owner_id column:
add_foreign_key:table_name,:users,column: :resource_owner_idThen run migrations:
rake db:migrateSee doorkeeper-mongodb project for Mongoid and MongoMapper support. Follow along the implementation in that repository to extend doorkeeper with other ORMs.
If you are using Sequel gem then you can add doorkeeper-sequel extension to your project. Follow configuration instructions for setting up the necessary Doorkeeper ORM.
The installation script will also automatically add the Doorkeeper routes into your app, like this:
Rails.application.routes.drawdouse_doorkeeper# your routesendThis 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.
You need to configure Doorkeeper in order to provide resource_owner model
and authentication block in config/initializers/doorkeeper.rb:
Doorkeeper.configuredoresource_owner_authenticatordoUser.find_by_id(session[:current_user_id]) || redirect_to(login_url)endendThis 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.
See language files in the I18n repository.
To protect your API with OAuth, you just need to setup before_actions
specifying the actions you want to protect. For example:
classApi::V1::ProductsController < Api::V1::ApiControllerbefore_action:doorkeeper_authorize!# Require access token for all actions# your actionsendYou can pass any option before_action accepts, such as if, only,
except, and others.
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'moduleAPImoduleV1classUsers < Grape::APIhelpersDoorkeeper::Grape::Helpersbeforedodoorkeeper_authorize!end# ...endendendYou 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.
moduleConstraintclassAuthenticateddefmatches?(request)token=Doorkeeper.authenticate(request)token && token.accessible?endendendFor more information about integration and other integrations, check out the related wiki page.
You can also require the access token to have specific scopes in certain actions:
First configure the scopes in initializers/doorkeeper.rb
Doorkeeper.configuredodefault_scopes:public# if no scope was requested, this will be the defaultoptional_scopes:admin,:writeendAnd in your controllers:
classApi::V1::ProductsController < Api::V1::ApiControllerbefore_action->{doorkeeper_authorize!:public},only: :indexbefore_actiononly: [:create,:update,:destroy]dodoorkeeper_authorize!:admin,:writeendendPlease note that there is a logical OR between multiple required scopes. In the
above example, doorkeeper_authorize! :admin, :write means that the access
token is required to have either :admin scope or :write scope, but does not
need have both of them.
If you want to require the access token to have multiple scopes at the same
time, use multiple doorkeeper_authorize!, for example:
classApi::V1::ProductsController < Api::V1::ApiControllerbefore_action->{doorkeeper_authorize!:public},only: :indexbefore_actiononly: [:create,:update,:destroy]dodoorkeeper_authorize!:admindoorkeeper_authorize!:writeendendIn the above example, a client can call :create action only if its access token
has both :admin and :write scopes.
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.configuredoaccess_token_generator"Doorkeeper::JWT"endJWT token support is available with Doorkeeper-JWT.
By default Doorkeeper's main controller Doorkeeper::ApplicationController inherits from ActionController::Base.
You may want to use your own controller to inherit from, to keep Doorkeeper controllers in the same context than the rest your app:
Doorkeeper.configuredobase_controller'ApplicationController'endIf 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:
classApi::V1::CredentialsController < Api::V1::ApiControllerbefore_action:doorkeeper_authorize!respond_to:json# GET /me.jsondefmerespond_withcurrent_resource_ownerendprivate# Find the user that owns the access tokendefcurrent_resource_ownerUser.find(doorkeeper_token.resource_owner_id)ifdoorkeeper_tokenendendIn this example, we're returning the credentials (me.json) of the access
token owner.
By default, the applications list (/oauth/applications) is publicly available.
To protect the endpoint you should uncomment these lines:
# config/initializers/doorkeeper.rbDoorkeeper.configuredoadmin_authenticatordo |routes|
Admin.find_by_id(session[:admin_id]) || redirect_to(routes.new_admin_session_url)endendThe 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 all together.
For more information see the page
in the wiki.
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.
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.
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.
You can find everything about doorkeeper in our wiki here.
Check out this screencast from railscasts.com: #353 OAuth with Doorkeeper
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!
- The OAuth 2.0 Authorization Framework
- OAuth 2.0 Threat Model and Security Considerations
- OAuth 2.0 Token Revocation
MIT License. Copyright 2011 Applicake.