doorkeeper 4.2.5 → 5.0.0

data/README.md

@@ -1,24 +1,38 @@
-# Doorkeeper - awesome oauth provider for your Rails app.
+# Doorkeeper — awesome OAuth 2 provider for your Rails / Grape app.
 
+[![Gem Version](https://badge.fury.io/rb/doorkeeper.svg)](https://rubygems.org/gems/doorkeeper)
 [![Build Status](https://travis-ci.org/doorkeeper-gem/doorkeeper.svg?branch=master)](https://travis-ci.org/doorkeeper-gem/doorkeeper)
-[![Dependency Status](https://gemnasium.com/doorkeeper-gem/doorkeeper.svg?travis)](https://gemnasium.com/doorkeeper-gem/doorkeeper)
 [![Code Climate](https://codeclimate.com/github/doorkeeper-gem/doorkeeper.svg)](https://codeclimate.com/github/doorkeeper-gem/doorkeeper)
-[![Gem Version](https://badge.fury.io/rb/doorkeeper.svg)](https://rubygems.org/gems/doorkeeper)
+[![Coverage Status](https://coveralls.io/repos/github/doorkeeper-gem/doorkeeper/badge.svg?branch=master)](https://coveralls.io/github/doorkeeper-gem/doorkeeper?branch=master)
 [![Security](https://hakiri.io/github/doorkeeper-gem/doorkeeper/master.svg)](https://hakiri.io/github/doorkeeper-gem/doorkeeper/master)
+[![Reviewed by Hound](https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg)](https://houndci.com)
 
-Doorkeeper is a gem that makes it easy to introduce OAuth 2 provider
-functionality to your Rails or Grape application.
+Doorkeeper is a gem (Rails engine) that makes it easy to introduce OAuth 2 provider
+functionality to your Ruby on Rails or Grape application.
 
-[PR 567]: https://github.com/doorkeeper-gem/doorkeeper/pull/567
+Supported features:
 
+- [The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749)
+  - [Authorization Code Flow](http://tools.ietf.org/html/draft-ietf-oauth-v2-22#section-4.1)
+  - [Access Token Scopes](http://tools.ietf.org/html/draft-ietf-oauth-v2-22#section-3.3)
+  - [Refresh token](http://tools.ietf.org/html/draft-ietf-oauth-v2-22#section-1.5)
+  - [Implicit grant](http://tools.ietf.org/html/draft-ietf-oauth-v2-22#section-4.2)
+  - [Resource Owner Password Credentials](http://tools.ietf.org/html/draft-ietf-oauth-v2-22#section-4.3)
+  - [Client Credentials](http://tools.ietf.org/html/draft-ietf-oauth-v2-22#section-4.4)
+  - [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)
 
 ## 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 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
 
 ## Table of Contents
 
@@ -27,19 +41,26 @@ https://github.com/doorkeeper-gem/doorkeeper/releases
 
 - [Installation](#installation)
 - [Configuration](#configuration)
-  - [Active Record](#active-record)
-  - [Other ORMs](#other-orms)
+  - [ORM](#orm)
+    - [Active Record](#active-record)
+    - [MongoDB](#mongodb)
+    - [Sequel](#sequel)
+    - [Couchbase](#couchbase)
+  - [API mode](#api-mode)
   - [Routes](#routes)
   - [Authenticating](#authenticating)
   - [Internationalization (I18n)](#internationalization-i18n)
+  - [Rake Tasks](#rake-tasks)
 - [Protecting resources with OAuth (a.k.a your API endpoint)](#protecting-resources-with-oauth-aka-your-api-endpoint)
-  - [Protect your API with OAuth when using Grape](#protect-your-api-with-oauth-when-using-grape)
+  - [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)
 - [Development](#development)
 - [Contributing](#contributing)
@@ -69,10 +90,12 @@ This will install the doorkeeper initializer into `config/initializers/doorkeepe
 
 ## Configuration
 
-### Active Record
+### ORM
 
-By default doorkeeper is configured to use active record, so to start you have
-to generate the migration tables:
+#### 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
 
@@ -84,25 +107,81 @@ 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:
+
+[PKCE flow]: https://tools.ietf.org/html/rfc7636
+
+```sh
+    rails generate doorkeeper:pkce
+```
+
 Then run migrations:
 
 ```sh
 rake db:migrate
 ```
 
-### Other ORMs
+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
@@ -117,12 +196,13 @@ end
 
 This will mount following routes:
 
-    GET       /oauth/authorize/:code
+    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
@@ -139,7 +219,7 @@ 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)
+    User.find_by(id: session[:current_user_id]) || redirect_to(login_url)
   end
 end
 ```
@@ -152,20 +232,52 @@ 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)
 
-See language files in [the I18n repository](https://github.com/doorkeeper-gem/doorkeeper-i18n).
+Doorkeeper support multiple languages. See language files in
+[the I18n repository](https://github.com/doorkeeper-gem/doorkeeper-i18n).
+
+### 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.
 
 ## Protecting resources with OAuth (a.k.a your API endpoint)
 
-To protect your API with OAuth, you just need to setup `before_action`s
-specifying the actions you want to protect. For example:
+### Ruby on Rails controllers
+
+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! # Require access token for all actions
+  before_action :doorkeeper_authorize! # Requires access token for all actions
+  
+  # before_action -> { doorkeeper_authorize! :read, :write }
 
   # your actions
 end
@@ -174,16 +286,17 @@ end
 You can pass any option `before_action` accepts, such as `if`, `only`,
 `except`, and others.
 
-### Protect your API with OAuth when using Grape
+### Grape endpoints
 
-As of [PR 567] doorkeeper has helpers for Grape >= 0.10. 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`.
+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].
 
-[PR 567]: https://github.com/doorkeeper-gem/doorkeeper/pull/567
+[Grape framework]: https://github.com/ruby-grape/grape
 [Wiki]: https://github.com/doorkeeper-gem/doorkeeper/wiki/Grape-Integration
 
 ``` ruby
@@ -198,8 +311,8 @@ module API
         doorkeeper_authorize!
       end
 
-      route_setting :scopes, ['user:email']
-      get :emails do
+      # route_setting :scopes, ['user:email'] - for old versions of Grape
+      get :emails, scopes: [:user, :write] do
         [{'email' => current_user.email}]
       end
 
@@ -209,7 +322,6 @@ module API
 end
 ```
 
-
 ### Route Constraints and other integrations
 
 You can leverage the `Doorkeeper.authenticate` facade to easily extract a
@@ -224,7 +336,6 @@ module Constraint
       token = Doorkeeper.authenticate(request)
       token && token.accessible?
     end
-
   end
 end
 ```
@@ -296,8 +407,10 @@ JWT token support is available with
 
 ### 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:
+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:
 
 ```ruby
 Doorkeeper.configure do
@@ -342,7 +455,7 @@ 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)
+    Admin.find_by(id: session[:admin_id]) || redirect_to(routes.new_admin_session_url)
   end
 end
 ```
@@ -353,10 +466,36 @@ 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).
 
+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):
+
+```ruby
+# config/initializers/doorkeeper.rb
+Doorkeeper.configure do
+  # ...
+
+  default_scopes :read, :write
+  optional_scopes :create, :update
+
+  enforce_configured_scopes
+end
+```
+
 ## Other customizations
 
 - [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)
+
+## 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](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.
 
 ## Upgrading
 
@@ -373,7 +512,7 @@ To run the local engine server:
 
 ```
 bundle install
-bundle exec rails server
+bundle exec rake doorkeeper:server
 ````
 
 By default, it uses the latest Rails version with ActiveRecord. To run the
@@ -383,8 +522,6 @@ 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
@@ -400,7 +537,7 @@ page](https://github.com/doorkeeper-gem/doorkeeper/wiki/Contributing).
 
 ### Wiki
 
-You can find everything about doorkeeper in our [wiki
+You can find everything about Doorkeeper in our [wiki
 here](https://github.com/doorkeeper-gem/doorkeeper/wiki).
 
 ### Screencast
@@ -422,7 +559,6 @@ here](https://github.com/doorkeeper-gem/doorkeeper/wiki/Testing-your-provider-wi
 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)

data/RELEASING.md

@@ -1,17 +1,10 @@
 # Releasing doorkeeper
 
+How to release doorkeeper in five easy steps!
+
 1. Update `lib/doorkeeper/version.rb` file accordingly.
 2. Update `NEWS.md` to reflect the changes since last release.
-3. Commit changes. There shouldn’t be code changes, and thus CI doesn’t need to
-   run, you can then add “[ci skip]” to the commit message.
-4. Tag the release: `git tag vVERSION -m "Release vVERSION"`
-5. Push changes: `git push && git push --tags`
-6. Build and publish the gem:
-
-   ```bash
-   gem build doorkeeper.gemspec
-   gem push doorkeeper-*.gem
-   ```
-
-7. Announce the new release, making sure to say “thank you” to the contributors
+3. Commit changes: `git commit -am 'Bump to vVERSION'`
+4. Run `rake release`
+5. Announce the new release, making sure to say “thank you” to the contributors
    who helped shape this version!

data/Rakefile

@@ -15,6 +15,12 @@ namespace :doorkeeper do
     cd 'spec/dummy'
     system 'bundle exec rails g doorkeeper:install --force'
   end
+
+  desc 'Runs local test server'
+  task :server do
+    cd 'spec/dummy'
+    system 'bundle exec rails server'
+  end
 end
 
 Bundler::GemHelper.install_tasks

data/SECURITY.md

@@ -0,0 +1,15 @@
+# Reporting security issues in Doorkeeper
+
+Hello! Thank you for wanting to disclose a possible security
+vulnerability within the Doorkeeper gem! Please follow our disclosure
+policy as outlined below:
+
+1. Do NOT open up a GitHub issue with your report. Security reports
+   should be kept private until a possible fix is determined.
+2. Send an email to Nikita Bulai at bulaj.nikita AT gmail.com or one of
+   the others Doorkeeper maintainers listed in gemspec. You should receive
+   a prompt response.
+3. Be patient. Since Doorkeeper is in a stable maintenance phase, we want to
+   do as little as possible to rock the boat of the project.
+
+Thank you very much for adhering for these policies!

data/UPGRADE.md

@@ -0,0 +1,2 @@
+See [Upgrade Guides](https://github.com/doorkeeper-gem/doorkeeper/wiki/Migration-from-old-versions)
+in the project Wiki.

data/app/assets/stylesheets/doorkeeper/admin/application.css

@@ -5,6 +5,6 @@
  *= require_tree .
 */
 
-td {
-  vertical-align: middle !important;
+.doorkeeper-admin .form-group > .field_with_errors {
+  width: 16.66667%;
 }

data/app/controllers/doorkeeper/application_controller.rb

@@ -4,12 +4,9 @@ module Doorkeeper
 
     include Helpers::Controller
 
-    if ::Rails.version.to_i < 4
-      protect_from_forgery
-    else
+    unless Doorkeeper.configuration.api_only
       protect_from_forgery with: :exception
+      helper 'doorkeeper/dashboard'
     end
-
-    helper 'doorkeeper/dashboard'
   end
 end

data/app/controllers/doorkeeper/application_metal_controller.rb

@@ -5,6 +5,7 @@ module Doorkeeper
       AbstractController::Rendering,
       ActionController::Rendering,
       ActionController::Renderers::All,
+      AbstractController::Callbacks,
       Helpers::Controller
     ].freeze
 
@@ -12,6 +13,9 @@ module Doorkeeper
       include mod
     end
 
+    before_action :enforce_content_type,
+                  if: -> { Doorkeeper.configuration.enforce_content_type }
+
     ActiveSupport.run_load_hooks(:doorkeeper_metal_controller, self)
   end
 end

data/app/controllers/doorkeeper/applications_controller.rb

@@ -1,12 +1,24 @@
 module Doorkeeper
   class ApplicationsController < Doorkeeper::ApplicationController
-    layout 'doorkeeper/admin'
+    layout 'doorkeeper/admin' unless Doorkeeper.configuration.api_only
 
     before_action :authenticate_admin!
-    before_action :set_application, only: [:show, :edit, :update, :destroy]
+    before_action :set_application, only: %i[show edit update destroy]
 
     def index
-      @applications = Application.all
+      @applications = Application.ordered_by(:created_at)
+
+      respond_to do |format|
+        format.html
+        format.json { head :no_content }
+      end
+    end
+
+    def show
+      respond_to do |format|
+        format.html
+        format.json { render json: @application }
+      end
     end
 
     def new
@@ -15,26 +27,47 @@ module Doorkeeper
 
     def create
       @application = Application.new(application_params)
+
       if @application.save
-        flash[:notice] = I18n.t(:notice, scope: [:doorkeeper, :flash, :applications, :create])
-        redirect_to oauth_application_url(@application)
+        flash[:notice] = I18n.t(:notice, scope: %i[doorkeeper flash applications create])
+
+        respond_to do |format|
+          format.html { redirect_to oauth_application_url(@application) }
+          format.json { render json: @application }
+        end
       else
-        render :new
+        respond_to do |format|
+          format.html { render :new }
+          format.json { render json: { errors: @application.errors.full_messages }, status: :unprocessable_entity }
+        end
       end
     end
 
+    def edit; end
+
     def update
-      if @application.update_attributes(application_params)
-        flash[:notice] = I18n.t(:notice, scope: [:doorkeeper, :flash, :applications, :update])
-        redirect_to oauth_application_url(@application)
+      if @application.update(application_params)
+        flash[:notice] = I18n.t(:notice, scope: %i[doorkeeper flash applications update])
+
+        respond_to do |format|
+          format.html { redirect_to oauth_application_url(@application) }
+          format.json { render json: @application }
+        end
       else
-        render :edit
+        respond_to do |format|
+          format.html { render :edit }
+          format.json { render json: { errors: @application.errors.full_messages }, status: :unprocessable_entity }
+        end
       end
     end
 
     def destroy
-      flash[:notice] = I18n.t(:notice, scope: [:doorkeeper, :flash, :applications, :destroy]) if @application.destroy
-      redirect_to oauth_applications_url
+      flash[:notice] = I18n.t(:notice, scope: %i[doorkeeper flash applications destroy]) if @application.destroy
+
+      respond_to do |format|
+        format.html { redirect_to oauth_applications_url }
+        format.json { head :no_content }
+      end
     end
 
     private
@@ -44,7 +77,8 @@ module Doorkeeper
     end
 
     def application_params
-      params.require(:doorkeeper_application).permit(:name, :redirect_uri, :scopes)
+      params.require(:doorkeeper_application).
+        permit(:name, :redirect_uri, :scopes, :confidential)
     end
   end
 end