doorkeeper 5.2.0.rc1 → 5.2.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8d957f89709f38c434bcaa2f50d2b7a540ed613c37c49a7206cbab07c32c240
-  data.tar.gz: f1945351442b325395da930863b402cb45091f576075ffe0b71dbc285911d846
+  metadata.gz: 30363aebde1b255fb64b8df11e5d9b1c80f0d896ebb970908f764a8a5fd17fdf
+  data.tar.gz: 129cddd18b7ea164da1387d8a3fef5c40b4be96eca9f141ebb0167a318f28a07
 SHA512:
-  metadata.gz: 97b9c9d403403af0227f670b66876be06dac554beeb024f507e3c460a0fcd6c5eeb75b8747946ff622065791992ce1bf9c30f8366f964e57545e229366533048
-  data.tar.gz: f235dee893b1ad79ad1873006e68e0ad508a25f676c4d6ecd6f867cca0ec8c5f1776420d79e0efb8cefc7309b1f467ef34de3382249c698fd842872c3eea5254
+  metadata.gz: 48f707ac0ee598c6987cf396cc168f57975abe8fbf78ce0479733e1b7fdf35ef6abcd73474f0141c72eee1b08ce8a9f0cf46d866f974c0feea8ae9609cb36d07
+  data.tar.gz: 79c4aa3fdae50be283f3ef78c544554ad5d50d8395d6f6970a41c73a0d46d427b859dd07e38685120d0df9b1016567a3a34b79d882b9b23d6bb470a19c95ecd8

data/CHANGELOG.md

@@ -7,6 +7,19 @@ User-visible changes worth mentioning.
 
 ## master
 
+- [#PR ID] Add your description here
+
+## 5.2.0.rc2
+
+- [#1270] Find matching tokens in batches for `reuse_access_token` option (fix #1193).
+- [#1271] Reintroduce existing token revocation for client credentials.
+- [#1269] Update initializer template documentation.
+- [#1266] Use strong parameters within pre-authorization.
+- [#1264] Add :before_successful_authorization and :after_successful_authorization hooks in TokensController
+- [#1263] Response properly when introspection fails and fix configurations's user guide.
+
+## 5.2.0.rc1
+
 - [#1260], [#1261] Improve Token Introspection configuration option (access to tokens, client).
 - [#1257] Add constraint configuration when using client authentication on introspection endpoint.
 - [#1252] Returning `unauthorized` when the revocation of the token should not be performed due to wrong permissions.
@@ -31,7 +44,7 @@ User-visible changes worth mentioning.
 
 - [#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,
+  **[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`.
 

data/CONTRIBUTING.md

@@ -7,6 +7,13 @@ Fork, then clone the repo:
 
     git clone git@github.com:your-username/doorkeeper.git
 
+### Docker Setup
+
+Build the container image with: `docker build --pull -t doorkeeper:test .`
+Run the tests with: `docker run -it --rm doorkeeper:test`
+
+### Local Setup
+
 Set up Ruby dependencies via Bundler
 
     bundle install

data/Dangerfile

@@ -11,7 +11,7 @@ def changelog_entry_example
                    .sub(/[?.!,;]?$/, '')
                    .capitalize
 
-  "- [##{pr_number}]: #{pr_title}."
+  "- [##{pr_number}] #{pr_title}."
 end
 
 # --------------------------------------------------------------------------------------------------------------------

data/Dockerfile

@@ -0,0 +1,29 @@
+FROM ruby:2.6.3-alpine3.9
+
+RUN apk add --no-cache \
+  ca-certificates \
+  wget \
+  openssl \ 
+  bash \
+  build-base \
+  git \
+  sqlite-dev \
+  tzdata
+
+ENV LANG en_US.UTF-8
+ENV LANGUAGE en_US:en
+ENV LC_ALL en_US.UTF-8
+
+ENV BUNDLER_VERSION 2.0.1
+RUN gem install bundler -v ${BUNDLER_VERSION} -i /usr/local/lib/ruby/gems/$(ls /usr/local/lib/ruby/gems) --force
+
+WORKDIR /srv
+
+COPY Gemfile doorkeeper.gemspec /srv/
+COPY lib/doorkeeper/version.rb /srv/lib/doorkeeper/version.rb
+
+RUN bundle install
+
+COPY . /srv/
+
+CMD ["rake"]

data/app/controllers/doorkeeper/authorizations_controller.rb

@@ -68,7 +68,12 @@ module Doorkeeper
     def pre_auth
       @pre_auth ||= OAuth::PreAuthorization.new(Doorkeeper.configuration,
                                                 server.client_via_uid,
-                                                params)
+                                                pre_auth_params)
+    end
+
+    def pre_auth_params
+      params.permit(:response_type, :redirect_uri, :scope, :state,
+                    :code_challenge, :code_challenge_method)
     end
 
     def authorization

data/app/controllers/doorkeeper/tokens_controller.rb

@@ -88,7 +88,20 @@ module Doorkeeper
     end
 
     def authorize_response
-      @authorize_response ||= strategy.authorize
+      @authorize_response ||= begin
+        before_successful_authorization
+        auth = strategy.authorize
+        after_successful_authorization unless auth.is_a?(Doorkeeper::OAuth::ErrorResponse)
+        auth
+      end
+    end
+
+    def after_successful_authorization
+      Doorkeeper.configuration.after_successful_authorization.call(self)
+    end
+
+    def before_successful_authorization
+      Doorkeeper.configuration.before_successful_authorization.call(self)
     end
 
     def revocation_error_response

data/lib/doorkeeper/config.rb

@@ -322,9 +322,10 @@ module Doorkeeper
            end)
 
     # Configure protection of token introspection request.
-    # By default token introspection is allowed only for clients that
-    # introspected token belongs to or if access token been introspected
-    # is a public one (doesn't belong to any client).
+    # By default this configuration allows to introspect a token by
+    # another token of the same application, or to introspect the token
+    # that belongs to authorized client, or access token has been introspected
+    # is a public one (doesn't belong to any client)
     #
     # You can define any custom rule you need or just disable token
     # introspection at all.
@@ -340,9 +341,11 @@ module Doorkeeper
     #   Bearer token used to authorize the request
     #
     option :allow_token_introspection,
-           default: (lambda do |token, authorized_client, _authorized_token|
-             if token.application
-               token.application == authorized_client
+           default: (lambda do |token, authorized_client, authorized_token|
+             if authorized_token
+               authorized_token.application == token&.application
+             elsif token.application
+               authorized_client == token.application
              else
                true
              end

data/lib/doorkeeper/models/access_token_mixin.rb

@@ -76,9 +76,50 @@ module Doorkeeper
                             end
 
         tokens = authorized_tokens_for(application.try(:id), resource_owner_id)
-        tokens.detect do |token|
-          scopes_match?(token.scopes, scopes, application.try(:scopes))
+        find_matching_token(tokens, application, scopes)
+      end
+
+      # Interface to enumerate access token records in batches in order not
+      # to bloat the memory. Could be overloaded in any ORM extension.
+      #
+      def find_access_token_in_batches(relation, *args, &block)
+        relation.find_in_batches(*args, &block)
+      end
+
+      # Enumerates AccessToken records in batches to find a matching token.
+      # Batching is required in order not to pollute the memory if Application
+      # has huge amount of associated records.
+      #
+      # ActiveRecord 5.x - 6.x ignores custom ordering so we can't perform a
+      # database sort by created_at, so we need to load all the matching records,
+      # sort them and find latest one. Probably it would be better to rewrite this
+      # query using Time math if possible, but we n eed to consider ORM and
+      # different databases support.
+      #
+      # @param relation [ActiveRecord::Relation]
+      #   Access tokens relation
+      # @param application [Doorkeeper::Application]
+      #   Application instance
+      # @param scopes [String, Doorkeeper::OAuth::Scopes]
+      #   set of scopes
+      #
+      # @return [Doorkeeper::AccessToken, nil] Access Token instance or
+      #   nil if matching record was not found
+      #
+      def find_matching_token(relation, application, scopes)
+        return nil unless relation
+
+        matching_tokens = []
+
+        find_access_token_in_batches(relation) do |batch|
+          tokens = batch.select do |token|
+            scopes_match?(token.scopes, scopes, application.try(:scopes))
+          end
+
+          matching_tokens.concat(tokens)
         end
+
+        matching_tokens.max_by(&:created_at)
       end
 
       # Checks whether the token scopes match the scopes from the parameters

data/lib/doorkeeper/oauth/client_credentials/creator.rb

@@ -5,11 +5,25 @@ module Doorkeeper
     class ClientCredentialsRequest < BaseRequest
       class Creator
         def call(client, scopes, attributes = {})
+          existing_token = existing_token_for(client, scopes)
+
+          if Doorkeeper.configuration.reuse_access_token && existing_token&.reusable?
+            return existing_token
+          end
+
+          existing_token&.revoke
+
           AccessToken.find_or_create_for(
             client, nil, scopes, attributes[:expires_in],
             attributes[:use_refresh_token]
           )
         end
+
+        private
+
+        def existing_token_for(client, scopes)
+          Doorkeeper::AccessToken.matching_token_for client, nil, scopes
+        end
       end
     end
   end

data/lib/doorkeeper/oauth/token_introspection.rb

@@ -67,7 +67,7 @@ module Doorkeeper
           #  HTTP 401 code as described in Section 3 of OAuth 2.0 Bearer Token
           #  Usage [RFC6750].
           #
-          @error = :invalid_token if authorized_token_matches_introspected? || !authorized_token.accessible?
+          @error = :invalid_token unless valid_authorized_token?
         else
           @error = :invalid_request
         end
@@ -149,9 +149,9 @@ module Doorkeeper
       #
       def active?
         if authorized_client
-          valid_token? && token_introspection_allowed?(authorized_client.application)
+          valid_token? && token_introspection_allowed?(auth_client: authorized_client.application)
         else
-          valid_token? && token_introspection_allowed?(authorized_token&.application)
+          valid_token?
         end
       end
 
@@ -160,20 +160,26 @@ module Doorkeeper
         @token&.accessible?
       end
 
+      def valid_authorized_token?
+        !authorized_token_matches_introspected? &&
+          authorized_token.accessible? &&
+          token_introspection_allowed?(auth_token: authorized_token)
+      end
+
       # RFC7662 Section 2.1
       def authorized_token_matches_introspected?
         authorized_token.token == @token&.token
       end
 
       # config constraints for introspection in Doorkeeper.configuration.allow_token_introspection
-      def token_introspection_allowed?(client)
+      def token_introspection_allowed?(auth_client: nil, auth_token: nil)
         allow_introspection = Doorkeeper.configuration.allow_token_introspection
         return allow_introspection unless allow_introspection.respond_to?(:call)
 
         allow_introspection.call(
           @token,
-          client,
-          authorized_token
+          auth_client,
+          auth_token
         )
       end
 

data/lib/doorkeeper/version.rb

@@ -10,7 +10,7 @@ module Doorkeeper
     MAJOR = 5
     MINOR = 2
     TINY = 0
-    PRE = "rc1"
+    PRE = "rc2"
 
     # Full version number
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")

data/lib/generators/doorkeeper/templates/initializer.rb

@@ -65,7 +65,7 @@ Doorkeeper.configure do
   # end
 
   # Use a custom class for generating the access token.
-  # See https://github.com/doorkeeper-gem/doorkeeper#custom-access-token-generator
+  # See https://doorkeeper.gitbook.io/guides/configuration/other-configurations#custom-access-token-generator
   #
   # access_token_generator '::Doorkeeper::JWT'
 
@@ -160,7 +160,7 @@ Doorkeeper.configure do
 
   # Define access token scopes for your provider
   # For more information go to
-  # https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes
+  # https://doorkeeper.gitbook.io/guides/ruby-on-rails/scopes
   #
   # default_scopes  :public
   # optional_scopes :write, :update
@@ -296,7 +296,7 @@ Doorkeeper.configure do
   # or add any other functionality.
   #
   # before_successful_authorization do |controller|
-  #   Rails.logger.info(params.inspect)
+  #   Rails.logger.info(controller.request.params.inspect)
   # end
   #
   # after_successful_authorization do |controller|
@@ -314,23 +314,13 @@ Doorkeeper.configure do
   #   client.superapp? or resource_owner.admin?
   # end
 
-  # Configure custom constraints for the Token Introspection request. By default
-  # this configuration option allows to introspect the token that belongs to authorized
-  # client (from Bearer token or from authenticated client) OR when token doesn't
+  # Configure custom constraints for the Token Introspection request.
+  # By default this configuration option allows to introspect a token by another
+  # token of the same application, OR to introspect the token that belongs to
+  # authorized client (from authenticated client) OR when token doesn't
   # belong to any client (public token). Otherwise requester has no access to the
   # introspection and it will return response as stated in the RFC.
   #
-  # You can define your custom check:
-  #
-  # allow_token_introspection do |token, authorized_client, _authorized_token|
-  #   if token.application
-  #     # `protected_resource` is a new database boolean column, for example
-  #     token.application == authorized_client || authorized_client.protected_resource?
-  #   else
-  #     true
-  #   end
-  # end
-  #
   # Block arguments:
   #
   # @param token [Doorkeeper::AccessToken]
@@ -343,15 +333,38 @@ Doorkeeper.configure do
   # @param authorized_token [Doorkeeper::AccessToken]
   #   Bearer token used to authorize the request
   #
-  # Keep in mind, that in case the block returns `nil` or `false` introspection response
-  # doesn't have 401 status code and some descriptive body, you'll get 200 with
-  # { "active": false } body as stated in the RFC 7662 section 2.2. Introspection Response.
+  # In case the block returns `nil` or `false` introspection responses with 401 status code
+  # when using authorized token to introspect, or you'll get 200 with { "active": false } body
+  # when using authorized client to introspect as stated in the
+  # RFC 7662 section 2.2. Introspection Response.
+  #
+  # Using with caution:
+  # Keep in mind that these three parameters pass to block can be nil as following case:
+  #  `authorized_client` is nil if and only if `authorized_token` is present, and vice versa.
+  #  `token` will be nil if and only if `authorized_token` is present.
+  # So remember to use `&` or check if it is present before calling method on
+  # them to make sure you doesn't get NoMethodError exception.
+  #
+  # You can define your custom check:
+  #
+  # allow_token_introspection do |token, authorized_client, authorized_token|
+  #   if authorized_token
+  #     # customize: require `introspection` scope
+  #     authorized_token.application == token&.application ||
+  #       authorized_token.scopes.include?("introspection")
+  #   elsif token.application
+  #     # `protected_resource` is a new database boolean column, for example
+  #     authorized_client == token.application || authorized_client.protected_resource?
+  #   else
+  #     # public token (when token.application is nil, token doesn't belong to any application)
+  #     true
+  #   end
+  # end
   #
-  # You can completely disable any token introspection:
+  # Or you can completely disable any token introspection:
   #
   # allow_token_introspection false
   #
-  # In such case every request for token introspection will get { "active": false } response.
   # If you need to block the request at all, then configure your routes.rb or web-server
   # like nginx to forbid the request.
 

data/spec/controllers/authorizations_controller_spec.rb

@@ -524,4 +524,17 @@ describe Doorkeeper::AuthorizationsController, "implicit grant flow" do
       post :create
     end
   end
+
+  describe "strong parameters" do
+    it "ignores non-scalar scope parameter" do
+      get :new, params: {
+        client_id: client.uid,
+        response_type: "token",
+        redirect_uri: client.redirect_uri,
+        scope: { "0" => "profile" },
+      }
+
+      expect(response).to be_successful
+    end
+  end
 end

data/spec/controllers/tokens_controller_spec.rb

@@ -3,31 +3,139 @@
 require "spec_helper"
 
 describe Doorkeeper::TokensController do
-  describe "when authorization has succeeded" do
-    let(:token) { double(:token, authorize: true) }
+  let(:client) { FactoryBot.create :application }
+  let!(:user)  { User.create!(name: "Joe", password: "sekret") }
 
-    it "returns the authorization" do
-      skip "verify need of these specs"
+  before do
+    Doorkeeper.configure do
+      resource_owner_from_credentials do
+        User.first
+      end
+    end
 
-      expect(token).to receive(:authorization)
+    allow(Doorkeeper.configuration).to receive(:grant_flows).and_return(["password"])
+  end
 
-      post :create
+  subject { JSON.parse(response.body) }
+
+  describe "POST #create" do
+    before do
+      post :create, params: {
+        client_id: client.uid,
+        client_secret: client.secret,
+        grant_type: "password",
+      }
+    end
+
+    it "responds after authorization" do
+      expect(response).to be_successful
+    end
+
+    it "includes access token in response" do
+      expect(subject["access_token"]).to eq(Doorkeeper::AccessToken.first.token)
+    end
+
+    it "includes token type in response" do
+      expect(subject["token_type"]).to eq("Bearer")
+    end
+
+    it "includes token expiration in response" do
+      expect(subject["expires_in"].to_i).to eq(Doorkeeper.configuration.access_token_expires_in)
+    end
+
+    it "issues the token for the current client" do
+      expect(Doorkeeper::AccessToken.first.application_id).to eq(client.id)
+    end
+
+    it "issues the token for the current resource owner" do
+      expect(Doorkeeper::AccessToken.first.resource_owner_id).to eq(user.id)
     end
   end
 
-  describe "when authorization has failed" do
-    it "returns the error response" do
-      token = double(:token, authorize: false)
-      allow(controller).to receive(:token) { token }
+  describe "POST #create with errors" do
+    before do
+      post :create, params: {
+        client_id: client.uid,
+        client_secret: "invalid",
+        grant_type: "password",
+      }
+    end
 
-      post :create
+    it "responds after authorization" do
+      expect(response).to be_unauthorized
+    end
 
-      expect(response.status).to eq 400
-      expect(response.headers["WWW-Authenticate"]).to match(/Bearer/)
+    it "include error in response" do
+      expect(subject["error"]).to eq("invalid_client")
+    end
+
+    it "include error_description in response" do
+      expect(subject["error_description"]).to be
+    end
+
+    it "does not include access token in response" do
+      expect(subject["access_token"]).to be_nil
+    end
+
+    it "does not include token type in response" do
+      expect(subject["token_type"]).to be_nil
+    end
+
+    it "does not include token expiration in response" do
+      expect(subject["expires_in"]).to be_nil
+    end
+
+    it "does not issue any access token" do
+      expect(Doorkeeper::AccessToken.all).to be_empty
+    end
+  end
+
+  describe "POST #create with callbacks" do
+    after do
+      client.update_attribute :redirect_uri, "urn:ietf:wg:oauth:2.0:oob"
+    end
+
+    describe "when successful" do
+      after do
+        post :create, params: {
+          client_id: client.uid,
+          client_secret: client.secret,
+          grant_type: "password",
+        }
+      end
+
+      it "should call :before_successful_authorization callback" do
+        expect(Doorkeeper.configuration)
+          .to receive_message_chain(:before_successful_authorization, :call).with(instance_of(described_class))
+      end
+
+      it "should call :after_successful_authorization callback" do
+        expect(Doorkeeper.configuration)
+          .to receive_message_chain(:after_successful_authorization, :call).with(instance_of(described_class))
+      end
+    end
+
+    describe "with errors" do
+      after do
+        post :create, params: {
+          client_id: client.uid,
+          client_secret: "invalid",
+          grant_type: "password",
+        }
+      end
+
+      it "should call :before_successful_authorization callback" do
+        expect(Doorkeeper.configuration)
+          .to receive_message_chain(:before_successful_authorization, :call).with(instance_of(described_class))
+      end
+
+      it "should not call :after_successful_authorization callback" do
+        expect(Doorkeeper.configuration).not_to receive(:after_successful_authorization)
+      end
     end
   end
 
-  describe "when there is a failure due to a custom error" do
+  describe "POST #create with custom error" do
     it "returns the error response with a custom message" do
       # I18n looks for `doorkeeper.errors.messages.custom_message` in locale files
       custom_message = "my_message"
@@ -58,7 +166,7 @@ describe Doorkeeper::TokensController do
   end
 
   # http://tools.ietf.org/html/rfc7009#section-2.2
-  describe "revoking tokens" do
+  describe "POST #revoke" do
     let(:client) { FactoryBot.create(:application) }
     let(:access_token) { FactoryBot.create(:access_token, application: client) }
 
@@ -117,21 +225,7 @@ describe Doorkeeper::TokensController do
     end
   end
 
-  describe "authorize response memoization" do
-    it "memoizes the result of the authorization" do
-      strategy = double(:strategy, authorize: true)
-      expect(strategy).to receive(:authorize).once
-      allow(controller).to receive(:strategy) { strategy }
-      allow(controller).to receive(:create) do
-        2.times { controller.send :authorize_response }
-        controller.render json: {}, status: :ok
-      end
-
-      post :create
-    end
-  end
-
-  describe "when requested token introspection" do
+  describe "POST #introspect" do
     let(:client) { FactoryBot.create(:application) }
     let(:access_token) { FactoryBot.create(:access_token, application: client) }
     let(:token_for_introspection) { FactoryBot.create(:access_token, application: client) }
@@ -167,13 +261,15 @@ describe Doorkeeper::TokensController do
         end
       end
 
-      it "responds with just active: false response" do
+      it "responds with invalid_token error" do
         request.headers["Authorization"] = "Bearer #{access_token.token}"
 
         post :introspect, params: { token: token_for_introspection.token }
 
-        should_have_json "active", false
-        expect(json_response).not_to include("client_id", "token_type", "exp", "iat")
+        response_status_should_be 401
+
+        should_not_have_json "active"
+        should_have_json "error", "invalid_token"
       end
     end
 
@@ -268,15 +364,17 @@ describe Doorkeeper::TokensController do
         expect(json_response).to include("client_id", "token_type", "exp", "iat")
       end
 
-      it "responds with just active status if authorized token doesn't have introspection scope" do
+      it "responds with invalid_token error if authorized token doesn't have introspection scope" do
         access_token.update(scopes: "read write")
 
         request.headers["Authorization"] = "Bearer #{access_token.token}"
 
         post :introspect, params: { token: token_for_introspection.token }
 
-        should_have_json "active", false
-        expect(json_response).not_to include("client_id", "token_type", "exp", "iat")
+        response_status_should_be 401
+
+        should_not_have_json "active"
+        should_have_json "error", "invalid_token"
       end
     end
 
@@ -285,7 +383,7 @@ describe Doorkeeper::TokensController do
         FactoryBot.create(:access_token, application: client, revoked_at: 1.day.ago)
       end
 
-      it "responds with invalid token error" do
+      it "responds with invalid_token error" do
         request.headers["Authorization"] = "Bearer #{access_token.token}"
 
         post :introspect, params: { token: token_for_introspection.token }
@@ -340,13 +438,15 @@ describe Doorkeeper::TokensController do
       end
 
       context "authorized using valid Bearer token" do
-        it "responds with only active state" do
+        it "responds with invalid_token error" do
           request.headers["Authorization"] = "Bearer #{access_token.token}"
 
           post :introspect, params: { token: SecureRandom.hex(16) }
 
-          should_have_json "active", false
-          expect(json_response).not_to include("client_id", "token_type", "exp", "iat")
+          response_status_should_be 401
+
+          should_not_have_json "active"
+          should_have_json "error", "invalid_token"
         end
       end
     end

data/spec/dummy/config/initializers/doorkeeper.rb

@@ -107,32 +107,59 @@ Doorkeeper.configure do
   #   client.superapp? or resource_owner.admin?
   # end
 
-  # Implement constraints in case you use Client Credentials to authenticate
-  # the introspection endpoint.
-  # By default allow introspection if the introspected token belongs to authorized client,
-  # OR token doesn't belong to any client (public token). Otherwise disallow.
-  #
-  # Params:
-  # `token` - the token to be introspected (see Doorkeeper::AccessToken)
-  # `client` - the client application authorized for the endpoint (see Doorkeeper::Application)
-  #
-  # You can completely ignore it:
-  # allow_token_introspection do |_token, _client|
-  #   false
-  # end
+  # Configure custom constraints for the Token Introspection request.
+  # By default this configuration option allows to introspect a token by another
+  # token of the same application, OR to introspect the token that belongs to
+  # authorized client (from authenticated client) OR when token doesn't
+  # belong to any client (public token). Otherwise requester has no access to the
+  # introspection and it will return response as stated in the RFC.
+  #
+  # Block arguments:
+  #
+  # @param token [Doorkeeper::AccessToken]
+  #   token to be introspected
+  #
+  # @param authorized_client [Doorkeeper::Application]
+  #   authorized client (if request is authorized using Basic auth with
+  #   Client Credentials for example)
+  #
+  # @param authorized_token [Doorkeeper::AccessToken]
+  #   Bearer token used to authorize the request
   #
-  # Or you can define your custom check:
-  #   Adding `protected_resource` boolean column to applications table
-  #   to allow protected_resource client introspect the token of normal client.
-  #   In this case, protected resource client must be confidential.
+  # In case the block returns `nil` or `false` introspection responses with 401 status code
+  # when using authorized token to introspect, or you'll get 200 with { "active": false } body
+  # when using authorized client to introspect as stated in the
+  # RFC 7662 section 2.2. Introspection Response.
   #
-  # allow_token_introspection do |token, client|
-  #   if token.application
-  #     token.application == client || client.protected_resource?
+  # Using with caution:
+  # Keep in mind that these three parameters pass to block can be nil as following case:
+  #  `authorized_client` is nil if and only if `authorized_token` is present, and vice versa.
+  #  `token` will be nil if and only if `authorized_token` is present.
+  # So remember to use `&` or check if it is present before calling method on
+  # them to make sure you doesn't get NoMethodError exception.
+  #
+  # You can define your custom check:
+  #
+  # allow_token_introspection do |token, authorized_client, authorized_token|
+  #   if authorized_token
+  #     # customize: require `introspection` scope
+  #     authorized_token.application == token&.application ||
+  #       authorized_token.scopes.include?("introspection")
+  #   elsif token.application
+  #     # `protected_resource` is a new database boolean column, for example
+  #     authorized_client == token.application || authorized_client.protected_resource?
   #   else
+  #     # public token (when token.application is nil, token doesn't belong to any application)
   #     true
   #   end
   # end
+  #
+  # Or you can completely disable any token introspection:
+  #
+  # allow_token_introspection false
+  #
+  # If you need to block the request at all, then configure your routes.rb or web-server
+  # like nginx to forbid the request.
 
   # WWW-Authenticate Realm (default "Doorkeeper").
   realm "Doorkeeper"

data/spec/lib/oauth/client_credentials/creator_spec.rb

@@ -55,6 +55,7 @@ class Doorkeeper::OAuth::ClientCredentialsRequest
 
           expect(Doorkeeper::AccessToken.count).to eq(2)
           expect(result).not_to eq(existing_token)
+          expect(existing_token.reload).to be_revoked
         end
       end
 
@@ -69,6 +70,7 @@ class Doorkeeper::OAuth::ClientCredentialsRequest
 
           expect(Doorkeeper::AccessToken.count).to eq(2)
           expect(result).not_to eq(existing_token)
+          expect(existing_token.reload).to be_revoked
         end
       end
     end
@@ -82,6 +84,7 @@ class Doorkeeper::OAuth::ClientCredentialsRequest
 
         expect(Doorkeeper::AccessToken.count).to eq(2)
         expect(result).not_to eq(existing_token)
+        expect(existing_token.reload).to be_revoked
       end
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: doorkeeper
 version: !ruby/object:Gem::Version
-  version: 5.2.0.rc1
+  version: 5.2.0.rc2
 platform: ruby
 authors:
 - Felipe Elias Philipp
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-05-23 00:00:00.000000000 Z
+date: 2019-06-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -179,6 +179,7 @@ files:
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
 - Dangerfile
+- Dockerfile
 - Gemfile
 - MIT-LICENSE
 - NEWS.md