oauth2-client 1.0.0 → 1.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    N2U2ZjkyMjc5YjBhZWE1MjE3YTZjZDEzMjM4M2Y0MDZlYTA3MmU0YQ==
+  data.tar.gz: !binary |-
+    M2NhZDBhYjljNzVmY2ZkYTEwNjcxZGI4MmRjNTUxODhhOTNlMzYzMQ==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    MzJhY2RiOWQ4ZWFkZTZjNmI2YmRhYWYyOGUzZTBiM2YzNmJmZWY0ZTgyZTRj
+    M2IwYTkyOTgxM2MzZmQ1MzhlODYyOGM4YjEwZGJhZWZkNDg3ZDA4YzEyNWVk
+    NDQxNWM0N2QzYjRiZmM2Y2UwMzc4MzRlOTQ1OGQ2YjBjNTk5NTg=
+  data.tar.gz: !binary |-
+    ZGU0YmRiM2Y5YjRlNzUzMTdmNTA0ZWVjOGIzMzViNDliNzQxNjk0OWNiN2Zj
+    MDVjYjYxYzUxYTRiN2I0ZDJjYjQxZDc0YmEyZmI4ZWQ4YjFhNjMwYjVlMTcy
+    YzUwNGFjNDlmZDM4YjU1ODVlMDc1MGIzMDE5ZTViYmU3YTNjNjY=

data/.gitignore

@@ -16,3 +16,13 @@ tmp
 .yardoc
 _yardoc
 doc/
+
+# OS generated files #
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+Icon?
+ehthumbs.db
+Thumbs.db

data/.travis.yml

@@ -1,5 +1,6 @@
 language: ruby
 rvm:
+  - "1.8.7"
   - "1.9.2"
   - "1.9.3"
 # uncomment this line if your project needs to run something other than `rake`:

data/Gemfile

@@ -1,17 +1,12 @@
 source 'https://rubygems.org'
 
-gem 'json'
-
-gem 'bcrypt-ruby', '~> 3.0.0'
-
-gem 'addressable'
-
 gem 'rake'
 
-gem 'rspec', '~>2.12'
-
-gem 'simplecov'
-
-gem 'activesupport', '~> 3.2.8'
+group :test do
+  gem 'json', :platforms => :ruby_18
+  gem 'rspec', '>= 2.11'
+  gem 'simplecov', :require => false
+  gem 'webmock'
+end
 
-# gem 'mocha', '>=0.12.1', :require => false
+gemspec

data/Gemfile.lock

@@ -1,13 +1,18 @@
+PATH
+  remote: .
+  specs:
+    oauth2-client (1.1.0)
+      addressable
+      bcrypt-ruby (~> 3.0.0)
+      json
+
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (3.2.8)
-      i18n (~> 0.6)
-      multi_json (~> 1.0)
-    addressable (2.3.2)
+    addressable (2.3.3)
     bcrypt-ruby (3.0.1)
+    crack (0.3.2)
     diff-lcs (1.1.3)
-    i18n (0.6.1)
     json (1.7.5)
     multi_json (1.3.6)
     rake (0.9.2.2)
@@ -23,15 +28,18 @@ GEM
       multi_json (~> 1.0)
       simplecov-html (~> 0.7.1)
     simplecov-html (0.7.1)
+    webmock (1.10.1)
+      addressable (>= 2.2.7)
+      crack (>= 0.3.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  activesupport (~> 3.2.8)
-  addressable
-  bcrypt-ruby (~> 3.0.0)
+  bundler (~> 1.0)
   json
+  oauth2-client!
   rake
-  rspec (~> 2.12)
+  rspec (>= 2.11)
   simplecov
+  webmock

data/{LICENSE → LICENSE.md}

@@ -1,4 +1,4 @@
-Copyright (c) 2012, Kevin Mutyaba
+Copyright (c) 2013, Kevin Mutyaba
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,24 +1,30 @@
 # OAuth2 Ruby Client
 
+[![Gem Version](https://badge.fury.io/rb/oauth2-client.png)][gem]
 [![Build Status](https://secure.travis-ci.org/tiabas/oauth2-client.png?branch=master)][travis]
 
+[gem]: https://rubygems.org/gems/oauth2-client
 [travis]: http://travis-ci.org/tiabas/oauth2-client
 
-A Ruby wrapper for the OAuth 2.0 specification. It is designed with the philosophy that not
-every service that claims to support OAuth 2.0 actually implements it according to the
-[standard]( http://tools.ietf.org/html/rfc6749). This version therefore, affords 
-the developer some degree of flexibility in generating the URLs and requests
-needed to authorize an OAuth 2.0 application.
+A Ruby wrapper for the OAuth 2.0 specification. It is designed with the philosophy that 
+different service providers implement OAuth 2.0 differently and not exactly according to the
+[RFC]( http://tools.ietf.org/html/rfc6749). This gem therefore, affords 
+the developer some degree of flexibility in creating a client that will work with different OAuth2
+providers.
 
-For more about the standard, take a look at http://tools.ietf.org/html/rfc6749 
+For more about the standard checkout: http://tools.ietf.org/html/rfc6749 
 
 ## Installation
-Download the library and include the its location in your Gemfile
+```sh
+gem install oauth2-client
+```
 
 ## Resources
 * [View Source on GitHub][code]
 * [Report Issues on GitHub][issues]
+* [Website][website]
 
+[website]: http://tiabas.github.com/oauth2-client/
 [code]: https://github.com/tiabas/oauth2-client
 [issues]: https://github.com/tiabas/oauth2-client/issues
 
@@ -85,6 +91,52 @@ auth_url = client.device_code.authorization_path(:scope => 'abc xyz', :state =>
 token = client.device_code.get_token(device_auth_code)
 ```
 
+# Using a custom Http wrapper
+By default, oauth2-client uses a Net::HTTP wrapper called OAuth2::HttpConnection. However, if you wish to use a different HTTP library, you only
+need to create a wrapper around your favorite library that will respond to the `send_request` method.
+
+```ruby
+class TyphoeusHttpConnection
+  
+  def initalize(site_url, connection_options={})
+    # set url and connection options
+    @site_url = site_url
+    @connection_options = connection_options
+  end
+
+  def base_url(path)
+    @site_url + path
+  end
+
+  def send_request(http_method, request_path, options={})
+    # options may contain optional arguments like http headers, request parameters etc
+    # send http request over the inter-webs
+
+    params          = options[:params] || {}
+    headers         = options[:headers]|| {}
+    method          = method.to_sym
+    client          = Typhoeus
+
+    case method
+    when :get, :delete
+      #pass
+    when :post, :put
+      options[:body] = options.delete(:params) if options[:params]
+    else
+      raise UnhandledHTTPMethodError.new("Unsupported HTTP method, #{method}")
+    end
+    response = client.send(http_method, base_url(request_path), params)
+  end
+end
+
+# now you can initialize the OAuth2 client with you custom client and expect that all requests
+# will be sent using this client
+oauth_client = OAuth2::Client.new('example.com', client_id, client_secret, {
+  :connection_client  => TyphoeusHttpConnection,
+  :connection_options => {}
+})
+```
+
 # Client Examples
 This library comes bundled with two sample implementations of Google and Yammer OAuth clients. These clients are 
 meant to showcase the degree of flexibilty that you get when using this library to interact with other OAuth 2.0
@@ -94,21 +146,14 @@ providers.
 
 ```ruby
 
-google_client = GoogleClient.new(
-  'https://accounts.google.com',
-  '827502413694.apps.googleusercontent.com',
-  'a2nQpcUm2Dgq1chWdAvbXGTk',
-  {
-    :token_path     => '/o/oauth2/token',
-    :authorize_path => '/o/oauth2/auth',
-    :device_path    => '/o/oauth2/device/code'
-  }
-)
+google_client = GoogleClient.new('https://accounts.google.com', '827502413694.apps.googleusercontent.com','a2nQpcUm2Dgq1chWdAvbXGTk')
 
 ```
 
 ### Client-side authorization URL(Implicit grant)
 ```ruby
+
+# generate authorization url
 auth_url = google_client.webserver_authorization_url(
     :scope => 'https://www.googleapis.com/auth/userinfo.email',
     :state => '/profile',
@@ -119,6 +164,8 @@ auth_url = google_client.webserver_authorization_url(
 
 ### Server-side authorization URL(Authorization code grant)
 ```ruby
+
+# generate authorization url
 auth_url = google_client.clientside_authorization_url(
     :scope => 'https://www.googleapis.com/auth/userinfo.email',
     :state => '/profile',
@@ -146,7 +193,50 @@ response.body
 }
 ```
 
+## Github Client
+
+```ruby
+
+gihub_client = GithubClient.new('https://github.com', '82f971d013e8d637a7e1', '1a1d59e1f8b8afa5f73e9dc9f17e25f7876e64ac')
+
+```
+### Server-side authorization URL(Authorization code grant)
+
+```ruby
+
+# generate authorization url
+auth_url = gihub_client.webserver_authorization_url
+# => https://github.com/login/oauth/authorize?client_id=82f971d013e8d637a7e1&response_type=code
+
+# exchange authorization code for access token. we will get back a Net::HTTPResponse
+response = gihub_client.exchange_auth_code_for_token({
+    :code => '11a0b0b64db56c30e2ef',
+    :redirect_uri => 'https://localhost/callback',
+  })
+
+response.inspect 
+# => #<Net::HTTPOK:0x007ff8bc7c1200>
+
+response.body
+# => {
+      "access_token" : "e409f4272fe539166a77c42479de030e7660812a",
+      "token_type" : "bearer"
+    }"
+```
+
+## Supported Ruby Versions
+This library aims to support and is [tested against][travis] the following Ruby
+version:
+
+* Ruby 1.8.7
+* Ruby 1.9.2
+* Ruby 1.9.3
+
+This library may inadvertently work (or seem to work) on other Ruby
+implementations, however support will only be provided for the versions listed
+above.
+
 ## Copyright
-Copyright (c) 2012 Kevin Mutyaba
-See [LICENSE][] for details.
+Copyright (c) 2013 Kevin Mutyaba
+See [LICENSE][license] for details.
 [license]: https://github.com/tiabas/oauth2-client/blob/master/LICENSE

data/examples/github_client.rb

@@ -0,0 +1,42 @@
+class GithubClient < OAuth2::Client
+  
+  def initialize(*args)
+    super
+    @token_path = '/login/oauth/access_token'
+    @authorize_path = '/login/oauth/authorize'
+  end
+  # @see http://developer.github.com/v3/oauth/#redirect-users-to-request-github-access
+  #
+  # @params [Hash] parameters to include in the URL eg. scope, state, redirect_uri
+  #
+  # client.webserver_authorization_url({
+  #  :scope => 'user, public_repo',
+  #  :state => '2sw543v74sfD',
+  #  :redirect_uri => 'https://localhost/callback',
+  # })
+  # #=>
+  def webserver_authorization_url(opts={})
+    opts[:scope] = normalize_scope(opts[:scope], ',') if opts[:scope]
+    authorization_code.authorization_url(opts)
+  end
+
+  #
+  # @see http://developer.github.com/v3/oauth/#github-redirects-back-to-your-site
+  #
+  # @params [Hash] parameters to include in the URL eg. code, redirect_uri
+  #
+  # client.exchange_auth_code_for_token(
+  #   :params => {
+  #     :code => '11a0b0b64db56c30e2ef',
+  #     :redirect_uri => 'https://localhost/callback',
+  #   })
+  # #=>
+  def exchange_auth_code_for_token(opts={})
+    unless (opts[:params] && opts[:params][:code])
+      raise "Authorization code expected but was nil"
+    end
+    opts[:authenticate] = :body
+    code = opts[:params].delete(:code)
+    authorization_code.get_token(code, opts)
+  end
+end

data/examples/google_client.rb

@@ -1,11 +1,10 @@
 class GoogleClient < OAuth2::Client
 
-  def normalize_scope(scope, sep=' ')
-    unless (scope.is_a?(String) || scope.is_a?(Array))
-      raise ArgumentError.new("Expected scope of type String or Array but was: #{scope.class.name}")
-    end
-    return scope if scope.is_a?(String)
-    scope.join(sep)
+  def initialize(*args)
+    super
+    @token_path = '/o/oauth2/token'
+    @authorize_path = '/o/oauth2/auth'
+    @device_path = '/o/oauth2/device/code'
   end
 
   # Generates the Google URL that the user will be redirected to in order to
@@ -56,15 +55,6 @@ class GoogleClient < OAuth2::Client
     authorization_code.authorization_url(params)
   end
 
-  # Generates the Google URL that allows a user to obtain an authorization
-  # code for a given device
-  #
-  # @see https://developers.google.com/accounts/docs/OAuth2ForDevices
-  # def device_authorization_url(params={})
-  #   params[:scope] = normalize_scope(params[:scope]) if params[:scope]
-  #   device.authorization_url(params)
-  # end
-
   # Makes a request to google server that will swap your authorization code for an access
   # token
   #
@@ -87,6 +77,7 @@ class GoogleClient < OAuth2::Client
     unless (opts[:params] && opts[:params][:code])
       raise ArgumentError.new("You must include an authorization code as a parameter")
     end
+    opts[:authenticate] ||= :body
     code = opts[:params].delete(:code)
     authorization_code.get_token(code, opts)
   end
@@ -112,10 +103,21 @@ class GoogleClient < OAuth2::Client
     unless (opts[:params] && opts[:params][:refresh_token])
       raise ArgumentError.new("You must provide a refresh_token as a parameter")
     end
+    opts[:authenticate] = :body
     token = opts[:params].delete(:refresh_token)
     refresh_token.get_token(token, opts)
   end
 
+
+  # Generates the Google URL that allows a user to obtain an authorization
+  # code for a given device
+  #
+  # @see https://developers.google.com/accounts/docs/OAuth2ForDevices
+  def device_authorization_url(params={})
+    params[:scope] = normalize_scope(params[:scope]) if params[:scope]
+    device.authorization_url(params)
+  end
+  
   # @see https://developers.google.com/accounts/docs/OAuth2ForDevices#obtainingacode
   #
   # @params [Hash] additional parameters to be include in URL eg. state

data/examples/yammer_client.rb

@@ -0,0 +1,96 @@
+class YammerClient < OAuth2::Client
+
+  def initialize(*args)
+    super
+    @token_path     = '/oauth2/token'
+    @authorize_path = '/dialog/oauth/authorize'
+  end
+  # Generates the Yammer URL that the user will be redirected to in order to
+  # authorize your application
+  #
+  # @see https://developer.yammer.com/api/oauth2.html#client-side
+  #
+  # @opts [Hash] additional parameters to be include in URL eg. scope, state, etc
+  #
+  # client = YammerClient.new(config)
+  # client.clientside_authorization_url({
+  #      :redirect_uri => 'https://localhost/oauth/cb',
+  #    })
+  # >> https://www.yammer.com/dialog/oauth/?client_id={client_id}&
+  #    redirect_uri=http%3A%2F%2Flocalhost%2Foauth%2Fcb&response_type=token
+  #
+  def clientside_authorization_url(opts={})
+    implicit.token_url(opts)
+  end
+
+  # Generates the Yammer URL that the user will be redirected to in order to
+  # authorize your application
+  #
+  # @see https://developer.yammer.com/api/oauth2.html#server-side
+  #
+  # @opts [Hash] additional parameters to be include in URL eg. scope, state, etc
+  #
+  # >> client = YammerClient.new(config)
+  # >> client.webserver_authorization_url({
+  #      :redirect_uri => 'https://localhost/oauth/cb',
+  #    })
+  # >> https://www.yammer.com/dialog/oauth/?client_id={client_id}&
+  #    redirect_uri=http%3A%2F%2Flocalhost%2Foauth%2Fcb&response_type=code
+  #
+  def webserver_authorization_url(opts={})
+    opts[:scope] = normalize_scope(opts[:scope]) if opts[:scope]
+    authorization_code.authorization_url(opts)
+  end
+
+  # Generates the Yammer URL that the user will be redirected to in order to
+  # authorize your application
+  #
+  # @see https://developer.yammer.com/api/oauth2.html#server-side
+  #
+  # @opts [Hash] additional parameters to be include in URL eg. scope, state, etc
+  #
+  # >> client = YammerClient.new(config)
+  # >> client.webserver_authorization_url({
+  #      :client_secret => @client_secret
+  #      :code => 'G3Y6jU3a',
+  #      :redirect_uri => 'https://localhost/oauth/cb',
+  #    })
+  # >> https://www.yammer.com/oauth2/access_token?client_id={client_id}&
+  #    redirect_uri=http%3A%2F%2Flocalhost%2Foauth%2Fcb&client_secret={client_secret}&
+  #    grant_type=authorization_code&code=aXW2c6bYz
+  #
+  def webserver_token_url(opts={})
+    opts[:scope] = normalize_scope(opts[:scope]) if opts[:scope]
+    opts[:client_secret] = @client_secret
+    authorization_code.token_path(opts)
+  end
+
+  # Makes a request to Yammer server that will swap your authorization code for an access
+  # token
+  #
+  # @see https://developer.yammer.com/api/oauth2.html#server-side
+  #
+  # @opts [Hash] must include authorization code and redirect uri in additon to others
+  #
+  # >> client = YammerClient.new(config)
+  # >> client.exchange_auth_code_for_token({
+  #      :redirect_uri => 'https://localhost:3000/oauth/v2/callback',
+  #      :code => 'G3Y6jU3a',
+  #    })
+  #
+  # POST /oauth2/access_token HTTP/1.1
+  # Host: www.yammer.com
+  # Content-Type: application/x-www-form-urlencoded
+
+  #  client_id={client_id}&code=G3Y6jU3a&grant_type=authorization_code&
+  #  redirect_uri=http%3A%2F%2Flocalhost%2Foauth%2Fcb&client_secret={client_secret}
+
+  def exchange_auth_code_for_token(opts={})
+    unless (opts[:params] && opts[:params][:code])
+      raise ArgumentError.new("You must include an authorization code as a parameter")
+    end
+    opts[:authenticate] ||= :body
+    code = opts[:params].delete(:code)
+    authorization_code.get_token(code, opts)
+  end
+end