doorkeeper-device_authorization_grant 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 41a11fbc4e3f17a41ba597414e90d134d92f121ed56ee0ab3fbd3289d5a8c000
+  data.tar.gz: 7662d33b032f9293c09ebdcfeef4afc2e6fabdbb5da6adf36baf2ac48d2d1ab6
+SHA512:
+  metadata.gz: c7c692bfa261c432498e68a300f657ed532471f6c3414b8d7def3c1c27c1f0e3424a3ddba99c19d6eb274d6aecd8a5f6d14d5a593e651bdb659aa455498a8ccb
+  data.tar.gz: b7de6fc069d86e5c2ec3dd3e2f94dc645ffef57934747dd2d9d3ee30bc3a0c7b529632c57e215de3302988db49ef88e994f08eafdc161327c87268bbec205ddf

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2020 EXOP Group
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,320 @@
+# Doorkeeper::DeviceAuthorizationGrant
+
+OAuth 2.0 device authorization grant extension for Doorkeeper. 
+
+This library implements the OAuth 2.0 device authorization grant 
+([RFC 8628](https://tools.ietf.org/html/rfc8628)) for 
+[Ruby on Rails](https://rubyonrails.org/) applications on top of the
+[Doorkeeper](https://github.com/doorkeeper-gem/doorkeeper) OAuth 2.0 framework.
+
+## Status
+
+This extension currently works with Doorkeeper version `>= 5.4.0`.
+
+As of June 25 2020, due to some limitations of Doorkeeper, it is currently
+inconvenient for this Gem to use the official OAuth grant type
+`urn:ietf:params:oauth:grant-type:device_code`. Instead, it has been renamed
+to simply `device_code`, which is non-standard. This is going to be corrected
+soon: the next Doorkeeper release will include the ability to cleanly
+register custom Grant Flows - see [Doorkeeper Pull Request #1418](https://github.com/doorkeeper-gem/doorkeeper/pull/1418).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'doorkeeper-device_authorization_grant'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install doorkeeper-device_authorization_grant
+```
+
+Run the installation generator to update routes and create a dedicated initializer:
+
+```bash
+$ rails generate doorkeeper:device_authorization_grant:install
+```
+
+Generate a migration for Active Record (other ORMs are currently not supported):
+
+```bash
+$ rails doorkeeper_device_authorization_grant_engine:install:migrations
+```
+
+## Configuration
+
+### Doorkeeper configuration
+
+In your Doorkeeper initializer (usually `config/initializers/doorkeeper.rb`), enable
+the device flow extension grant type, adding to the `grant_flows` option the `device_code`
+string. For example:
+
+```ruby
+  # config/initializers/doorkeeper.rb
+  
+  Doorkeeper.configure do
+    # ... 
+  
+    grant_flows [
+      # Note: this is a non-standard grant flow, used instead of the
+      # official `urn:ietf:params:oauth:grant-type:device_code` due to
+      # current Doorkeeper limitations.
+      'device_code',
+ 
+      # together with all the other grant flows you already enabled, for example:
+      'authorization_code',
+      'client_credentials'
+      # ...
+    ]
+
+    # ...
+  end
+```
+
+Please note that **this is not the official grant flow**. The real one should be
+the IANA URN `urn:ietf:params:oauth:grant-type:device_code`, however this is hard
+to support with the current version of Doorkeeper, due to how strategy classes are
+looked up by grant type value.
+
+### Device Authorization Grant configuration
+
+The gem's installation scripts automatically creates a new initializer file:
+`config/initializers/doorkeeper_device_authorization_grant.rb`. Here you can
+adjust the configuration parameters according to your needs.
+
+### Routes
+
+The gem's installation scripts automatically modify your `config/routes.rb`
+file, adding the default routes to the controllers described above. The
+routes file should then look like this:
+
+```ruby
+Rails.application.routes.draw do
+  use_doorkeeper_device_authorization_grant
+  # your routes ...
+end
+```
+
+This is enough to add to your app the following default routes:
+
+```
+                               Prefix  Verb  URI                      Controller#Action
+            oauth_device_codes_create  POST  /oauth/authorize_device  doorkeeper/device_authorization_grant/device_codes#create
+    oauth_device_authorizations_index  GET   /oauth/device            doorkeeper/device_authorization_grant/device_authorizations#index
+oauth_device_authorizations_authorize  POST  /oauth/device            doorkeeper/device_authorization_grant/device_authorizations#authorize
+```
+
+The routing method `use_doorkeeper_device_authorization_grant` allows extra customization,
+just like `use_doorkeeper` (see [Doorkeeper Wiki - Customizing routes](https://github.com/doorkeeper-gem/doorkeeper/wiki/Customizing-routes)).
+
+This Gem defines two Rails controllers:
+
+- `DeviceCodesController` serves Device Authorization requests, as described
+  by [RFC 8628](https://tools.ietf.org/html/rfc8628), sections 3.1
+  and 3.2. 
+- `DeviceAuthorizationsController` provides a bare-bones implementation of a
+  verification web page which allows an authenticated resource-owner to
+  authorize a device, by providing an end-user code.
+
+You can change the controllers to your **custom controllers** with the `controller` option:
+
+```ruby
+Rails.application.routes.draw do
+  use_doorkeeper_device_authorization_grant do
+    # it accepts :device_authorizations and :device_codes
+    controller device_authorizations: 'custom_device_authorizations'
+  end
+end
+```
+
+Be sure to use the same superclasses of the original controllers (or something compatible).
+
+You can set **custom aliases** with `as`:
+
+```ruby
+Rails.application.routes.draw do
+  use_doorkeeper_device_authorization_grant do
+    # it accepts :device_authorizations and :device_codes
+    as device_codes: :custom_device
+  end
+end
+```
+
+You can **skip routes** with `skip_controllers`:
+
+```ruby
+Rails.application.routes.draw do
+  use_doorkeeper_device_authorization_grant do
+    # it accepts :device_authorizations and :device_codes
+    skip_controllers :device_authorizations
+  end
+end
+```
+
+The default scope is `oauth`. You can provide a **custom scope** like this:
+
+```ruby
+Rails.application.routes.draw do
+  use_doorkeeper_device_authorization_grant scope: 'oauth2'
+end
+```
+
+## Usage
+
+The following sections show the typical steps of a device authorization flow.
+Default configuration and routes are assumed.
+
+### Device Authorization Request
+
+Reference: [RFC 8628, section 3.1 - Device Authorization Request](https://tools.ietf.org/html/rfc8628#section-3.1).
+
+First of all, a *Device Client* can perform a *Device Authorization Request* to
+the *Authorization Server* (your Rails application, with Doorkeeper and this
+gem extension) like this:
+
+```http request
+POST /oauth/authorize_device HTTP/1.1
+Content-Type: application/x-www-form-urlencoded
+
+client_id=1406020730&scope=example_scope
+```
+
+### Device Authorization Response
+
+Reference: [RFC 8628, section 3.2 - Device Authorization Response](https://tools.ietf.org/html/rfc8628#section-3.2).
+
+The *Authorization Server* responds with a *Device Authorization Response*:
+
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+    "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
+    "user_code": "0A44L90H",
+    "verification_uri": "https://example.com/oauth/device",
+    "verification_uri_complete": "https://example.com/oauth/device?user_code=0A44L90H",
+    "expires_in": 300,
+    "interval": 5
+}
+``` 
+
+### User interaction
+
+Reference: [RFC 8628, section 3.3 - User Interaction](https://tools.ietf.org/html/rfc8628#section-3.3).
+
+The *Device Client* can now display to the end user the `user_code` and the
+`verification_uri` (or somehow make use of `verification_uri_complete`, in special cases).
+ 
+The user should visit  URI in a user agent on a secondary device (for example, in a browser
+on their mobile phone) and enter the user code.
+
+During the user interaction, the device continuously polls the token endpoint with the
+`device_code`, as detailed in the next section, until the user completes the interaction,
+the code expires, or another error occurs.
+
+The default Rails route provided by this Gem, `/oauth/device`, allows an authenticated
+request owner (for example, a user) to manually verify the user code.
+
+### Device Access Token Request / polling
+
+Reference: [RFC 8628, section 3.4 - Device Access Token Request](https://tools.ietf.org/html/rfc8628#section-3.4).
+
+After displaying instructions to the user, the *Device Client* should create a
+*Device Access Token Request* and send it to the token endpoint (provided
+by Dorkeeper), for example:
+
+```http request
+POST /oauth/token HTTP/1.1
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=device_code
+&device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS
+&client_id=1406020730
+```
+
+**Note:** this is a non-standard `grant_type`, used instead of the official 
+`urn:ietf:params:oauth:grant-type:device_code` due to current limitations of
+the Doorkeeper gem.
+
+The response to this request is defined in the next section. It is expected for
+the *Device Client* to try the access token request repeatedly in a polling
+fashion, based on the error code in the response. The polling time interval
+was possibly included in the *Device Authorization Response*, but it is
+optional; if no value was provided, the client MUST use 5 seconds as the default.
+
+### Device Access Token Response
+
+Reference: [RFC 8628, section 3.5 - Device Access Token Response](https://tools.ietf.org/html/rfc8628#section-3.5).
+
+Please refer to the RFC document for exhaustive documentation. Here we show just
+some possible responses.
+
+While the authorization request is still pending, and the device-code token is
+not expired, the response contains an `authorization_pending` error:
+
+```
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+
+{ "error": "authorization_pending", "error_description": "..." }
+```
+
+The client should simply continue with further polling requests.
+
+If the client requests are too close in time, a `slow_down` error is returned:
+
+```
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+
+{ "error": "slow_down", "error_description": "..." }
+```
+
+The client can still continue with polling requests, but the polling time interval
+MUST be increased by 5 seconds for all subsequent requests.
+
+If the `device_code` has expired, the response contains the `expired_token` error:
+
+```
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+
+{ "error": "expired_token", "error_description": "..." }
+```
+
+The client should stop polling, and may commence a new device authorization
+request (possibly upon waiting for further user interaction).
+
+Once the user has successfully authorized the device, a successful response will
+be eventually returned. This is a standard OAuth 2.0 response, described in
+[Section 5.1 of [RFC6749]](https://tools.ietf.org/html/rfc6749#section-5.1). Here
+is a typical bearer token response:
+
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+    "access_token": "FkPeBMF8Ab0zkYj6vQLZCxZ5OP0Hrd7ST3RS99x7nRM",
+    "token_type": "Bearer",
+    "expires_in": 7200,
+    "scope": "read",
+    "created_at": 1593096829
+}
+```
+
+The device authentication flow is now complete, and the token data can be used to
+authenticate requests against the authorization and/or resource server.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Doorkeeper::DeviceAuthorizationGrant'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path('test/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/app/controllers/doorkeeper/device_authorization_grant/device_authorizations_controller.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Doorkeeper
+  module DeviceAuthorizationGrant
+    # The Device Authorizations controller provides a simple interface which
+    # allows authenticated resource owners to authorize devices, by providing
+    # a user code.
+    class DeviceAuthorizationsController < Doorkeeper::ApplicationController
+      before_action :authenticate_resource_owner!
+
+      def index
+        respond_to do |format|
+          format.html
+          format.json { head :no_content }
+        end
+      end
+
+      def authorize
+        device_grant_model.transaction do
+          device_grant = device_grant_model.lock.find_by(user_code: user_code)
+          return authorization_error_response(:invalid_user_code) if device_grant.nil?
+          return authorization_error_response(:expired_user_code) if device_grant.expired?
+
+          device_grant.update!(user_code: nil, resource_owner_id: current_resource_owner.id)
+        end
+
+        authorization_success_response
+      end
+
+      private
+
+      def authorization_success_response
+        respond_to do |format|
+          notice = I18n.t(:success, scope: i18n_flash_scope(:authorize))
+          format.html { redirect_to oauth_device_authorizations_index_url, notice: notice }
+          format.json { head :no_content }
+        end
+      end
+
+      # @param error_message_key [Symbol]
+      def authorization_error_response(error_message_key)
+        respond_to do |format|
+          notice = I18n.t(error_message_key, scope: i18n_flash_scope(:authorize))
+          format.html { redirect_to oauth_device_authorizations_index_url, notice: notice }
+          format.json do
+            render json: { errors: [notice] }, status: :unprocessable_entity
+          end
+        end
+      end
+
+      # @return [Class]
+      def device_grant_model
+        @device_grant_model ||= Doorkeeper::DeviceAuthorizationGrant.configuration.device_grant_model
+      end
+
+      # @return [String, nil]
+      def user_code
+        params[:user_code]
+      end
+
+      # @param action [Symbol]
+      # @return [Array<Symbol>]
+      def i18n_flash_scope(action)
+        %I[doorkeeper flash device_codes #{action}]
+      end
+    end
+  end
+end