privy_wine_bouncer 1.0.4.5

data/README.md

@@ -0,0 +1,238 @@
+# WineBouncer
+
+Protect your precious Grape API with Doorkeeper.
+WineBouncer uses minimal modification, to make the magic happen.
+
+# Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Upgrading](#upgrading)
+- [Usage](#usage)
+  - [Easy DSL](#easy-dsl)
+  - [Authentication strategies](#authentication-strategies)
+    - [Default](#default)
+    - [Swagger](#swagger)
+    - [Protected](#protected)
+  - [Token information](#token-information)
+  - [Disable WineBouncer](#disable-winebouncer)
+- [Exceptions and Exception handling](#exceptions-and-exception-handling)
+- [Example Application](#example-application)
+- [Development](#development)
+- [Contributing](#contributing)
+
+## Requirements
+
+- Ruby > 2.1
+- Doorkeeper > 1.4.0 and < 5
+- Grape > 0.10 and < 1.2
+
+Please submit pull requests and Travis env bumps for newer dependency versions.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'privy_wine_bouncer'
+```
+
+And then execute:
+
+```ruby
+bundle
+```
+
+## Upgrading
+
+When upgrading from a previous version, see [UPGRADING](UPGRADING.md). You might also be interested at the [CHANGELOG](CHANGELOG.md).
+
+## Usage
+
+WineBouncer is a custom Grape Middleware used for Authentication and Authorization. We assume you have a Grape API mounted in your Rails application together with Doorkeeper.
+
+To get started with WineBouncer, run the configuration initializer:
+
+```shell
+$ rails g wine_bouncer:initializer
+```
+
+This creates a rails initializer in your Rails app at `config/initializers/wine_bouncer.rb` with the following configuration:
+
+```ruby
+WineBouncer.configure do |config|
+  config.auth_strategy = :default
+
+  config.define_resource_owner do
+    User.find(doorkeeper_access_token.resource_owner_id) if doorkeeper_access_token
+  end
+end
+```
+
+Then register WineBouncer as Grape middleware in your Grape API.
+
+```ruby
+class Api < Grape::API
+   default_format :json
+   format :json
+   use ::WineBouncer::OAuth2
+   mount YourAwesomeApi
+end
+```
+
+### Easy DSL
+
+WineBouncer comes with an easy DSL and relies on Grape's DSL extentions to define if an endpoint method should be protected.
+You can protect an endpoint by calling `oauth2` method with optional scopes in front of the endpoint definition.
+
+```ruby
+ class MyAwesomeAPI < Grape::API
+    desc 'protected method with required public scope'
+    oauth2 'public'
+    get '/protected' do
+       { hello: 'world' }
+    end
+
+    oauth2 'public'
+    get '/with_no_description' do
+       { hello: 'undescribed world' }
+    end
+
+    desc 'Unprotected method'
+    get '/unprotected' do
+      { hello: 'unprotected world' }
+    end
+
+    desc 'This method needs the public or private scope.'
+    oauth2 'public', 'write'
+    get '/method' do
+      { hello: 'public or private user.' }
+    end
+
+    desc 'This method uses Doorkeepers default scopes.',
+    oauth2
+    get '/protected_with_default_scope' do
+       { hello: 'protected unscoped world' }
+    end
+ end
+
+ class Api < Grape::API
+    default_format :json
+    format :json
+    use ::WineBouncer::OAuth2
+    mount MyAwesomeAPI
+ end
+```
+
+### Authentication strategies
+
+Behaviour of the authentication can be customized by selecting an authentication strategy. The following authentication strategies are provided in the gem.
+
+#### Default
+
+The default strategy only authenticates endpoints which are annotated by the `oauth2` method. Un-annotated endpoints still can be accessed without authentication.
+
+#### Swagger
+
+WineBouncer comes with a strategy that can be perfectly used with [grape-swagger](https://github.com/tim-vandecasteele/grape-swagger) with a syntax compliant with the [swagger spec](https://github.com/wordnik/swagger-spec/).
+This might be one of the simplest methods to protect your API and serve it with documentation. You can use [swagger-ui](https://github.com/wordnik/swagger-ui) to view your documentation.
+
+To get started ensure you also have included the `grape-swagger` gem in your gemfile.
+
+Run `bundle` to install the missing gems.
+
+Create a rails initializer in your Rails app at `config/initializers/wine_bouncer.rb` with the following configuration.
+
+```ruby
+WineBouncer.configure do |config|
+    config.auth_strategy = :swagger
+
+    config.define_resource_owner do
+            User.find(doorkeeper_access_token.resource_owner_id) if doorkeeper_access_token
+    end
+end
+```
+
+Then you can start protecting your API like the example below.
+
+```ruby
+desc 'This method needs the public or private scope.',
+  success: Api::Entities::Response,
+  failure: [
+      [401, 'Unauthorized', Api::Entities::Error],
+      [403, 'Forbidden', Api::Entities::Error]
+  ],
+  notes: <<-NOTE
+  Marked down notes!
+  NOTE
+oauth2 'public', 'write'
+get '/method' do
+  { hello: 'public or private user.' }
+end
+```
+
+The Swagger strategy uses scopes and injects them in the authorizations description for external application to be read.
+
+#### Protected
+
+The protected strategy is very similar to the default strategy except any public endpoint must explicitly set. To make an end point public, use `oauth2 false`.
+If the authorization method is not set, the end point is assumed to be **protected with Doorkeeper's default scopes** (which is the same as `oauth2 nil `.)
+To protect your endpoint with other scopes append the following method `oauth2 'first scope', 'second scope'`.
+
+### Token information
+
+WineBouncer comes with free extras! Methods for `resource_owner` and `doorkeeper_access_token` get included in your endpoints. You can use them to get the current resource owner, and the access_token object of doorkeeper.
+
+### Disable WineBouncer
+
+If you want to disable WineBouncer conditionally - e.g. in specs - you can add a block to the WineBouncer configuration. When this block evaluates to true, any request will be unprotected. For example:
+
+```{ruby}
+WineBouncer.configure do |config|
+  config.disable do
+    Rails.env.test?
+  end
+end
+```
+
+The block is newly evaluated for every request, so you could in principle have something like:
+
+```{ruby}
+config.disable do
+  [true, false].sample
+end
+```
+
+You probably shouldn't, though.
+
+## Exceptions and Exception handling
+
+This gem raises the following exceptions which can be handled in your Grape API, see [Grape documentation](https://github.com/intridea/grape#exception-handling).
+
+- `WineBouncer::Errors::OAuthUnauthorizedError`
+  when the request is unauthorized.
+- `WineBouncer::Errors::OAuthForbiddenError`
+  when the token is found but scopes do not match.
+
+Detailed doorkeeper error response can be found in the error's `response` attribute. You could use
+it to compose the actual HTTP response to API users.
+
+## Example/Template Application
+
+A full working sample app (or starter template) can be found at [grape-doorkeeper on github](https://github.com/sethherr/grape-doorkeeper). It has one click deploy to Heroku and [a live example](https://grape-doorkeeper.herokuapp.com/).
+
+## Development
+
+Since we want the gem tested against several rails versions we use the same way to prepare our development environment as Doorkeeper.
+
+To install the development environment for rails 4.2.6, you can also specify a different rails version to test against.
+
+`rails=4.2.6 bundle install`
+
+To run the specs.
+
+`rails=4.2.6 bundle exec rake`
+
+## Contributing
+
+For contributing to the gem see [CONTRIBUTING](CONTRIBUTING.md).

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+
+desc 'Default: Run all specs.'
+task default: :spec
+
+desc 'Run all specs'
+RSpec::Core::RakeTask.new(:spec)

data/UPGRADING.md

@@ -0,0 +1,62 @@
+Upgrading WineBouncer
+=====================
+
+
+## Upgrading to >= 1.0
+
+No DSL changes have been made. This is just a stability release from we can work to next releases.
+
+
+## Upgrading to >= 0.5.0
+
+WineBouncer's exceptions `OAuthUnauthorizedError` and `OAuthForbiddenError` now come with a
+corresponding Doorkeeper's error response. You can access it via `response` method of the exception.
+For backward compatible, you can still use `message` but the content will be provided by Doorkeeper
+error response's description.
+
+## Upgrading to >=  0.3.0
+
+An new DSL has been introduced to WineBouncer. This DSL will become the preferred way to authorize your endpoints.
+The authentication trough endpoint description will become deprecated in the future version.
+
+The old way to authorize your endpoints:
+
+```
+  desc 'protected method with required public and private scope',
+  auth: { scopes: ['public','private'] }
+  get '/protected' do
+     { hello: 'world' }
+  end
+```
+
+You may now write:
+```
+  desc 'protected method with required public and private scope'
+  oauth2 'public', 'private'
+  get '/protected' do
+     { hello: 'world' }
+  end
+```
+
+And even remove the description.
+
+Note this is the last version that will support Grape 0.8 and 0.9. Grape 0.10 will be the next minimum Grape version.
+
+### Upgrading to >= 0.2.0
+
+To use the `resource_owner` you now need to define how WineBouncer gets the resource owner. In most cases he needs to return the User that is logged in, but not in all cases.
+You now additionally need to specify `define_resource_owner` in your configuration. Mostly this the following code will work:
+
+``` ruby
+WineBouncer.configure do |c|
+  .......
+  c.define_resource_owner do
+    User.find(doorkeeper_access_token.resource_owner_id) if doorkeeper_access_token
+  end
+end
+```
+
+The required Grape version is now from 0.8 and above.
+
+------
+From version 0.1.0 upgrade instructions are given.

data/lib/generators/templates/wine_bouncer.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+WineBouncer.configure do |config|
+  config.auth_strategy = :default
+
+  config.define_resource_owner do
+    User.find(doorkeeper_access_token.resource_owner_id) if doorkeeper_access_token
+  end
+end

data/lib/generators/wine_bouncer/initializer_generator.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module WineBouncer
+  module Generators
+    class InitializerGenerator < ::Rails::Generators::Base
+      source_root File.expand_path('../../templates', __FILE__)
+
+      desc 'Creates a sample WineBouncer initializer.'
+      def copy_initializer
+        copy_file 'wine_bouncer.rb', 'config/initializers/wine_bouncer.rb'
+      end
+    end
+  end
+end

data/lib/privy_wine_bouncer.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'wine_bouncer'

data/lib/wine_bouncer/auth_methods/auth_methods.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module WineBouncer
+  module AuthMethods
+
+    def protected_endpoint=(protected)
+      @protected_endpoint = protected
+    end
+
+    def protected_endpoint?
+      @protected_endpoint || false
+    end
+
+    def resource_owner
+       instance_eval(&WineBouncer.configuration.defined_resource_owner)
+    end
+
+    def client_credential_token?
+      has_doorkeeper_token? && doorkeeper_access_token.resource_owner_id.nil?
+    end
+
+    def doorkeeper_access_token
+      @_doorkeeper_access_token
+    end
+
+    def doorkeeper_access_token=(token)
+      @_doorkeeper_access_token = token
+    end
+
+    def has_doorkeeper_token?
+      !@_doorkeeper_access_token.nil?
+    end
+
+    def has_resource_owner?
+      has_doorkeeper_token? && !!doorkeeper_access_token.resource_owner_id
+    end
+  end
+end

data/lib/wine_bouncer/auth_strategies/default.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module WineBouncer
+  module AuthStrategies
+    class Default < ::WineBouncer::BaseStrategy
+      def endpoint_protected?
+        !!endpoint_authorizations
+      end
+
+      def has_auth_scopes?
+        !!endpoint_authorizations &&
+            endpoint_authorizations.key?(:scopes) &&
+            !endpoint_authorizations[:scopes].empty?
+      end
+
+      def auth_scopes
+        endpoint_authorizations[:scopes].map(&:to_sym)
+      end
+
+      private
+
+      def endpoint_authorizations
+          api_context.options[:route_options][:auth]
+      end
+    end
+  end
+end

data/lib/wine_bouncer/auth_strategies/protected.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module WineBouncer
+  module AuthStrategies
+    class Protected < WineBouncer::BaseStrategy
+      def endpoint_protected?
+        has_authorizations?
+      end
+
+      def has_auth_scopes?
+        endpoint_authorizations &&
+          endpoint_authorizations.key?(:scopes) &&
+          endpoint_authorizations[:scopes].any?
+      end
+
+      def auth_scopes
+        endpoint_authorizations[:scopes].map(&:to_sym)
+      end
+
+      private
+
+      def nil_authorizations?
+        endpoint_authorizations.nil?
+      end
+
+      # returns true if an authorization hash has been found
+      # First it checks for the old syntax, then for the new.
+      def has_authorizations?
+        (nil_authorizations? || !!endpoint_authorizations) && scope_keys?
+      end
+
+      # if false or nil scopes are entered the authorization should be skipped.
+      # nil_authorizations? is used to check against the legacy hash.
+      def scope_keys?
+        nil_authorizations? || endpoint_authorizations[:scopes] != [false]
+      end
+
+      def endpoint_authorizations
+        api_context.options[:route_options][:auth]
+      end
+    end
+  end
+end

data/lib/wine_bouncer/auth_strategies/swagger.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module WineBouncer
+  module AuthStrategies
+    class Swagger < ::WineBouncer::BaseStrategy
+      def endpoint_protected?
+        has_authorizations? && !!authorization_type_oauth2
+      end
+
+      def has_auth_scopes?
+        endpoint_protected? && !authorization_type_oauth2.empty?
+      end
+
+      def auth_scopes
+        authorization_type_oauth2.map { |hash| hash[:scope].to_sym }
+      end
+
+      private
+
+      def has_authorizations?
+        !!endpoint_authorizations
+      end
+
+      def endpoint_authorizations
+         api_context.options[:route_options][:authorizations]
+      end
+
+      def authorization_type_oauth2
+        endpoint_authorizations[:oauth2]
+      end
+    end
+  end
+end

data/lib/wine_bouncer/base_strategy.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module WineBouncer
+  class BaseStrategy
+    attr_accessor :api_context
+  end
+end

data/lib/wine_bouncer/configuration.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module WineBouncer
+
+  class << self
+    attr_accessor :configuration
+  end
+
+  class Configuration
+    attr_accessor :auth_strategy
+    attr_accessor :defined_resource_owner
+    attr_writer :auth_strategy
+
+    def auth_strategy
+      @auth_strategy || :default
+    end
+
+    def require_strategies
+      require "wine_bouncer/auth_strategies/#{auth_strategy}"
+    end
+
+    def define_resource_owner &block
+      raise(ArgumentError, 'define_resource_owner expects a block in the configuration') unless block_given?
+      @defined_resource_owner = block
+    end
+
+    def defined_resource_owner
+      raise(Errors::UnconfiguredError, 'Please define define_resource_owner to configure the resource owner') unless @defined_resource_owner
+      @defined_resource_owner
+    end
+
+    # when the block evaluates to true, WineBouncer should be disabled
+    # if no block is provided, WineBouncer is always enabled
+    def disable(&block)
+      @disable_block = block
+    end
+
+    def disable_block
+      @disable_block || ->() { false }
+    end
+  end
+
+  def self.configuration
+    @config || raise(Errors::UnconfiguredError.new)
+  end
+
+  def self.configuration=(config)
+    @config = config
+    @config.require_strategies
+  end
+
+  ###
+  # Configure block.
+  # Requires all strategy specific files.
+  ###
+  def self.configure
+    yield(config)
+    config.require_strategies
+    config
+  end
+
+  private_class_method
+
+  ###
+  # Returns a new configuration or existing one.
+  ###
+  def self.config
+    @config ||= Configuration.new
+  end
+end

data/lib/wine_bouncer/errors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module WineBouncer
+  module Errors
+    class UnconfiguredError < StandardError; end
+
+    class OAuthUnauthorizedError < StandardError
+      attr_reader :response
+      def initialize(response)
+        super(response.try(:description))
+        @response = response
+      end
+    end
+
+    class OAuthForbiddenError < StandardError
+      attr_reader :response
+      def initialize(response)
+        super(response.try(:description))
+        @response = response
+      end
+    end
+  end
+end

data/lib/wine_bouncer/extension.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module WineBouncer
+  module Extension
+    def oauth2(*scopes)
+      scopes = Doorkeeper.configuration.default_scopes.all if scopes.all? { |x| x.nil? }
+      description = if respond_to?(:route_setting) # >= grape-0.10.0
+                      route_setting(:description) || route_setting(:description, {})
+                    else
+                      @last_description ||= {}
+                    end
+      # case WineBouncer.configuration.auth_strategy
+      # when :default
+      description[:auth] = { scopes: scopes }
+      # when :swagger
+      description[:authorizations] = { oauth2: scopes.map { |x| { scope: x } } }
+      # end
+    end
+
+    # Grape::API::Instance is defined in grape 1.2.0 or above
+    grape_api = defined?(Grape::API::Instance) ? Grape::API::Instance : Grape::API
+    grape_api.extend self
+  end
+end