Installation

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

Configuration

ORM

Active Record

By default doorkeeper is configured to use Active Record, so to start you have
to generate the migration tables (supports Rails >= 5 migrations versioning):

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_id

If you want to enable PKCE flow for mobile apps, you need to generate another
migration:

rails generate doorkeeper:pkce

Then run migrations:

rake db:migrate

Ensure to use non-confidential apps for pkce. PKCE is created, because
you cannot trust its apps' secret. So whatever app needs pkce: it means, it cannot
be a confidential app by design.

Remember to add associations to your model so the related records are deleted.
If you don't do this an ActiveRecord::InvalidForeignKey-error will be raised
when you try to destroy a model with related access grants or access tokens.

Couchbase

API mode

By default Doorkeeper uses full Rails stack to provide all the OAuth 2 functionality
with additional features like administration area for managing applications. By the
way, starting from Doorkeeper 5 you can use API mode for your API only Rails 5 applications.
All you need is just to configure the gem to work in desired mode:

Doorkeeper.configure do# ...
api_only
end

Keep in mind, that in this mode you will not be able to access Applications or
Authorized Applications controllers because they will be skipped. CSRF protections (which are otherwise enabled) will be skipped, and all the redirects will be returned as JSON response with corresponding locations.

Routes

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

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.

Internationalization (I18n)

Customizing errors

If you don't want to use default Doorkeeper error responses you can raise and rescue it's
exceptions. All you need is to set configuration option handle_auth_errors to :raise.
In this case Doorkeeper will raise Doorkeeper::Errors::TokenForbidden,
Doorkeeper::Errors::TokenExpired, Doorkeeper::Errors::TokenRevoked or other exceptions
that you need to care about.

Rake Tasks

If you are using rake, you can load rake tasks provided by this gem, by adding
the following line to your Rakefile:

Doorkeeper::Rake.load_tasks

Cleaning up

By default Doorkeeper is retaining expired and revoked access tokens and grants.
This allows to keep an audit log of those records, but it also leads to the
corresponding tables to grow large over the lifetime of your application.

If you are concerned about those tables growing too large,
you can regularly run the following rake task to remove stale entries
from the database:

rake doorkeeper:db:cleanup

Note that this will remove tokens that are expired according to the configured TTL
in Doorkeeper.configuration.access_token_expires_in. The specific expires_in
value of each access token is not considered. The same is true for access
grants.

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

Ruby on Rails controllers

To protect your controllers (usual one or ActionController::API) with OAuth,
you just need to setup before_actions specifying the actions you want to
protect. For example:

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

Grape endpoints

Starting from version 2.2 Doorkeeper provides helpers for the
Grape framework >= 0.10. One of them is doorkeeper_authorize! that
can be used in a similar way as an example above to protect your API
with OAuth. Note that you have to use require 'doorkeeper/grape/helpers'
and helpers Doorkeeper::Grape::Helpers in your Grape API class.

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.

Please 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 to 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:

In the above example, a client can call :create action only if its access token
has 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.

Custom Base Controller

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.configure do
base_controller 'ApplicationController'end

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:

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 publicly available (before 5.0 release).
Starting from Doorkeeper 5.0 it returns 403 Forbidden if admin_authenticator option is not configured
by developers.

To change the protection rules of this endpoint you should uncomment these lines:

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 all together.
For more information see the page
in the wiki.

By default, everybody can create application with any scopes. However,
you can enforce users to create applications only with configured scopes
(default_scopes and optional_scopes from the Doorkeeper initializer):

Other customizations

Testing

You can use Doorkeeper models in your application test suite. Note that starting from
Doorkeeper 4.3.0 it uses ActiveSupport lazy loading hooks
to load models. There are known issue
with the factory_bot_rails gem (it executes factories building before ActiveRecord::Base
is initialized using hooks in gem railtie, so you can catch a uninitialized constant error).
It is recommended to use pure factory_bot gem to solve this problem.