flexmls_api 0.3.6 → 0.4.5

data/Gemfile

@@ -1,11 +1,11 @@
 source :rubygems
 
-gem 'faraday'
-gem 'curb'
-gem 'faraday_middleware'
-gem 'multi_json'
-gem 'json'
-gem 'yajl-ruby'
+gem 'curb', '0.7.8'
+gem 'faraday', '0.5.3'
+gem 'faraday_middleware', '0.3.1'
+gem 'multi_json', '0.0.5'
+gem 'json', '1.4.6'
+gem 'yajl-ruby', '0.7.8'
 gem 'builder', '2.1.2'
 
 gem 'will_paginate', '~> 3.0.pre2'

data/Gemfile.lock

@@ -46,15 +46,15 @@ PLATFORMS
 DEPENDENCIES
   builder (= 2.1.2)
   ci_reporter (>= 1.6.3)
-  curb
-  faraday
-  faraday_middleware
+  curb (= 0.7.8)
+  faraday (= 0.5.3)
+  faraday_middleware (= 0.3.1)
   jeweler
-  json
-  multi_json
+  json (= 1.4.6)
+  multi_json (= 0.0.5)
   rcov
   rspec
   typhoeus
   webmock
   will_paginate (~> 3.0.pre2)
-  yajl-ruby
+  yajl-ruby (= 0.7.8)

data/README.md

@@ -34,9 +34,13 @@ Usage Examples
 
 Authentication
 --------------
-Authentication is handled transparently by the request framework in the gem, so you should never need to manually make an authentication request.
+Authentication is handled transparently by the request framework in the gem, so you should never need to manually make an authentication request.  More than one mode of authentication is supported, so the client needs to be configured accordingly.
 
+#### API Authentication (Default)
+Usually supplied for a single user, this authentication mode is the simplest, and is setup as the default.  The example usage above demonstrates how to get started using this authentication mode.
 
+#### OAuth2 Authentication
+Authentication mode the separates application and user authentication.  This mode requires further setup which is described in lib/flexmls_api/authentication/oauth2.rb
 
 Error Codes
 ---------------------
@@ -124,5 +128,3 @@ Error Codes
   </tbody>
 </table>
 
-
-

data/Rakefile

@@ -14,7 +14,8 @@ begin
     gemspec.email = "api-support@flexmls.com"
     gemspec.homepage = "https://github.com/flexmls/flexmls_api"
     gemspec.authors = ["Brandon Hornseth", "Wade McEwen"]
-    gemspec.files =  FileList["[A-Z]*", "{lib,spec}/**/*"]
+    # Need to skip spec/reports for CI builds
+    gemspec.files =  FileList["[A-Z]*", "{lib,spec/fixtures,spec/unit}/**/*", "spec/*.rb"]
     gemspec.add_development_dependency "rspec"
     gemspec.add_development_dependency "jeweler"
     gemspec.add_development_dependency "curb"

data/VERSION

@@ -1 +1 @@
-0.3.6
+0.4.5

data/lib/flexmls_api/authentication.rb

@@ -1,11 +1,18 @@
+
 require 'openssl'
 require 'faraday'
 require 'faraday_middleware'
 require 'yajl'
 require 'date'
+
+require File.expand_path('../authentication/base_auth', __FILE__)
+require File.expand_path('../authentication/api_auth', __FILE__)
+require File.expand_path('../authentication/oauth2', __FILE__)
+
 module FlexmlsApi
-  # =API Authentication
-  # Handles authentication and reauthentication to the flexmls api.
+  # =Authentication
+  # Mixin module for handling client authentication and reauthentication to the flexmls api.  Makes 
+  # use of the configured authentication mode (API Auth by default).
   module Authentication
 
     # Main authentication step.  Run before any api request unless the user session exists and is 
@@ -16,58 +23,32 @@ module FlexmlsApi
     # *raises*
     #   FlexmlsApi::ClientError when authentication fails
     def authenticate
-      sig = sign("#{@api_secret}ApiKey#{@api_key}")
-      FlexmlsApi.logger.debug("Authenticating to #{@endpoint}")
       start_time = Time.now
-      request_path = "/#{version}/session?ApiKey=#{api_key}&ApiSig=#{sig}"
-      resp = connection(true).post request_path, ""
       request_time = Time.now - start_time
-      FlexmlsApi.logger.info("[#{(request_time * 1000).to_i}ms] Api: POST #{request_path}")
-      @session = Session.new(resp.body.results[0])
-      FlexmlsApi.logger.debug("Authentication: #{@session.inspect}")
-      @session
+      new_session = @authenticator.authenticate
+      FlexmlsApi.logger.info("[#{(request_time * 1000).to_i}ms]")
+      FlexmlsApi.logger.debug("Session: #{new_session.inspect}")
+      new_session
+    end
+
+    # Test to see if there is an active session
+    def authenticated?
+      @authenticator.authenticated?
     end
     
     # Delete the current session
     def logout
       FlexmlsApi.logger.info("Logging out.")
-      delete("/session/#{@session.auth_token}") unless @session.nil?
-      @session = nil
+      @authenticator.logout
     end
 
-    # Active session object
+    # Fetch the active session object
     def session
-      @session
-    end
-    
-    # Builds an ordered list of key value pairs and concatenates it all as one big string.  Used 
-    # specifically for signing a request.
-    def build_param_string(param_hash)
-      return "" if param_hash.nil?
-        sorted = param_hash.sort do |a,b|
-          a.to_s <=> b.to_s
-        end
-        params = ""
-        sorted.each do |key,val|
-          params += key.to_s + val.to_s
-        end
-        params
+      @authenticator.session
     end
-    
-    # ==Session class
-    # Handle on the api user session information as return by the api session service, including 
-    # roles, tokens and expiration
-    class Session
-      attr_accessor :auth_token, :expires, :roles 
-      def initialize(options={})
-        @auth_token = options["AuthToken"]
-        @expires = DateTime.parse options["Expires"]
-        @roles = options["Roles"]
-      end
-      #  Is the user session token expired?
-      def expired?
-        DateTime.now > @expires
-      end
+    # Save the active session object
+    def session=(active_session)
+      @authenticator.session=active_session
     end
     
     # Main connection object for running requests.  Bootstraps the Faraday abstraction layer with 
@@ -92,7 +73,7 @@ module FlexmlsApi
       conn
     end
     
-    # HTTP request headers
+    # HTTP request headers for client requests
     def headers
       {
         :accept => 'application/json',
@@ -102,15 +83,5 @@ module FlexmlsApi
       }
     end
     
-    # Sign a request
-    def sign(sig)
-      Digest::MD5.hexdigest(sig)
-    end
-
-    # Sign a request with request data.
-    def sign_token(path, params = {}, post_data="")
-      sign("#{@api_secret}ApiKey#{@api_key}ServicePath/#{version}#{path}#{build_param_string(params)}#{post_data}")
-    end
-    
   end
 end

data/lib/flexmls_api/authentication/api_auth.rb

@@ -0,0 +1,100 @@
+module FlexmlsApi
+
+  module Authentication
+
+    #=API Authentication
+    # Auth implementation for the API's original hash based authentication design.  This is the 
+    # default authentication strategy used by the client.  API Auth rely's on the user's API key
+    # and secret and the active user is tied to the key owner.  
+    
+    #==ApiAuth
+    # Implementation the BaseAuth interface for API style authentication  
+    class ApiAuth < BaseAuth
+      
+      def initialize(client)
+        @client = client
+      end
+      
+      def authenticate
+        sig = sign("#{@client.api_secret}ApiKey#{@client.api_key}")
+        FlexmlsApi.logger.debug("Authenticating to #{@client.endpoint}")
+        start_time = Time.now
+        request_path = "/#{@client.version}/session?ApiKey=#{@client.api_key}&ApiSig=#{sig}"
+        resp = @client.connection(true).post request_path, ""
+        request_time = Time.now - start_time
+        FlexmlsApi.logger.info("[#{(request_time * 1000).to_i}ms] Api: POST #{request_path}")
+        @session = Session.new(resp.body.results.first)
+        FlexmlsApi.logger.debug("Authentication: #{@session.inspect}")
+        @session
+      end
+      
+      def logout
+        @client.delete("/session/#{@session.auth_token}") unless @session.nil?
+        @session = nil
+      end
+      
+      # Builds an ordered list of key value pairs and concatenates it all as one big string.  Used 
+      # specifically for signing a request.
+      def build_param_string(param_hash)
+        return "" if param_hash.nil?
+          sorted = param_hash.sort do |a,b|
+            a.to_s <=> b.to_s
+          end
+          params = ""
+          sorted.each do |key,val|
+            params += key.to_s + val.to_s
+          end
+          params
+      end
+
+      # Sign a request
+      def sign(sig)
+        Digest::MD5.hexdigest(sig)
+      end
+  
+      # Sign a request with request data.
+      def sign_token(path, params = {}, post_data="")
+        sign("#{@client.api_secret}ApiKey#{@client.api_key}ServicePath#{path}#{build_param_string(params)}#{post_data}")
+      end
+      
+      # Perform an HTTP request (no data)
+      def request(method, path, body, options)
+        request_opts = {
+          "AuthToken" => @session.auth_token
+        }
+        unless @client.api_user.nil?
+          request_opts.merge!(:ApiUser => "#{@client.api_user}")
+        end
+        request_opts.merge!(options)
+        sig = sign_token(path, request_opts, body)
+        request_path = "#{path}?#{build_url_parameters({"ApiSig"=>sig}.merge(request_opts))}"
+        FlexmlsApi.logger.debug("Request: #{request_path}")
+        if body.nil?
+          response = @client.connection.send(method, request_path)
+        else
+          FlexmlsApi.logger.debug("Data: #{body}")
+          response = @client.connection.send(method, request_path, body)
+        end
+        response
+      end
+      
+    end
+    
+    # ==Session class
+    # Handle on the api user session information as return by the api session service, including 
+    # roles, tokens and expiration
+    class Session
+      attr_accessor :auth_token, :expires, :roles 
+      def initialize(options={})
+        @auth_token = options["AuthToken"]
+        @expires = DateTime.parse options["Expires"]
+        @roles = options["Roles"]
+      end
+      #  Is the user session token expired?
+      def expired?
+        DateTime.now > @expires
+      end
+    end
+
+  end
+end

data/lib/flexmls_api/authentication/base_auth.rb

@@ -0,0 +1,47 @@
+module FlexmlsApi
+
+  module Authentication
+    #=Authentication Base
+    # This base class defines the basic interface supported by all client authentication 
+    # implementations.
+    class BaseAuth
+      attr_accessor :session
+      # All ihheriting classes should accept the flexmls_api client as a part of initialization
+      def initialize(client)
+        @client = client
+      end
+      
+      # Perform requests to authenticate the client with the API
+      def authenticate
+        raise "Implement me!"
+      end
+
+      # Called prior to running authenticate (except in case of api authentication errors)
+      def authenticated?
+        !(session.nil? || session.expired?)
+      end
+      
+      # Terminate the active session
+      def logout
+        raise "Implement me!"
+      end
+        
+      # Perform an HTTP request (no data)
+      def request(method, path, body, options)
+        raise "Implement me!"
+      end
+      
+      # Format a hash as request parameters
+      # 
+      # :returns:
+      #   Stringized form of the parameters as needed for an HTTP request
+      def build_url_parameters(parameters={})
+        array = parameters.map do |key,value|
+          escaped_value = CGI.escape("#{value}")
+          "#{key}=#{escaped_value}"
+        end
+        array.join "&"
+      end
+    end
+  end
+end

data/lib/flexmls_api/authentication/oauth2.rb

@@ -0,0 +1,219 @@
+require 'uri'
+
+module FlexmlsApi
+
+  module Authentication
+    #=OAuth2 Authentication
+    # Auth implementation to the API using the OAuth2 service endpoint.  Current adheres to the 10 
+    # draft of the OAuth2 specification.  With OAuth2, the application supplies credentials for the 
+    # application, and a separate a user authentication flow dictactes the active user for 
+    # requests.
+    #
+    #===Setup
+    # When using this authentication method, there is a bit more setup involved to make the client
+    # work.  All applications need to extend the BaseOAuth2Provider class to supply the application
+    # specific configuration.  Also depending on the application type (command line, native, or web 
+    # based), the user authentication step will be handled differently.
+    
+    #==OAuth2
+    # Implementation the BaseAuth interface for API style authentication  
+    class OAuth2 < BaseAuth
+      
+      def session
+        @provider.load_session()
+      end
+      def session=(s)
+        @provider.save_session(s)
+      end
+      
+      def initialize(client)
+        @client = client
+        @provider = client.oauth2_provider
+      end
+      
+      # Generate the appropriate request uri for authorizing this application for current user.
+      def authorization_url
+        params = {
+          "client_id" => @provider.client_id,
+          "response_type" => "code",
+          "redirect_uri" => @provider.redirect_uri
+        }
+        "#{@provider.authorization_uri}?#{build_url_parameters(params)}"
+      end
+      
+      def token_params
+        params = {
+          "client_id" => @provider.client_id,
+          "client_secret" => @provider.client_secret,
+          "grant_type" => "authorization_code",
+          "code" => @provider.code,
+          "redirect_uri" => @provider.redirect_uri
+        }
+        "?#{build_url_parameters(params)}"
+      end
+      
+      def authenticate
+        if(@provider.code.nil?)
+          FlexmlsApi.logger.debug("Redirecting to provider to get the authorization code")
+          @provider.redirect(authorization_url)
+        end
+        FlexmlsApi.logger.debug("Authenticating to #{@provider.access_uri}")
+        uri = URI.parse(@provider.access_uri)
+        request_path = "#{uri.path}#{token_params}"
+        response = oauth_access_connection("#{uri.scheme}://#{uri.host}").post(request_path, "").body
+        response.expires_in = @provider.session_timeout if response.expires_in.nil?
+        self.session=response
+        response
+      end
+      
+      # Perform an HTTP request (no data)
+      def request(method, path, body, options)
+        connection = @client.connection(true)  # SSL Only!
+        connection.headers.merge!(self.auth_header)
+        request_opts = {}
+        request_opts.merge!(options)
+        request_path = "#{path}?#{build_url_parameters({:access_token => session.access_token}.merge(options))}"
+        FlexmlsApi.logger.debug("Request: #{request_path}")
+        if body.nil?
+          response = connection.send(method, request_path)
+        else
+          FlexmlsApi.logger.debug("Data: #{body}")
+          response = connection.send(method, request_path, body)
+        end
+        response
+      end
+      
+      def logout
+        @provider.save_session(nil)
+      end
+
+            
+      protected
+      
+      def auth_header
+        {"Authorization"=> "OAuth #{session.access_token}"}
+      end
+      
+      # Setup a faraday connection for dealing with an OAuth2 endpoint
+      def oauth_access_connection(endpoint)
+        opts = {
+          :headers => @client.headers
+        }
+        opts[:ssl] = {:verify => false }
+        opts[:url] = endpoint       
+        conn = Faraday::Connection.new(opts) do |builder|
+          builder.adapter Faraday.default_adapter
+          builder.use Faraday::Response::ParseJson
+          builder.use FlexmlsApi::Authentication::FlexmlsOAuth2Middleware
+        end
+      end
+    end
+    
+    # Representation of a session with the api using oauth2
+    class OAuthSession
+      attr_accessor :access_token, :expires_in, :scope, :refresh_token
+      def initialize(options={})
+        @access_token = options["access_token"]
+        # TODO The current oauth2 service does not send an expiration time.  I'm setting it to default to 1 hour.
+        @expires_in = options["expires_in"]
+        @scope = options["scope"]
+        @refresh_token = options["refresh_token"]
+        @start_time = DateTime.now
+      end
+      #  Is the user session token expired?
+      def expired?
+        @start_time + Rational(@expires_in, 24*60*60) < DateTime.now
+      end
+    end
+    
+    #=OAuth2 configuration provider for applications
+    # Applications planning to use OAuth2 authentication with the API must extend this class as 
+    # part of the client configuration, providing values for the following attributes:
+    #  @authorization_uri - User oauth2 login page for flexmls
+    #  @access_uri - Location of the OAuth2 access token resource for the api.  OAuth2 code and 
+    #    credentials will be sent to this uri to generate an access token.
+    #  @redirect_uri - Application uri to redirect to 
+    #  @client_id - OAuth2 provided application identifier
+    #  @client_secret - OAuth2 provided password for the client id
+    class BaseOAuth2Provider
+      
+      attr_accessor :authorization_uri, :code, :access_uri, :redirect_uri, :client_id, :client_secret
+
+      # Application using the client must handle user redirect for user authentication.  For 
+      # command line applications, this method is called prior to initial client requests so that  
+      # the process can notify the user to go to the url and retrieve the access_code for the app.  
+      # In a web based web application, this method can be mostly ignored.  However, the web based 
+      # application is then responsible for ensuring the code is saved to the the provider instance  
+      # prior to any client requests are performed (or the error below will be thrown). 
+      def redirect(url)
+        raise "To be implemented by client application"
+      end
+      
+      #==For any persistence to be supported outside application process, the application shall 
+      # implement the following methods for storing and retrieving the user OAuth2 session 
+      # (e.g. to and from memcached).
+      
+      # Load the current OAuth session
+      # returns - active OAuthSession or nil
+      def load_session
+        nil
+      end
+      
+      # Save current session
+      # session - active OAuthSession
+      def save_session(session)
+        
+      end
+      
+      # Provides a default session time out
+      # returns - the session timeout length (in seconds)
+      def session_timeout
+        3600
+      end
+      
+    end
+
+    #==OAuth2 Faraday response middleware
+    # HTTP Response after filter to package oauth2 responses and bubble up basic api errors.
+    class FlexmlsOAuth2Middleware < Faraday::Response::Middleware
+      begin
+        def self.register_on_complete(env)
+          env[:response].on_complete do |finished_env|
+            validate_and_build_response(finished_env)
+          end
+        end
+      rescue LoadError, NameError => e
+        self.load_error = e
+      end
+      
+      def self.validate_and_build_response(finished_env)
+        body = finished_env[:body]
+        FlexmlsApi.logger.debug("Response Body: #{body.inspect}")
+        unless body.is_a?(Hash)
+          raise InvalidResponse, "The server response could not be understood"
+        end
+        case finished_env[:status]
+        when 200..299
+          FlexmlsApi.logger.debug("Success!")
+          session = OAuthSession.new(body)
+        else 
+          # Handle the WWW-Authenticate Response Header Field if present. This can be returned by 
+          # OAuth2 implementations and wouldn't hurt to log.
+          auth_header_error = finished_env[:request_headers]["WWW-Authenticate"]
+          FlexmlsApi.logger.warn("Authentication error #{auth_header_error}") unless auth_header_error.nil?
+          raise ClientError.new(0, finished_env[:status]), body["error"]
+        end
+        FlexmlsApi.logger.debug("Session= #{session.inspect}")
+        finished_env[:body] = session
+      end
+  
+      def initialize(app)
+        super
+        @parser = nil
+      end
+      
+    end
+    
+  end
+ 
+end