spark_api 1.0.0

data/lib/spark_api/authentication/api_auth.rb

@@ -0,0 +1,104 @@
+module SparkApi
+
+  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)
+        super(client)
+      end
+      
+      def authenticate
+        sig = sign("#{@client.api_secret}ApiKey#{@client.api_key}")
+        SparkApi.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
+        SparkApi.logger.info("[#{(request_time * 1000).to_i}ms] Api: POST #{request_path}")
+        SparkApi.logger.debug("Authentication Response: #{resp.inspect}")
+        @session = Session.new(resp.body.results.first)
+        SparkApi.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="")
+        token_string = "#{@client.api_secret}ApiKey#{@client.api_key}ServicePath#{path}#{build_param_string(params)}#{post_data}"
+        signed = sign(token_string)
+        signed
+      end
+      
+      # Perform an HTTP request (no data)
+      def request(method, path, body, options)
+        escaped_path = URI.escape(path)
+        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(escaped_path, request_opts, body)
+        request_path = "#{escaped_path}?#{build_url_parameters({"ApiSig"=>sig}.merge(request_opts))}"
+        SparkApi.logger.debug("Request: #{request_path}")
+        if body.nil?
+          response = @client.connection.send(method, request_path)
+        else
+          SparkApi.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/spark_api/authentication/api_auth.rb~

@@ -0,0 +1,104 @@
+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)
+        super(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}")
+        FlexmlsApi.logger.debug("Authentication Response: #{resp.inspect}")
+        @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="")
+        token_string = "#{@client.api_secret}ApiKey#{@client.api_key}ServicePath#{path}#{build_param_string(params)}#{post_data}"
+        signed = sign(token_string)
+        signed
+      end
+      
+      # Perform an HTTP request (no data)
+      def request(method, path, body, options)
+        escaped_path = URI.escape(path)
+        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(escaped_path, request_opts, body)
+        request_path = "#{escaped_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/spark_api/authentication/base_auth.rb

@@ -0,0 +1,47 @@
+module SparkApi
+
+  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 spark_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/spark_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/spark_api/authentication/oauth2.rb

@@ -0,0 +1,198 @@
+require 'uri'
+
+module SparkApi
+
+  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 initialize(client)
+        super(client)
+        @provider = client.oauth2_provider
+      end
+      
+      def session
+        @provider.load_session()
+      end
+      def session=(s)
+        @provider.save_session(s)
+      end
+      
+      def authenticate
+        granter = OAuth2Impl::GrantTypeBase.create(@client, @provider, session)
+        self.session = granter.authenticate
+        session
+      end
+      
+      # Perform an HTTP request (no data)
+      def request(method, path, body, options={})
+        escaped_path = URI.escape(path)
+        connection = @client.connection(true)  # SSL Only!
+        connection.headers.merge!(self.auth_header)
+        parameter_string = options.size > 0 ? "?#{build_url_parameters(options)}" : ""
+        request_path = "#{escaped_path}#{parameter_string}"
+        SparkApi.logger.debug("Request: #{request_path}")
+        if body.nil?
+          response = connection.send(method, request_path)
+        else
+          SparkApi.logger.debug("Data: #{body}")
+          response = connection.send(method, request_path, body)
+        end
+        response
+      end
+      
+      def logout
+        @provider.save_session(nil)
+      end
+      
+      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
+
+            
+      protected
+      
+      def auth_header
+        {"Authorization"=> "OAuth #{session.access_token}"}
+      end
+      
+      def provider
+        @provider
+      end
+      def client
+        @client
+      end
+
+    end
+    
+    # Representation of a session with the api using oauth2
+    class OAuthSession
+      SESSION_ATTRIBUTES = [:access_token, :expires_in, :scope, :refresh_token, :refresh_timeout, :start_time]
+      attr_accessor *SESSION_ATTRIBUTES
+      def initialize(options={})
+        @access_token = options["access_token"]
+        @expires_in = options["expires_in"]
+        @scope = options["scope"]
+        @refresh_token = options["refresh_token"]
+        @start_time = options.fetch("start_time", DateTime.now)
+        @refresh_timeout = options.fetch("refresh_timeout",3600)
+        if @start_time.is_a? String
+          @start_time = DateTime.parse(@start_time)
+        end
+      end
+      #  Is the user session token expired?
+      def expired?
+        @start_time + Rational(@expires_in - @refresh_timeout, 86400) < DateTime.now
+      end
+      
+      def to_json(*a)
+        hash = {}
+        SESSION_ATTRIBUTES.each do |k|
+          value = self.send(k)
+          hash[k.to_s] = value unless value.nil?
+        end
+        hash.to_json(*a)
+      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 the Spark platform
+    #  @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 *Configuration::OAUTH2_KEYS
+      # Requirements for authorization_code grant type
+      attr_accessor :code
+      attr_accessor :grant_type
+      
+      def initialize(opts={})
+        Configuration::OAUTH2_KEYS.each do |key|
+          send("#{key}=", opts[key]) if opts.include? key
+        end
+        @grant_type = :authorization_code
+      end
+      
+      def grant_type
+        # backwards compatibility check
+        @grant_type.nil? ?  :authorization_code : @grant_type
+      end
+      
+      # 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
+        86400 # 1.day
+      end
+
+    end
+
+    module OAuth2Impl
+      require 'spark_api/authentication/oauth2_impl/middleware'
+      require 'spark_api/authentication/oauth2_impl/grant_type_base'
+      require 'spark_api/authentication/oauth2_impl/grant_type_refresh'
+      require 'spark_api/authentication/oauth2_impl/grant_type_code'
+      require 'spark_api/authentication/oauth2_impl/grant_type_password'
+      require 'spark_api/authentication/oauth2_impl/password_provider'
+      
+      # Loads a provider class from a string
+      def self.load_provider(string, args={})
+        constant = Object
+        string.split("::").compact.each { |name| constant = constant.const_get(name) unless name == ""}
+        constant.new(args)
+      rescue => e
+        raise ArgumentError, "The value '#{string}' is an invalid class name for an oauth2 provider:  #{e.message}"
+      end
+    end
+    
+  end
+ 
+end