oauth2 0.4.1 → 0.5.0

data/.autotest

@@ -0,0 +1 @@
+require 'autotest/bundler'

data/.gitignore

@@ -32,4 +32,7 @@ Gemfile.lock
 coverage.data
 
 ## PROJECT::SPECIFIC
-.svn
+.svn
+
+## Rubinius
+*.rbc

data/.travis.yml

@@ -1,7 +1,5 @@
 rvm:
   - 1.8.7
-  - 1.9.1
   - 1.9.2
-  - jruby
-  - rbx
   - ree
+  - ruby-head

data/Gemfile

@@ -1,3 +1,3 @@
-source "http://rubygems.org"
+source 'http://rubygems.org'
 
 gemspec

data/README.md

@@ -8,7 +8,7 @@ Installation
 
 Continuous Integration
 ----------------------
-[![Build Status](http://travis-ci.org/intridea/oauth2.png)](http://travis-ci.org/intridea/oauth2)
+[![Build Status](https://secure.travis-ci.org/intridea/oauth2.png)](http://travis-ci.org/intridea/oauth2)
 
 Resources
 ---------
@@ -16,67 +16,48 @@ Resources
 * Report Issues on GitHub (https://github.com/intridea/oauth2/issues)
 * Read More at the Wiki (https://wiki.github.com/intridea/oauth2)
 
-Web Server Example (Sinatra)
-----------------------------
-Below is a fully functional example of a Sinatra application that would authenticate to Facebook utilizing the OAuth 2.0 web server flow.
+Generic Client Example
+----------------------
 
-    require 'rubygems'
-    require 'sinatra'
     require 'oauth2'
-    require 'json'
-    
-    def client
-      OAuth2::Client.new('app_id', 'app_secret', :site => 'https://graph.facebook.com')
-    end
-    
-    get '/auth/facebook' do
-      redirect client.web_server.authorize_url(
-        :redirect_uri => redirect_uri,
-        :scope => 'email,offline_access'
-      )
-    end
-    
-    get '/auth/facebook/callback' do
-      access_token = client.web_server.get_access_token(params[:code], :redirect_uri => redirect_uri)
-      user = JSON.parse(access_token.get('/me'))
-      user.inspect
-    end
-    
-    def redirect_uri
-      uri = URI.parse(request.url)
-      uri.path = '/auth/facebook/callback'
-      uri.query = nil
-      uri.to_s
-    end
-
-That's all there is to it! You can use the access token like you would with the
-OAuth gem, calling HTTP verbs on it etc. You can view more examples on the [OAuth2
-Wiki](http://wiki.github.com/intridea/oauth2/examples).
-
-JSON Parsing
-------------
-Because JSON has become the standard format of the OAuth 2.0 specification,
-the <tt>oauth2</tt> gem contains a mode that will perform automatic parsing
-of JSON response bodies, returning a hash instead of a string. To enable this
-mode, simply add the <tt>:parse_json</tt> option to your client initialization:
+    client = OAuth2::Client.new('client_id', 'client_secret', :site => 'https://example.org')
+
+    client.auth_code.authorize_url(:redirect_uri => 'http://localhost:8080/oauth2/callback')
+    # => "https://example.org/oauth/authorization?response_type=code&client_id=client_id&redirect_uri=http://localhost:8080/oauth2/callback"
+
+    token = client.auth_code.get_token('authorization_code_value', :redirect_uri => 'http://localhost:8080/oauth2/callback')
+    response = token.get('/api/resource', :params => { 'query_foo' => 'bar' })
+    response.class.name
+    # => OAuth2::Response
+
+OAuth2::Response
+----------------
+The AccessToken methods #get, #post, #put and #delete and the generic #request will return an instance of the #OAuth2::Response class.
+This instance contains a #parsed method that will parse the response body and return a Hash if the Content-Type is application/x-www-form-urlencoded or if the body is a JSON object.  It will return an Array if the body is a JSON array.  Otherwise, it will return the original body string.
+
+The original response body, headers, and status can be accessed via their respective methods.
+
+OAuth2::AccessToken
+-------------------
+If you have an existing Access Token for a user, you can initialize an instance using various class methods including the standard new, from_hash (if you have a hash of the values), or from_kvform (if you have an application/x-www-form-urlencoded encoded string of the values).
+
+OAuth2::Error
+-------------
+On 400+ status code responses, an OAuth2::Error will be raised.  If it is a standard OAuth2 error response, the body will be parsed and #code and #description will contain the values provided from the error and error_description parameters.  The #response property of OAuth2::Error will always contain the OAuth2::Response instance.
 
-    client = OAuth2::Client.new(
-      'app_id',
-      'app_secret',
-      :site => 'https://example.com',
-      :parse_json => true,
-    )
-    
-    # Obtain an access token using the client
-    token.get('/some/url.json') #=> {"some" => "hash"}
+If you do not want an error to be raised, you may use :raise_errors => false option on initialization of the client.  In this case the OAuth2::Response instance will be returned as usual and on 400+ status code responses, the Response instance will contain the OAuth2::Error instance.
 
-Testing
--------
-To use the OAuth2 client for testing error conditions do:
+Authorization Grants
+--------------------
+Currently the Authorization Code and Resource Owner Password Credentials authentication grant types have helper strategy classes that simplify client use.  They are available via the #auth_code and #password methods respectively.
 
-    my_client.raise_errors = false
+    auth_url = client.auth_code.authorization_url(:redirect_uri => 'http://localhost:8080/oauth/callback')
+    token = client.auth_code.get_token('code_value', :redirect_uri => 'http://localhost:8080/oauth/callback')
+
+    token = client.password.get_token('username', 'password')
+
+You can always use the #request method on the OAuth2::Client instance to make requests for tokens for any Authentication grant type.
 
-It will then return the error status and response instead of raising an exception.
 
 Note on Patches/Pull Requests
 -----------------------------
@@ -87,7 +68,31 @@ Note on Patches/Pull Requests
 5. Add specs for your feature or bug fix.
 6. Run <tt>bundle exec rake spec</tt>. If your changes are not 100% covered, go back to step 5.
 7. Commit and push your changes.
-8. Submit a pull request. Please do not include changes to the [gemspec](https://github.com/intridea/oauth2/blob/master/oauth2.gemspec), [version](https://github.com/intridea/oauth2/blob/master/lib/oauth2/version.rb), or [changelog](https://github.com/intridea/oauth2/blob/master/CHANGELOG.md) file. (If you want to create your own version for some reason, please do so in a separate commit.)
+8. Submit a pull request. Please do not include changes to the [gemspec](https://github.com/intridea/oauth2/blob/master/oauth2.gemspec), [version](https://github.com/intridea/oauth2/blob/master/lib/oauth2/version.rb), or [changelog](https://github.com/intridea/oauth2/wiki/Changelg) . (If you want to create your own version for some reason, please do so in a separate commit.)
+
+Supported Rubies
+----------------
+This library aims to support and is [tested
+against](http://travis-ci.org/intridea/oauth2) the following Ruby
+implementations:
+
+* Ruby 1.8.7
+* Ruby 1.9.2
+* Ruby Enterprise Edition 1.8.7
+
+If something doesn't work on one of these interpreters, it should be considered
+a bug.
+
+This library may inadvertently work (or seem to work) on other Ruby
+implementations, however support will only be provided for the versions listed
+above.
+
+If you would like this library to support another Ruby version, you may
+volunteer to be a maintainer. Being a maintainer entails making sure all tests
+run and pass on that implementation. When something breaks on your
+implementation, you will be personally responsible for providing patches in a
+timely fashion. If critical issues for a particular implementation exist at the
+time of a major release, support for that Ruby version may be dropped.
 
 Copyright
 ---------

data/Rakefile

@@ -1,3 +1,5 @@
+#!/usr/bin/env rake
+
 require 'bundler'
 Bundler::GemHelper.install_tasks
 
@@ -7,7 +9,7 @@ RSpec::Core::RakeTask.new(:spec)
 task :default => :spec
 task :test => :spec
 
-require 'rake/rdoctask'
+require 'rdoc/task'
 Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title = "oauth2 #{OAuth2::VERSION}"

data/lib/oauth2.rb

@@ -1,13 +1,7 @@
-module OAuth2
-  class ErrorWithResponse < StandardError; attr_accessor :response end
-  class AccessDenied < ErrorWithResponse; end
-  class Conflict < ErrorWithResponse; end
-  class HTTPError < ErrorWithResponse; end
-end
-
+require 'oauth2/error'
 require 'oauth2/client'
 require 'oauth2/strategy/base'
-require 'oauth2/strategy/web_server'
+require 'oauth2/strategy/auth_code'
 require 'oauth2/strategy/password'
 require 'oauth2/access_token'
-require 'oauth2/response_object'
+require 'oauth2/response'

data/lib/oauth2/access_token.rb

@@ -1,53 +1,151 @@
 module OAuth2
   class AccessToken
     attr_reader :client, :token, :refresh_token, :expires_in, :expires_at, :params
-    attr_accessor :token_param
+    attr_accessor :options
 
-    def initialize(client, token, refresh_token=nil, expires_in=nil, params={})
+    class << self
+      # Initializes an AccessToken from a Hash
+      #
+      # @param [Client] the OAuth2::Client instance
+      # @param [Hash] a hash of AccessToken property values
+      # @return [AccessToken] the initalized AccessToken
+      def from_hash(client, hash)
+        self.new(client, hash.delete('access_token') || hash.delete(:access_token), hash)
+      end
+
+      # Initializes an AccessToken from a key/value application/x-www-form-urlencoded string
+      #
+      # @param [Client] client the OAuth2::Client instance
+      # @param [String] kvform the application/x-www-form-urlencoded string
+      # @return [AccessToken] the initalized AccessToken
+      def from_kvform(client, kvform)
+        from_hash(client, Rack::Utils.parse_query(kvform))
+      end
+    end
+
+    # Initalize an AccessToken
+    #
+    # @param [Client] client the OAuth2::Client instance
+    # @param [String] token the Access Token value
+    # @param [Hash] opts the options to create the Access Token with
+    # @option opts [String] :refresh_token (nil) the refresh_token value
+    # @option opts [FixNum, String] :expires_in (nil) the number of seconds in which the AccessToken will expire
+    # @option opts [FixNum, String] :expires_at (nil) the epoch time in seconds in which AccessToken will expire
+    # @option opts [Symbol] :mode (:header) the transmission mode of the Access Token parameter value
+    #    one of :header, :body or :query
+    # @option opts [String] :header_format ('Bearer %s') the string format to use for the Authorization header
+    # @option opts [String] :param_name ('bearer_token') the parameter name to use for transmission of the
+    #    Access Token value in :body or :query transmission mode
+    def initialize(client, token, opts={})
       @client = client
       @token = token.to_s
-      @refresh_token = refresh_token.to_s
-      @expires_in = (expires_in.nil? || expires_in == '') ? nil : expires_in.to_i
-      @expires_at = Time.now + @expires_in if @expires_in
-      @params = params
-      @token_param = 'oauth_token'
+      [:refresh_token, :expires_in, :expires_at].each do |arg|
+        instance_variable_set("@#{arg}", opts.delete(arg) || opts.delete(arg.to_s))
+      end
+      @expires_in ||= opts.delete('expires')
+      @expires_in &&= @expires_in.to_i
+      @expires_at ||= Time.now.to_i + @expires_in if @expires_in
+      @options = {:mode          => opts.delete(:mode) || :header,
+                  :header_format => opts.delete(:header_format) || 'Bearer %s',
+                  :param_name    => opts.delete(:param_name) || 'bearer_token'}
+      @params = opts
     end
 
+    # Indexer to additional params present in token response
+    #
+    # @param [String] key entry key to Hash
     def [](key)
       @params[key]
     end
 
-    # True if the token in question has an expiration time.
+    # Whether or not the token expires
+    #
+    # @return [Boolean]
     def expires?
-      !!@expires_in
+      !!@expires_at
     end
 
+    # Whether or not the token is expired
+    #
+    # @return [Boolean]
     def expired?
-      expires? && expires_at < Time.now
+      expires? && (expires_at < Time.now.to_i)
     end
 
-    def request(verb, path, params={}, headers={})
-      if params.instance_of?(Hash)
-        params = params.merge token_param => @token
-      end
-      headers = headers.merge 'Authorization' => "OAuth #{@token}"
-      @client.request(verb, path, params, headers)
+    # Refreshes the current Access Token
+    #
+    # @return [AccessToken] a new AccessToken
+    # @note options should be carried over to the new AccessToken
+    def refresh!(params={})
+      raise "A refresh_token is not available" unless refresh_token
+      params.merge!(:client_id      => @client.id,
+                    :client_secret  => @client.secret,
+                    :grant_type     => 'refresh_token',
+                    :refresh_token  => refresh_token)
+      new_token = @client.get_token(params)
+      new_token.options = options
+      new_token
+    end
+
+    # Make a request with the Access Token
+    #
+    # @param [Symbol] verb the HTTP request method
+    # @param [String] path the HTTP URL path of the request
+    # @param [Hash] opts the options to make the request with
+    # @see Client#request
+    def request(verb, path, opts={}, &block)
+      set_token(opts)
+      @client.request(verb, path, opts, &block)
     end
 
-    def get(path, params={}, headers={})
-      request(:get, path, params, headers)
+    # Make a GET request with the Access Token
+    #
+    # @see AccessToken#request
+    def get(path, opts={}, &block)
+      request(:get, path, opts, &block)
     end
 
-    def post(path, params={}, headers={})
-      request(:post, path, params, headers)
+    # Make a POST request with the Access Token
+    #
+    # @see AccessToken#request
+    def post(path, opts={}, &block)
+      request(:post, path, opts, &block)
     end
 
-    def put(path, params={}, headers={})
-      request(:put, path, params, headers)
+    # Make a PUT request with the Access Token
+    #
+    # @see AccessToken#request
+    def put(path, opts={}, &block)
+      request(:put, path, opts, &block)
     end
 
-    def delete(path, params={}, headers={})
-      request(:delete, path, params, headers)
+    # Make a DELETE request with the Access Token
+    #
+    # @see AccessToken#request
+    def delete(path, opts={}, &block)
+      request(:delete, path, opts, &block)
+    end
+
+  private
+    def set_token(opts)
+      case options[:mode]
+      when :header
+        opts[:headers] ||= {}
+        opts[:headers]['Authorization'] = options[:header_format] % token
+      when :query
+        opts[:params] ||= {}
+        opts[:params][options[:param_name]] = token
+      when :body
+        opts[:body] ||= {}
+        if opts[:body].is_a?(Hash)
+          opts[:body][options[:param_name]] = token
+        else
+          opts[:body] << "&#{options[:param_name]}=#{token}"
+        end
+        # @todo support for multi-part (file uploads)
+      else
+        raise "invalid :mode option of #{options[:mode]}"
+      end
     end
   end
 end

data/lib/oauth2/client.rb

@@ -1,105 +1,146 @@
 require 'faraday'
 
 module OAuth2
+  # The OAuth2::Client class
   class Client
-    attr_accessor :id, :secret, :site, :connection, :options, :raise_errors, :token_method
-    attr_writer :json
+    attr_reader :id, :secret
+    attr_accessor :site, :connection, :options
 
     # Instantiate a new OAuth 2.0 client using the
-    # client ID and client secret registered to your
+    # Client ID and Client Secret registered to your
     # application.
     #
-    # Options:
+    # @param [String] client_id the client_id value
+    # @param [String] client_secret the client_secret value
+    # @param [Hash] opts the options to create the client with
+    # @option opts [String] :site the OAuth2 provider site host
+    # @option opts [String] :authorize_url ('/oauth/authorize') absolute or relative URL path to the Authorization endpoint
+    # @option opts [String] :token_url ('/oauth/token') absolute or relative URL path to the Token endpoint
+    # @option opts [Symbol] :token_method (:post) HTTP method to use to request token (:get or :post)
+    # @option opts [Hash] :connection_opts ({}) Hash of connection options to pass to initialize Faraday with
+    # @option opts [FixNum] :max_redirects (5) maximum number of redirects to follow
+    # @option opts [Boolean] :raise_errors (true) whether or not to raise an OAuth2::Error
+    #  on responses with 400+ status codes
+    # @yield [builder] The Faraday connection builder
+    def initialize(client_id, client_secret, opts={}, &block)
+      @id = client_id
+      @secret = client_secret
+      @site = opts.delete(:site)
+      ssl = opts.delete(:ssl)
+      @options = {:authorize_url    => '/oauth/authorize',
+                  :token_url        => '/oauth/token',
+                  :token_method     => :post,
+                  :connection_opts  => {},
+                  :connection_build => block,
+                  :max_redirects    => 5,
+                  :raise_errors     => true}.merge(opts)
+      @options[:connection_opts][:ssl] = ssl if ssl
+    end
+
+    # Set the site host
     #
-    # <tt>:site</tt> :: Specify a base URL for your OAuth 2.0 client.
-    # <tt>:authorize_path</tt> :: Specify the path to the authorization endpoint.
-    # <tt>:authorize_url</tt> :: Specify a full URL of the authorization endpoint.
-    # <tt>:access_token_path</tt> :: Specify the path to the access token endpoint.
-    # <tt>:access_token_method</tt> :: Specify the method to use for token endpoints, can be :get or :post
-    # (note: for Facebook this should be :get and for Google this should be :post)
-    # <tt>:access_token_url</tt> :: Specify the full URL of the access token endpoint.
-    # <tt>:parse_json</tt> :: If true, <tt>application/json</tt> responses will be automatically parsed.
-    # <tt>:ssl</tt> :: Specify SSL options for the connection.
-    # <tt>:adapter</tt> :: The name of the Faraday::Adapter::* class to use, e.g. :net_http. To pass arguments
-    # to the adapter pass an array here, e.g. [:action_dispatch, my_test_session]
-    # <tt>:raise_errors</tt> :: Default true. When false it will then return the error status and response instead of raising an exception.
-    def initialize(client_id, client_secret, opts={})
-      self.options      = opts.dup
-      self.token_method = self.options.delete(:access_token_method) || :post
-      adapter           = self.options.delete(:adapter)
-      ssl_opts          = self.options.delete(:ssl) || {}
-      connection_opts   = ssl_opts ? {:ssl => ssl_opts} : {}
-      self.id           = client_id
-      self.secret       = client_secret
-      self.site         = self.options.delete(:site) if self.options[:site]
-      self.connection   = Faraday::Connection.new(site, connection_opts)
-      self.json         = self.options.delete(:parse_json)
-      self.raise_errors = !(self.options.delete(:raise_errors) == false)
+    # @param [String] the OAuth2 provider site host
+    def site=(value)
+      @connection = nil
+      @site = value
+    end
 
-      if adapter && adapter != :test
-        connection.build do |b|
-          b.adapter(*[adapter].flatten)
-        end
+    # The Faraday connection object
+    def connection
+      @connection ||= begin
+        conn = Faraday.new(site, options[:connection_opts])
+        conn.build do |b|
+          options[:connection_build].call(b)
+        end if options[:connection_build]
+        conn
       end
     end
 
+    # The authorize endpoint URL of the OAuth2 provider
+    #
+    # @param [Hash] params additional query parameters
     def authorize_url(params=nil)
-      path = options[:authorize_url] || options[:authorize_path] || "/oauth/authorize"
-      connection.build_url(path, params).to_s
+      connection.build_url(options[:authorize_url], params).to_s
     end
 
-    def access_token_url(params=nil)
-      path = options[:access_token_url] || options[:access_token_path] || "/oauth/access_token"
-      connection.build_url(path, params).to_s
+    # The token endpoint URL of the OAuth2 provider
+    #
+    # @param [Hash] params additional query parameters
+    def token_url(params=nil)
+      connection.build_url(options[:token_url], params).to_s
     end
 
     # Makes a request relative to the specified site root.
-    def request(verb, url, params={}, headers={})
-      if (verb == :get) || (verb == :delete)
-        resp = connection.run_request(verb, url, nil, headers) do |req|
-          req.params.update(params)
-        end
-      else
-        resp = connection.run_request(verb, url, params, headers)
+    #
+    # @param [Symbol] verb one of :get, :post, :put, :delete
+    # @param [String] url URL path of request
+    # @param [Hash] opts the options to make the request with
+    # @option opts [Hash] :params additional query parameters for the URL of the request
+    # @option opts [Hash, String] :body the body of the request
+    # @option opts [Hash] :headers http request headers
+    # @option opts [Boolean] :raise_errors whether or not to raise an OAuth2::Error on 400+ status
+    #   code response for this request.  Will default to client option
+    # @option opts [Symbol] :parse @see Response::initialize
+    # @yield [req] The Faraday request
+    def request(verb, url, opts={})
+      url = self.connection.build_url(url, opts[:params]).to_s
+
+      response = connection.run_request(verb, url, opts[:body], opts[:headers]) do |req|
+        yield(req) if block_given?
       end
+      response = Response.new(response, :parse => opts[:parse])
 
-      if raise_errors
-        case resp.status
-          when 200...299
-            return response_for(resp)
-          when 302
-            return request(verb, resp.headers['location'], params, headers)
-          when 401
-            e = OAuth2::AccessDenied.new("Received HTTP 401 during request.")
-            e.response = resp
-            raise e
-          when 409
-            e = OAuth2::Conflict.new("Received HTTP 409 during request.")
-            e.response = resp
-            raise e
-          else
-            e = OAuth2::HTTPError.new("Received HTTP #{resp.status} during request.")
-            e.response = resp
-            raise e
+      case response.status
+      when 200..299
+        response
+      when 300..399
+        opts[:redirect_count] ||= 0
+        opts[:redirect_count] += 1
+        return response if opts[:redirect_count] > options[:max_redirects]
+        if response.status == 303
+          verb = :get
+          opts.delete(:body)
         end
+        request(verb, response.headers['location'], opts)
+      when 400..599
+        e = Error.new(response)
+        raise e if opts[:raise_errors] || options[:raise_errors]
+        response.error = e
+        response
       else
-        response_for resp
+        raise Error.new(response), "Unhandled status code value of #{response.status}"
       end
     end
 
-    def json?; !!@json end
-
-    def web_server; OAuth2::Strategy::WebServer.new(self) end
-    def password; OAuth2::Strategy::Password.new(self) end
-
-    private
-
-    def response_for(resp)
-      if json?
-        return ResponseObject.from(resp)
+    # Initializes an AccessToken by making a request to the token endpoint
+    #
+    # @param [Hash] params a Hash of params for the token endpoint
+    # @return [AccessToken] the initalized AccessToken
+    def get_token(params)
+      opts = {:raise_errors => true, :parse => params.delete(:parse)}
+      if options[:token_method] == :post
+        opts[:body] = params
+        opts[:headers] =  {'Content-Type' => 'application/x-www-form-urlencoded'}
       else
-        return ResponseString.new(resp)
+        opts[:params] = params
       end
+      response = request(options[:token_method], token_url, opts)
+      raise Error.new(response) unless response.parsed.is_a?(Hash) && response.parsed['access_token']
+      AccessToken.from_hash(self, response.parsed)
+    end
+
+    # The Authorization Code strategy
+    #
+    # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.1
+    def auth_code
+      @auth_code ||= OAuth2::Strategy::AuthCode.new(self)
+    end
+
+    # The Resource Owner Password Credentials strategy
+    #
+    # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.3
+    def password
+      @password ||= OAuth2::Strategy::Password.new(self)
     end
   end
 end