doorkeeper 5.1.0.rc1 → 5.1.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5773ab2b97881fdf1bb6fa66a4e176299d58c536f354ea9e9f4f7bb6dc0dcdea
-  data.tar.gz: 69ac6937d7eb7786a8c9ac331f540ef5aa1321b7c0624a0778c7437151764569
+  metadata.gz: 4933a46b121732bd9b6cc44f53947863ab243f448224e444e6106890bb8d78ca
+  data.tar.gz: d2dd4869d2c08ab587908ab79edec49e307e8c2e73b7c54af4706620bc8fcb83
 SHA512:
-  metadata.gz: 5e4b8470847ab8e642d50d27972838c0b5181b3c97c4a25afca18861b3878e513346f7b72d5c5d6c31b5d8513d90c1e6426e0cfcfce51a06b1e04e563ae09ab0
-  data.tar.gz: 79c4363faf9a3f41bc639ee6e6ec756efbd99a96e4670e788bc4201b6f69eb992ffc95f2f56e3efbcd5645f2ed76e2c8d29f6e9807ffb6841becd31d868c6963
+  metadata.gz: dcd3f3b72d7d3cfdd783dd89eb61be9e21cfd4460a48cea0919a398e10a6aad8e6472a325c338988ad6b888167b2d5037c2e41631e9d43a4fd24532d52dd69a9
+  data.tar.gz: 6dd4f697b11faa4f3702482071fba8383c196bccc448fde8b3a1fb6ef0bf10e687a8dbc8bc3385c857a071c57816cdfc82061061029ef9acaa9ac96fea0ce193

data/.travis.yml

@@ -1,6 +1,5 @@
 language: ruby
 cache: bundler
-sudo: false
 
 rvm:
   - 2.1
@@ -8,7 +7,7 @@ rvm:
   - 2.3
   - 2.4
   - 2.5
-  - 2.6
+  - 2.6.1
   - ruby-head
 
 before_install:
@@ -21,6 +20,7 @@ gemfile:
   - gemfiles/rails_5_0.gemfile
   - gemfiles/rails_5_1.gemfile
   - gemfiles/rails_5_2.gemfile
+  - gemfiles/rails_6_0.gemfile
   - gemfiles/rails_master.gemfile
 
 matrix:
@@ -37,6 +37,14 @@ matrix:
       rvm: 2.1
     - gemfile: gemfiles/rails_5_2.gemfile
       rvm: 2.1
+    - gemfile: gemfiles/rails_6_0.gemfile
+      rvm: 2.1
+    - gemfile: gemfiles/rails_6_0.gemfile
+      rvm: 2.2
+    - gemfile: gemfiles/rails_6_0.gemfile
+      rvm: 2.3
+    - gemfile: gemfiles/rails_6_0.gemfile
+      rvm: 2.4
     - gemfile: gemfiles/rails_master.gemfile
       rvm: 2.1
     - gemfile: gemfiles/rails_master.gemfile
@@ -47,3 +55,4 @@ matrix:
       rvm: 2.4
   allow_failures:
     - gemfile: gemfiles/rails_master.gemfile
+    - rvm: ruby-head

data/Appraisals

@@ -1,18 +1,44 @@
 appraise "rails-4-2" do
   gem "rails", "~> 4.2.0"
+  gem "grape", '~> 0.16', '< 0.19.2'
+  gem "sqlite3", "~> 1.3", "< 1.4", platform: [:ruby, :mswin, :mingw, :x64_mingw]
 end
 
 appraise "rails-5-0" do
   gem "rails", "~> 5.0.0"
-  gem "rspec-rails", "~> 3.7"
+  gem "sqlite3", "~> 1.3", "< 1.4", platform: [:ruby, :mswin, :mingw, :x64_mingw]
 end
 
 appraise "rails-5-1" do
   gem "rails", "~> 5.1.0"
-  gem "rspec-rails", "~> 3.7"
+  gem "sqlite3", "~> 1.3", "< 1.4", platform: [:ruby, :mswin, :mingw, :x64_mingw]
+end
+
+appraise "rails-5-2" do
+  gem "rails", "~> 5.2.0"
+  gem "sqlite3", "~> 1.3", "< 1.4", platform: [:ruby, :mswin, :mingw, :x64_mingw]
+end
+
+appraise "rails-6-0" do
+  gem "rails", "~> 6.0.0.beta2"
+  gem "sqlite3", "~> 1.4", platform: [:ruby, :mswin, :mingw, :x64_mingw]
+
+  # TODO: Remove when rspec-rails 4.0 released
+  gem "rspec-core", github: "rspec/rspec-core"
+  gem "rspec-expectations", github: "rspec/rspec-expectations"
+  gem "rspec-mocks", github: "rspec/rspec-mocks"
+  gem "rspec-rails", github: "rspec/rspec-rails", branch: "4-0-dev"
+  gem "rspec-support", github: "rspec/rspec-support"
 end
 
 appraise "rails-master" do
   gem "rails", git: 'https://github.com/rails/rails'
-  gem "arel", git: 'https://github.com/rails/arel'
+  gem "sqlite3", "~> 1.4", platform: [:ruby, :mswin, :mingw, :x64_mingw]
+
+  # TODO: Remove when rspec-rails 4.0 released
+  gem "rspec-core", github: "rspec/rspec-core"
+  gem "rspec-expectations", github: "rspec/rspec-expectations"
+  gem "rspec-mocks", github: "rspec/rspec-mocks"
+  gem "rspec-rails", github: "rspec/rspec-rails", branch: "4-0-dev"
+  gem "rspec-support", github: "rspec/rspec-support"
 end

data/Gemfile

@@ -1,12 +1,20 @@
 source "https://rubygems.org"
+git_source(:github) { |repo| "https://github.com/#{repo}.git" }
 
-gem "rails", ">= 5.2.1.1", "< 6.0"
+gemspec
+
+gem "rails", "~> 6.0.0.beta3"
 
-gem "appraisal"
+# TODO: Remove when rspec-rails 4.0 released
+gem "rspec-core", github: "rspec/rspec-core"
+gem "rspec-expectations", github: "rspec/rspec-expectations"
+gem "rspec-mocks", github: "rspec/rspec-mocks"
+gem "rspec-rails", github: "rspec/rspec-rails", branch: "4-0-dev"
+gem "rspec-support", github: "rspec/rspec-support"
 
-gem "bcrypt", "~> 3.1"
+gem "bcrypt", "~> 3.1", require: false
 
 gem "activerecord-jdbcsqlite3-adapter", platform: :jruby
-gem "sqlite3", platform: [:ruby, :mswin, :mingw, :x64_mingw]
+gem "sqlite3", "~> 1.4", platform: [:ruby, :mswin, :mingw, :x64_mingw]
+
 gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw]
-gemspec

data/NEWS.md

@@ -7,15 +7,52 @@ User-visible changes worth mentioning.
 
 ## master
 
-- [#1188]  Use `params` instead of `request.POST` in tokens controller (fixes #1183).
-- [#1179] Authorization Code Grant Flow without client id returns invalid_client error.
+- [#1208] Unify hashing implementation into secret storing strategies
+
+  **[IMPORTANT]**: If you have been using the master branch of doorkeeper with bcrypt in your Gemfile.lock,
+  your application secrets have been hashed using BCrypt. To restore this behavior, use the initializer option
+  `use_application_hashing using: 'Doorkeeper::SecretStoring::BCrypt`.
+
+- [#1216] Add nil check to `expires_at` method.
+- [#1215] Fix deprecates for Rails 6.
+- [#1214] Scopes field accepts array.
+- [#1209] Fix tokens validation for Token Introspection request.
+- [#1202] Use correct HTTP status codes for error responses.
+
+  **[IMPORTANT]**: this change might break your application if you were relying on the previous
+  401 status codes, this is now a 400 by default, or a 401 for `invalid_client` and `invalid_token` errors.
+
+- [#1201] Fix custom TTL block `client` parameter to always be an `Doorkeeper::Application` instance.
+
+  **[IMPORTANT]**: those who defined `custom_access_token_expires_in` configuration option need to check
+  their block implementation: if you are using `oauth_client.application` to get `Doorkeeper::Application`
+  instance, then you need to replace it with just `oauth_client`.
+
+- [#1200] Increase default Doorkeeper access token value complexity (`urlsafe_base64` instead of just `hex`)
+  matching RFC6749/RFC6750.
+
+  **[IMPORTANT]**: this change have possible side-effects in case you have custom database constraints for
+  access token value, application secrets, refresh tokens or you patched Doorkeeper models and introduced
+  token value validations, or you are using database with case-insensitive WHERE clause like MySQL
+  (you can face some collisions). Before this change access token value matched `[a-f0-9]` regex, and now
+  it matches `[a-zA-Z0-9\-_]`. In case you have such restrictions and your don't use custom token generator
+  please change configuration option `default_generator_method ` to `:hex`.
+
+- [#1195] Allow to customize Token Introspection response (fixes #1194).
+- [#1189] Option to set `token_reuse_limit`.
+- [#1191] Try to load bcrypt for hashing of application secrets, but add fallback.
+
+## 5.1.0.rc1
+
+- [#1188] Use `params` instead of `request.POST` in tokens controller (fixes #1183).
 - [#1182] Fix loopback IP redirect URIs to conform with RFC8252, p. 7.3 (fixes #1170).
+- [#1179] Authorization Code Grant Flow without client id returns invalid_client error.
 - [#1177] Allow to limit `scopes` for certain `grant_types`
-- [#1162] Fix `enforce_content_type` for requests without body.
-- [#1164] Fix error when `root_path` is not defined.
-- [#1175] Internal refactor: use `scopes_string` inside `scopes`.
 - [#1176] Fix test factory support for `factory_bot_rails`
-- [#1168]: Allow optional hashing of tokens and secrets.
+- [#1175] Internal refactor: use `scopes_string` inside `scopes`.
+- [#1168] Allow optional hashing of tokens and secrets.
+- [#1164] Fix error when `root_path` is not defined.
+- [#1162] Fix `enforce_content_type` for requests without body.
 
 ## 5.0.2
 
@@ -24,13 +61,13 @@ User-visible changes worth mentioning.
 
 ## 5.0.1
 
+- [#1154] Refactor `StaleRecordsCleaner` to be ORM agnostic.
+- [#1152] Fix migration template: change resource owner data type from integer to Rails generic `references`
+- [#1151] Fix Refresh Token strategy: add proper validation of client credentials both for Public & Private clients.
+- [#1149] Fix for `URIChecker#valid_for_authorization?` false negative when query is blank, but `?` present.
 - [#1140] Allow rendering custom errors from exceptions (issue #844). Originally opened as [#944].
 - [#1138] Revert regression bug (check for token expiration in Authorizations controller so authorization
   triggers every time)
-- [#1149] Fix for `URIChecker#valid_for_authorization?` false negative when query is blank, but `?` present.
-- [#1151] Fix Refresh Token strategy: add proper validation of client credentials both for Public & Private clients.
-- [#1152] Fix migration template: change resource owner data type from integer to Rails generic `references`
-- [#1154] Refactor `StaleRecordsCleaner` to be ORM agnostic.
 
 ## 5.0.0
 
@@ -38,14 +75,14 @@ User-visible changes worth mentioning.
 
 ## 5.0.0.rc2
 
-- [#1106] Restrict access to AdminController with 'Forbidden 403' if admin_authenticator is not
-  configured by developers..
-- [#1108] Simple formating of callback URLs when listing oauth applications
+- [#1122] Fix AuthorizationsController#new error response to be in JSON format
+- [#1119] Fix token revocation for OAuth apps using "implicit" grant flow
 - [#1116] `AccessGrant`s will now be revoked along with `AccessToken`s when
   hitting the `AuthorizedApplicationController#destroy` route.
 - [#1114] Make token info endpoint's attributes consistent with token creation
-- [#1119] Fix token revocation for OAuth apps using "implicit" grant flow
-- [#1122] Fix AuthorizationsController#new error response to be in JSON format
+- [#1108] Simple formating of callback URLs when listing oauth applications
+- [#1106] Restrict access to AdminController with 'Forbidden 403' if admin_authenticator is not
+  configured by developers.
 
 ## 5.0.0.rc1
 

data/README.md

@@ -22,504 +22,112 @@ Supported features:
   - [Proof Key for Code Exchange](https://tools.ietf.org/html/rfc7636)
 - [OAuth 2.0 Token Revocation](http://tools.ietf.org/html/rfc7009)
 - [OAuth 2.0 Token Introspection](https://tools.ietf.org/html/rfc7662)
-
-See [list of tutorials](https://github.com/doorkeeper-gem/doorkeeper/wiki#how-tos--tutorials) in order to
-learn how to use the gem or integrate it with other solutions / gems.
-
-## 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
-
-- See the [Wiki](https://github.com/doorkeeper-gem/doorkeeper/wiki)
-- See [upgrade guides](https://github.com/doorkeeper-gem/doorkeeper/wiki/Migration-from-old-versions)
-- For general questions, please post in [Stack Overflow](http://stackoverflow.com/questions/tagged/doorkeeper)
-- See [SECURITY.md](SECURITY.md) for this project's security disclose
-  policy
+- [OAuth 2.0 Threat Model and Security Considerations](http://tools.ietf.org/html/rfc6819)
 
 ## Table of Contents
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
+
+- [Documentation](#documentation)
 - [Installation](#installation)
-- [Configuration](#configuration)
-  - [ORM](#orm)
-    - [Active Record](#active-record)
-    - [MongoDB](#mongodb)
-    - [Sequel](#sequel)
-    - [Couchbase](#couchbase)
-  - [API mode](#api-mode)
-  - [Routes](#routes)
-  - [Authenticating](#authenticating)
-  - [Internationalization (I18n)](#internationalization-i18n)
-  - [Customizing errors](#customizing-errors)
-  - [Rake Tasks](#rake-tasks)
-- [Protecting resources with OAuth (a.k.a your API endpoint)](#protecting-resources-with-oauth-aka-your-api-endpoint)
-  - [Ruby on Rails controllers](#ruby-on-rails-controllers)
-  - [Grape endpoints](#grape-endpoints)
-  - [Route Constraints and other integrations](#route-constraints-and-other-integrations)
-  - [Access Token Scopes](#access-token-scopes)
-  - [Custom Access Token Generator](#custom-access-token-generator)
-  - [Authenticated resource owner](#authenticated-resource-owner)
-  - [Applications list](#applications-list)
-- [Other customizations](#other-customizations)
-- [Testing](#testing)
-- [Upgrading](#upgrading)
+  - [Ruby on Rails](#ruby-on-rails)
+  - [Grape](#grape)
+- [ORMs](#orms)
+- [Extensions](#extensions)
+- [Example Applications](#example-applications)
+- [Tutorials](#tutorials)
+- [Sponsors](#sponsors)
 - [Development](#development)
 - [Contributing](#contributing)
-- [Other resources](#other-resources)
-  - [Wiki](#wiki)
-  - [Screencast](#screencast)
-  - [Client applications](#client-applications)
-  - [Contributors](#contributors)
-  - [IETF Standards](#ietf-standards)
-  - [License](#license)
+- [Contributors](#contributors)
+- [License](#license)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-## Installation
-
-Put this in your Gemfile:
-
-``` ruby
-gem 'doorkeeper'
-```
-
-Run the installation generator with:
-
-    rails generate doorkeeper:install
-
-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:
-
-```ruby
-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:
-
-[PKCE flow]: https://tools.ietf.org/html/rfc7636
-
-```sh
-rails generate doorkeeper:pkce
-```
-
-Then run migrations:
-
-```sh
-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.
-
-```ruby
-class User < ApplicationRecord
-  has_many :access_grants, class_name: "Doorkeeper::AccessGrant",
-                           foreign_key: :resource_owner_id,
-                           dependent: :delete_all # or :destroy if you need callbacks
-
-  has_many :access_tokens, class_name: "Doorkeeper::AccessToken",
-                           foreign_key: :resource_owner_id,
-                           dependent: :delete_all # or :destroy if you need callbacks
-end
-```
-
-#### MongoDB
-
-See [doorkeeper-mongodb project] for Mongoid and MongoMapper support. Follow along
-the implementation in that repository to extend doorkeeper with other ORMs.
-
-[doorkeeper-mongodb project]: https://github.com/doorkeeper-gem/doorkeeper-mongodb
-
-#### Sequel
-
-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.
-
-[Sequel gem]: https://github.com/jeremyevans/sequel/
-[doorkeeper-sequel extension]: https://github.com/nbulaj/doorkeeper-sequel
-
-#### Couchbase
-
-Use [doorkeeper-couchbase] extension if you are using Couchbase database.
-
-[doorkeeper-couchbase]: https://github.com/acaprojects/doorkeeper-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](http://edgeguides.rubyonrails.org/api_app.html).
-All you need is just to configure the gem to work in desired mode:
-
-``` ruby
-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:
-
-``` ruby
-Rails.application.routes.draw do
-  use_doorkeeper
-  # your routes
-end
-```
-
-This will mount following routes:
-
-    GET       /oauth/authorize/native?code
-    GET       /oauth/authorize
-    POST      /oauth/authorize
-    DELETE    /oauth/authorize
-    POST      /oauth/token
-    POST      /oauth/revoke
-    POST      /oauth/introspect
-    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](https://github.com/doorkeeper-gem/doorkeeper/wiki/Customizing-routes).
-
-### Authenticating
-
-You need to configure Doorkeeper in order to provide `resource_owner` model
-and authentication block in `config/initializers/doorkeeper.rb`:
-
-``` ruby
-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](https://github.com/doorkeeper-gem/doorkeeper/wiki/Authenticating-using-Clearance-or-DIY).
-
-### Internationalization (I18n)
-
-Doorkeeper support multiple languages. See language files in
-[the I18n repository](https://github.com/doorkeeper-gem/doorkeeper-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`:
-
-```ruby
-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
-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.
+## Documentation
 
-## Protecting resources with OAuth (a.k.a your API endpoint)
+This documentation is valid for `master` branch. Please check the documentation for the version of doorkeeper you are using in:
+https://github.com/doorkeeper-gem/doorkeeper/releases.
 
-### Ruby on Rails controllers
+Additionally, other resources can be found on:
 
-To protect your controllers (usual one or `ActionController::API`) with OAuth,
-you just need to setup `before_action`s specifying the actions you want to
-protect. For example:
-
-``` ruby
-class Api::V1::ProductsController < Api::V1::ApiController
-  before_action :doorkeeper_authorize! # Requires access token for all actions
-  
-  # before_action -> { doorkeeper_authorize! :read, :write }
-
-  # your actions
-end
-```
-
-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.
-
-For more information about integration with Grape see the [Wiki].
-
-[Grape framework]: https://github.com/ruby-grape/grape
-[Wiki]: https://github.com/doorkeeper-gem/doorkeeper/wiki/Grape-Integration
-
-``` ruby
-require 'doorkeeper/grape/helpers'
-
-module API
-  module V1
-    class Users < Grape::API
-      helpers Doorkeeper::Grape::Helpers
-
-      before do
-        doorkeeper_authorize!
-      end
-
-      # route_setting :scopes, ['user:email'] - for old versions of Grape
-      get :emails, scopes: [:user, :write] do
-        [{'email' => current_user.email}]
-      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.
-
-```ruby
-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](https://github.com/doorkeeper-gem/doorkeeper/wiki/ActionController::Metal-with-doorkeeper).
-
-### 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`
-
-```ruby
-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:
-
-```ruby
-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 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:
-
-```ruby
-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 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](http://jwt.io), specify an object that responds to
-`.generate(options = {})` and returns a string to be used as the token.
-
-```ruby
-Doorkeeper.configure do
-  access_token_generator "Doorkeeper::JWT"
-end
-```
-
-JWT token support is available with
-[Doorkeeper-JWT](https://github.com/chriswarren/doorkeeper-jwt).
+- [Guides](https://doorkeeper.gitbook.io/guides/) with how-to get started and configuration documentation
+- See the [Wiki](https://github.com/doorkeeper-gem/doorkeeper/wiki) with articles and other documentation
+- Screencast from [railscasts.com](http://railscasts.com/): [#353
+OAuth with
+Doorkeeper](http://railscasts.com/episodes/353-oauth-with-doorkeeper)
+- See [upgrade guides](https://github.com/doorkeeper-gem/doorkeeper/wiki/Migration-from-old-versions)
+- For general questions, please post on [Stack Overflow](http://stackoverflow.com/questions/tagged/doorkeeper)
+- See [SECURITY.md](SECURITY.md) for this project's security disclose
+  policy
 
-### Custom Base Controller
+## Installation
 
-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:
+Installation depends on the framework you're using. The first step is to add the following to your Gemfile:
 
 ```ruby
-Doorkeeper.configure do
-  base_controller 'ApplicationController'
-end
+gem 'doorkeeper'
 ```
 
-### 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:
+And run `bundle install`. After this, check out the guide related to the framework you're using.
 
-``` ruby
-class Api::V1::CredentialsController < Api::V1::ApiController
-  before_action :doorkeeper_authorize!
-  respond_to    :json
+### Ruby on Rails
 
-  # GET /me.json
-  def me
-    respond_with current_resource_owner
-  end
+Doorkeeper currently supports Ruby on Rails 5. See the guide [here](https://doorkeeper.gitbook.io/guides/ruby-on-rails/getting-started).
 
-  private
+### Grape
 
-  # Find the user that owns the access token
-  def current_resource_owner
-    User.find(doorkeeper_token.resource_owner_id) if doorkeeper_token
-  end
-end
-```
+Guide for integration with Grape framework can be found [here](https://doorkeeper.gitbook.io/guides/grape/grape).
 
-In this example, we're returning the credentials (`me.json`) of the access
-token owner.
+## ORMs
 
-### Applications list
+Doorkeeper supports Active Record by default, but can be configured to work with the following ORMs:
 
-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.
+| ORM | Support via |
+| :--- | :--- |
+| Active Record | by default |
+| MongoDB | [doorkeeper-gem/doorkeeper-mongodb](https://github.com/doorkeeper-gem/doorkeeper-mongodb) |
+| Sequel | [nbulaj/doorkeeper-sequel](https://github.com/nbulaj/doorkeeper-sequel) |
+| Couchbase | [acaprojects/doorkeeper-couchbase](https://github.com/acaprojects/doorkeeper-couchbase) |
 
-To change the protection rules of this endpoint you should uncomment these lines:
+## Extensions
 
-```ruby
-# 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
-```
+Extensions that are not included by default and can be installed separately.
 
-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](https://github.com/doorkeeper-gem/doorkeeper/wiki/Customizing-routes).
+|  | Link |
+| :--- | :--- |
+| OpenID Connect extension | [doorkeeper-gem/doorkeeper-openid\_connect](https://github.com/doorkeeper-gem/doorkeeper-openid_connect) |
+| JWT Token support | [doorkeeper-gem/doorkeeper-jwt](https://github.com/doorkeeper-gem/doorkeeper-jwt) |
+| Assertion grant extension | [doorkeeper-gem/doorkeeper-grants\_assertion](https://github.com/doorkeeper-gem/doorkeeper-grants_assertion) |
+| I18n translations | [doorkeeper-gem/doorkeeper-i18n](https://github.com/doorkeeper-gem/doorkeeper-i18n) |
 
-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):
+## Example Applications
 
-```ruby
-# config/initializers/doorkeeper.rb
-Doorkeeper.configure do
-  # ...
-
-  default_scopes :read, :write
-  optional_scopes :create, :update
-
-  enforce_configured_scopes
-end
-```
+These applications show how Doorkeeper works and how to integrate with it. Start with the oAuth2 server and use the clients to connect with the server.
 
-## Other customizations
+| Application | Link |
+| :--- | :--- |
+| oAuth2 Server with Doorkeeper | [doorkeeper-gem/doorkeeper-provider-app](https://github.com/doorkeeper-gem/doorkeeper-provider-app) |
+| Sinatra Client connected to Provider App | [doorkeeper-gem/doorkeeper-sinatra-client](https://github.com/doorkeeper-gem/doorkeeper-sinatra-client) |
+| Devise + Omniauth Client | [doorkeeper-gem/doorkeeper-devise-client](https://github.com/doorkeeper-gem/doorkeeper-devise-client) |
 
-- [Associate users to OAuth applications (ownership)](https://github.com/doorkeeper-gem/doorkeeper/wiki/Associate-users-to-OAuth-applications-%28ownership%29)
-- [CORS - Cross Origin Resource Sharing](https://github.com/doorkeeper-gem/doorkeeper/wiki/%5BCORS%5D-Cross-Origin-Resource-Sharing)
-- see more on [Wiki page](https://github.com/doorkeeper-gem/doorkeeper/wiki)
+You may want to create a client application to
+test the integration. Check out these [client
+examples](https://github.com/doorkeeper-gem/doorkeeper/wiki/Example-Applications)
+in our wiki or follow this [tutorial
+here](https://github.com/doorkeeper-gem/doorkeeper/wiki/Testing-your-provider-with-OAuth2-gem).
 
-## Testing
+## Tutorials
 
-You can use Doorkeeper models in your application test suite. Note that starting from
-Doorkeeper 4.3.0 it uses [ActiveSupport lazy loading hooks](http://api.rubyonrails.org/classes/ActiveSupport/LazyLoadHooks.html)
-to load models. There are [known issue](https://github.com/doorkeeper-gem/doorkeeper/issues/1043)
-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.
+See [list of tutorials](https://github.com/doorkeeper-gem/doorkeeper/wiki#how-tos--tutorials) in order to learn how to use the gem or integrate it with other solutions / gems.
 
-## Upgrading
+## Sponsors
 
-If you want to upgrade doorkeeper to a new version, check out the [upgrading
-notes](https://github.com/doorkeeper-gem/doorkeeper/wiki/Migration-from-old-versions)
-and take a look at the
-[changelog](https://github.com/doorkeeper-gem/doorkeeper/blob/master/NEWS.md).
+<a href="https://oauth.io/?utm_source=doorkeeper-gem" target="_blank"><img src="https://oauth.io/img/logo_text.png"/></a>
 
-Doorkeeper follows [semantic versioning](http://semver.org/).
+> If you prefer not to deal with the gory details of OAuth 2, need dedicated customer support & consulting, try the cloud-based SaaS version: [https://oauth.io](https://oauth.io/?utm_source=doorkeeper-gem)
 
 ## Development
 
@@ -548,38 +156,11 @@ integrate the gem with your app and let us know!
 Also, check out our [contributing guidelines
 page](https://github.com/doorkeeper-gem/doorkeeper/wiki/Contributing).
 
-## Other resources
-
-### Wiki
-
-You can find everything about Doorkeeper in our [wiki
-here](https://github.com/doorkeeper-gem/doorkeeper/wiki).
-
-### Screencast
-
-Check out this screencast from [railscasts.com](http://railscasts.com/): [#353
-OAuth with
-Doorkeeper](http://railscasts.com/episodes/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](https://github.com/doorkeeper-gem/doorkeeper/wiki/Example-Applications)
-in our wiki or follow this [tutorial
-here](https://github.com/doorkeeper-gem/doorkeeper/wiki/Testing-your-provider-with-OAuth2-gem).
-
-### Contributors
+## Contributors
 
 Thanks to all our [awesome
 contributors](https://github.com/doorkeeper-gem/doorkeeper/graphs/contributors)!
 
-### IETF Standards
-
-* [The OAuth 2.0 Authorization Framework](http://tools.ietf.org/html/rfc6749)
-* [OAuth 2.0 Threat Model and Security Considerations](http://tools.ietf.org/html/rfc6819)
-* [OAuth 2.0 Token Revocation](http://tools.ietf.org/html/rfc7009)
-
-### License
+## License
 
 MIT License. Copyright 2011 Applicake.