haveapi 0.17.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4799af18ce8de3147686153493e32210e780c650bdcec3e18f5ff714da50ee03
-  data.tar.gz: 4cfe8ff071d7d4ea6adcb28e25ab0d491008e9402058c34293bdf70881bf13e2
+  metadata.gz: fedb085c210494a3173ef597e44f63a280485cc0490bd0c0b74610d26d52e5b4
+  data.tar.gz: 372f4a9cb544426ad1e06c3bb60e26a50077b5e3bef70e7b77ac008ca5008aaa
 SHA512:
-  metadata.gz: 936f0c86ff2b766339c3dbc08d49c2ae46868002733124dad9987ad932f9232807160a6a36777fc6fe45b952682e89bf9b0a5856939d6a7a1775e94e9d8ffe4c
-  data.tar.gz: 3527985845485151a532aa42ce235eed35827f8d9f6a2aa053b208e7621ce4d93f578cd531f06aec8bcc27ecd1079c8023b7fc63f29bf36d4b6e38807121f0f6
+  metadata.gz: 6ab713fd64ead24d6a21095bda69ddbc536da56fdd26745c0c60721a8c9e5767addafdf7906a3c98a23401472106e83f8d341903291e4c5e3b1c08974c3f12b3
+  data.tar.gz: 58b3cfc406d09868675f07b51050c5b914368c1c4ee70dbd9cf919a6f2b7e9124133e0f6f33292822f69e614cd1090e6f605ba5179d0c98802d4b1023e09cc6e

data/haveapi.gemspec

@@ -23,6 +23,7 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'rake'
   s.add_runtime_dependency 'github-markdown'
   s.add_runtime_dependency 'nesty', '~> 1.0'
-  s.add_runtime_dependency 'haveapi-client', '~> 0.17.0'
+  s.add_runtime_dependency 'haveapi-client', '~> 0.18.0'
   s.add_runtime_dependency 'mail'
+  s.add_runtime_dependency 'rack-oauth2', '~> 2.2.0'
 end

data/lib/haveapi/authentication/base.rb

@@ -13,6 +13,10 @@ module HaveAPI
         end
       end
 
+      def self.inherited(subclass)
+        subclass.send(:instance_variable_set, '@auth_method', @auth_method)
+      end
+
       # @return [Symbol]
       attr_reader :name
 
@@ -23,6 +27,12 @@ module HaveAPI
         setup
       end
 
+      # Register custom path handlers in sinatra
+      # @param sinatra [Sinatra::Base]
+      # @param prefix [String]
+      def register_routes(sinatra, prefix)
+      end
+
       # @return [Module, nil]
       def resource_module
         nil

data/lib/haveapi/authentication/chain.rb

@@ -99,6 +99,8 @@ module HaveAPI::Authentication
       instance = p.new(@server, v)
       @instances[v] << instance
 
+      @server.add_auth_routes(v, instance, prefix: instance.name.to_s)
+
       if resource_module = instance.resource_module
         @server.add_auth_module(
           v,

data/lib/haveapi/authentication/oauth2/config.rb

@@ -0,0 +1,143 @@
+module HaveAPI::Authentication
+  module OAuth2
+    # Config passed to the OAuth2 provider
+    #
+    # Create your own subclass and pass it to {HaveAPI::Authentication::OAuth2.with_config}.
+    # The created provider can then be added to authentication chain.
+    #
+    # In general, it is up to the implementation to provide the authentication flow
+    # -- render HTML page in {#render_authorize_page} and then process it in
+    # {#handle_post_authorize}. The implementation must also handle generation
+    # of all needed tokens, their persistence and validity checking.
+    class Config
+      def initialize(provider, server, v)
+        @provider = provider
+        @server = server
+        @version = v
+      end
+
+      # Render authorization page
+      #
+      # This method can be called on both GET and POST requests, e.g. if the user
+      # provided incorrect credentials or if there are multiple authentication
+      # steps.
+      #
+      # It should return full HTML page that will be sent to the user. The page
+      # usually contains a login form.
+      #
+      # @param oauth2_request [Rack::OAuth2::Server::Authorize::Request]
+      # @param sinatra_params [Hash] request params
+      # @param client [Client]
+      # @param auth_result [AuthResult, nil]
+      # @return [String] HTML
+      def render_authorize_page(oauth2_request, sinatra_params, client, auth_result: nil)
+
+      end
+
+      # Handle POST requests made from {#render_authorize_page}
+      #
+      # Process form data and return {AuthResult} or nil. When nil is returned
+      # the authorization process is aborted and the user is redirected back
+      # to the client.
+      #
+      # @param sinatra_request [Sinatra::Request]
+      # @param sinatra_params [Hash] request params
+      # @param oauth2_request [Rack::OAuth2::Server::Authorize::Request]
+      # @param client [Client]
+      # @return [AuthResult, nil]
+      def handle_post_authorize(sinatra_request, sinatra_params, oauth2_request, client)
+
+      end
+
+      # Get oauth2 authorization code
+      #
+      # Called when the authentication is successful and complete. This method
+      # must generate and return authorization_code which is then sent to the
+      # client. It is up to the API implementation to persist the code.
+      #
+      # @param auth_res [AuthResult] value returned by {#handle_post_authorize}
+      # @return [String]
+      def get_authorization_code(auth_res)
+
+      end
+
+      # Get access token, its expiration date and optionally a refresh token
+      #
+      # The client has used the authorization_code returned by {#get_authorization_code}
+      # and now requests its access token. It is up to the implementation to create
+      # and persist the tokens. The authorization code should be invalidated.
+      #
+      # @param authorization [Authorization]
+      # @param sinatra_request [Sinatra::Request]
+      # @return [Array] access token, expiration date and optional refresh token
+      def get_tokens(authorization, sinatra_request)
+
+      end
+
+      # Refresh access token and optionally generate new refresh token
+      #
+      # The implementation should invalidate the current tokens and generate
+      # and persist new ones.
+      #
+      # @param authorization [Authorization]
+      # @param sinatra_request [Sinatra::Request]
+      # @return [Array] access token, expiration date and optional refresh token
+      def refresh_tokens(authorization, sinatra_request)
+
+      end
+
+      # Find client by ID
+      # @param client_id [String]
+      # @return [Client, nil]
+      def find_client_by_id(client_id)
+
+      end
+
+      # Find authorization by code
+      # @param client [Client]
+      # @param code [String]
+      # @return [Authorization, nil]
+      def find_authorization_by_code(client, code)
+
+      end
+
+      # Find authorization by refresh token
+      # @param client [Client]
+      # @param refresh_token [String]
+      # @return [Authorization, nil]
+      def find_authorization_by_refresh_token(client, refresh_token)
+
+      end
+
+      # Find user by the bearer token sent in HTTP header or as a query parameter
+      # @param sinatra_request [Sinatra::Request]
+      # @param access_token [String]
+      # @return [Object, nil] user
+      def find_user_by_access_token(request, access_token)
+
+      end
+
+      # Path to the authorization endpoint on this API
+      # @return [String]
+      def authorize_path
+        @provider.authorize_path
+      end
+
+      # Parameters needed for the authorization process
+      #
+      # Use these in {#render_authorization_page}, put them e.g. in hidden form
+      # fields.
+      #
+      # @return [Hash<String, String>]
+      def oauth2_params(req)
+        {
+          client_id: req.client_id,
+          response_type: req.response_type,
+          redirect_uri: req.redirect_uri,
+          scope: req.scope.join(' '),
+          state: req.state,
+        }
+      end
+    end
+  end
+end

data/lib/haveapi/authentication/oauth2/provider.rb

@@ -0,0 +1,231 @@
+require 'haveapi/authentication/base'
+require 'rack/oauth2'
+
+module HaveAPI::Authentication
+  module OAuth2
+    # Abstract class describing the client and what methods it must respond to
+    class Client
+      # @return [String]
+      attr_reader :client_id
+
+      # @return [String]
+      attr_reader :redirect_uri
+
+      # @param client_secret [String]
+      # @return [Boolean]
+      def check_secret(client_secret)
+        raise NotImplementedError
+      end
+    end
+
+    # Abstract class describing the authentication result and what methods it must respond to
+    class AuthResult
+      # True of the user was authenticated
+      # @return [Boolean]
+      attr_reader :authenticated
+
+      # True if the authentication process is complete, false if other steps are needed
+      # @return [Boolean]
+      attr_reader :complete
+
+      # True if the user asked to cancel the authorization process
+      # @return [Boolean]
+      attr_reader :cancel
+    end
+
+    # Abstract class describing ongoing authorization and what methods it must respond to
+    class Authorization
+      # @return [String]
+      attr_reader :redirect_uri
+
+      # @param redirect_uri [String]
+      # @return [Boolean]
+      def check_code_validity(redirect_uri)
+        raise NotImplementedError
+      end
+    end
+
+    # OAuth2 authentication and authorization provider
+    #
+    # Must be configured with {Config} using {OAuth2.with_config}.
+    class Provider < Base
+      auth_method :oauth2
+
+      # Configure the OAuth2 provider
+      # @param cfg [Config]
+      def self.with_config(cfg)
+        Module.new do
+          define_singleton_method(:new) do |*args|
+            Provider.new(*args, cfg)
+          end
+        end
+      end
+
+      # @return [String]
+      attr_reader :authorize_path
+
+      # @return [Config]
+      attr_reader :config
+
+      def initialize(server, v, cfg)
+        @config = cfg.new(self, server, v)
+        super(server, v)
+      end
+
+      def register_routes(sinatra, prefix)
+        @authorize_path = File.join(prefix, 'authorize')
+        @token_path = File.join(prefix, 'token')
+        that = self
+
+        sinatra.get @authorize_path do
+          that.authorization_endpoint(self).call(request.env)
+        end
+
+        sinatra.post @authorize_path do
+          that.authorization_endpoint(self).call(request.env)
+        end
+
+        sinatra.post @token_path do
+          that.token_endpoint(self).call(request.env)
+        end
+      end
+
+      def authenticate(request)
+        tokens = [
+          request['access_token'],
+          token_from_header(request)
+        ].compact
+
+        token =
+          case tokens.length
+          when 0
+            nil
+          when 1
+            tokens.first
+          else
+            fail 'Too many oauth2 tokens'
+          end
+
+        token && config.find_user_by_access_token(request, token)
+      end
+
+      def token_from_header(request)
+        auth_header = Rack::Auth::AbstractRequest.new(request.env)
+
+        if auth_header.provided? && !auth_header.parts.first.nil? && auth_header.scheme.to_s == 'bearer'
+          auth_header.params
+        else
+          nil
+        end
+      end
+
+      def describe
+        desc = <<-END
+        OAuth2 authorization provider. While OAuth2 is not supported by HaveAPI
+        clients, it is possible to use your API as an authentication source.
+
+        HaveAPI partially implements RFC 6749: authorization response type "code"
+        and token grant types "authorization_code" and "refresh_token". Other
+        response and grant types are not supported at this time.
+
+        The access token can be passed as bearer token according to RFC 6750.
+        END
+
+        {
+          description: desc,
+          authorize_path: @authorize_path,
+          token_path: @token_path,
+        }
+      end
+
+      def authorization_endpoint(handler)
+        Rack::OAuth2::Server::Authorize.new do |req, res|
+          client = config.find_client_by_id(req.client_id)
+          req.bad_request! if client.nil?
+
+          res.redirect_uri = req.verify_redirect_uri!(client.redirect_uri)
+
+          if req.post?
+            auth_res = config.handle_post_authorize(handler.request, handler.params, req, client)
+
+            if auth_res.nil?
+              # Authentication failed
+              req.access_denied!
+            elsif auth_res.cancel
+              # Cancel the process
+              req.access_denied!
+            elsif auth_res.authenticated && auth_res.complete
+              # Authentication was successful
+              case req.response_type
+              when :code
+                res.code = config.get_authorization_code(auth_res)
+              when :token
+                req.unsupported_response_type!
+              end
+
+              res.approve!
+            elsif auth_res.authenticated && !auth_res.complete
+              # Continue with another authentication step
+              res.content_type = 'text/html'
+              res.write(config.render_authorize_page(req, handler.params, client, auth_result: auth_res))
+            else
+              # Authentication failed, report errors and let the user retry
+              res.content_type = 'text/html'
+              res.write(config.render_authorize_page(req, handler.params, client, auth_result: auth_res))
+            end
+          else
+            res.content_type = 'text/html'
+            res.write(config.render_authorize_page(req, handler.params, client))
+          end
+        end
+      end
+
+      def token_endpoint(handler)
+        Rack::OAuth2::Server::Token.new do |req, res|
+          client = config.find_client_by_id(req.client_id)
+          req.invalid_client! if client.nil? || !client.check_secret(req.client_secret)
+
+          res.access_token =
+            case req.grant_type
+            when :authorization_code
+              authorization = config.find_authorization_by_code(client, req.code)
+
+              if authorization.nil? || authorization.check_code_validity(req.redirect_uri)
+                req.invalid_grant!
+              end
+
+              access_token, expires_at, refresh_token = config.get_tokens(authorization, handler.request)
+
+              bearer_token = Rack::OAuth2::AccessToken::Bearer.new(
+                access_token: access_token,
+                expires_in: expires_at - Time.now,
+              )
+              bearer_token.refresh_token = refresh_token if refresh_token
+              bearer_token
+
+            when :password
+              req.unsupported_grant_type!
+
+            when :client_credentials
+              req.unsupported_grant_type!
+
+            when :refresh_token
+              config.find_authorization_by_refresh_token(client, req.refresh_token)
+
+              access_token, expires_at, refresh_token = config.refresh_tokens(authorization, handler.request)
+
+              bearer_token = Rack::OAuth2::AccessToken::Bearer.new(
+                access_token: access_token,
+                expires_in: expires_at - Time.now,
+              )
+              bearer_token.refresh_token = refresh_token if refresh_token
+              bearer_token
+
+            else
+              req.unsupported_grant_type!
+            end
+        end
+      end
+    end
+  end
+end

data/lib/haveapi/authentication/oauth2.rb

@@ -0,0 +1,9 @@
+module HaveAPI::Authentication
+  module OAuth2
+    # Configure the oauth2 provider
+    # @param cfg [Config]
+    def self.with_config(cfg)
+      Provider.with_config(cfg)
+    end
+  end
+end

data/lib/haveapi/client_examples/curl.rb

@@ -42,6 +42,9 @@ $ curl --request OPTIONS \\
        --header '#{desc[:http_header]}: thetoken' \\
        '#{base_url}'
 END
+
+      when :oauth2
+        '# See RFC 6749 for authorization process and RFC 6750 for access token usage.'
       end
     end
 

data/lib/haveapi/client_examples/fs_client.rb

@@ -34,6 +34,9 @@ Password: secret
 # Note that the file system can read config file from haveapi-client, so if
 # you set up authentication there, the file system will use it.
 END
+
+      when :oauth2
+        '# OAuth2 is not supported by haveapi-fs.'
       end
     end
 

data/lib/haveapi/client_examples/http.rb

@@ -36,6 +36,25 @@ Host: #{host}
 Content-Type: application/json
 
 #{JSON.pretty_generate({token: login})}
+END
+
+      when :oauth2
+        <<END
+# 1) Request authorization code
+GET #{desc[:authorize_path]}?response_type=code&client_id=$client_id&state=$state&redirect_uri=$client_redirect_uri HTTP/1.1
+Host: #{host}
+
+# 2) The user logs in using this API
+
+# 3) The API then redirects the user back to the client application
+GET $client_redirect_uri?code=$authorization_code&state=$state
+Host: client-application
+
+# 4) The client application requests access token
+POST #{desc[:token_path]}
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=authorization_code&code=$authorization_code&redirect_uri=$client_redirect_uri&client_id=$client_id&client_secret=$client_secret
 END
       end
     end

data/lib/haveapi/client_examples/js_client.rb

@@ -49,6 +49,9 @@ api.authenticate("token", {
   console.log("Authenticated?", status);
 });
 END
+
+      when :oauth2
+        '// OAuth2 is not supported by HaveAPI JavaScript client.'
       end
     end
 

data/lib/haveapi/client_examples/php_client.rb

@@ -33,6 +33,9 @@ echo "Token = ".$api->getAuthenticationProvider()->getToken();
 // Next time, the client can authenticate using the token directly
 $api->authenticate("token", ["token" => $savedToken]);
 END
+
+      when :oauth2
+        '// OAuth2 is not supported by HaveAPI PHP client.'
       end
     end
 

data/lib/haveapi/client_examples/ruby_cli.rb

@@ -40,6 +40,9 @@ Password: secret
 # nor password and be authenticated
 #{init} user current
 END
+
+      when :oauth2
+        '# OAuth2 is not supported by HaveAPI Ruby CLI.'
       end
     end
 

data/lib/haveapi/client_examples/ruby_client.rb

@@ -36,6 +36,9 @@ puts "Token = \#{client.auth.token}"
 # Next time, the client can authenticate using the token directly
 client.authenticate(:token, token: saved_token)
 END
+
+      when :oauth2
+        '# OAuth2 is not supported by HaveAPI Ruby client.'
       end
     end
 

data/lib/haveapi/server.rb

@@ -576,6 +576,13 @@ module HaveAPI
       "#{@root}v#{v}/"
     end
 
+    # @param v [String] API version
+    # @param provider [Authentication::Base]
+    # @param prefix [String]
+    def add_auth_routes(v, provider, prefix: '')
+      provider.register_routes(@sinatra, "#{@root}_auth/#{prefix}")
+    end
+
     def add_auth_module(v, name, mod, prefix: '')
       @routes[v] ||= {authentication: {name => {resources: {}}}}
 

data/lib/haveapi/version.rb

@@ -1,4 +1,4 @@
 module HaveAPI
   PROTOCOL_VERSION = '2.0'
-  VERSION = '0.17.0'
+  VERSION = '0.18.0'
 end

data/lib/haveapi/views/version_page/auth_body.erb

@@ -10,6 +10,13 @@
     <dt>Query parameter:</dt>
     <dd><%= info[:query_parameter] %></dd>
   </dl>
+<% elsif name == :oauth2 %>
+  <dl>
+    <dt>Authorize path:</dt>
+    <dd><%= info[:authorize_path] %></dd>
+    <dt>Token path:</dt>
+    <dd><%= info[:token_path] %></dd>
+  </dl>
 <% end %>
 
 <% if info[:resources] %>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: haveapi
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.18.0
 platform: ruby
 authors:
 - Jakub Skokan
@@ -142,14 +142,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.17.0
+        version: 0.18.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.17.0
+        version: 0.18.0
 - !ruby/object:Gem::Dependency
   name: mail
   requirement: !ruby/object:Gem::Requirement
@@ -164,6 +164,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack-oauth2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.0
 description: Framework for creating self-describing APIs
 email: jakub.skokan@vpsfree.cz
 executables: []
@@ -193,6 +207,9 @@ files:
 - lib/haveapi/authentication/base.rb
 - lib/haveapi/authentication/basic/provider.rb
 - lib/haveapi/authentication/chain.rb
+- lib/haveapi/authentication/oauth2.rb
+- lib/haveapi/authentication/oauth2/config.rb
+- lib/haveapi/authentication/oauth2/provider.rb
 - lib/haveapi/authentication/token.rb
 - lib/haveapi/authentication/token/action_config.rb
 - lib/haveapi/authentication/token/action_request.rb