README.md in oauth2-client-1.0.0 vs README.md in oauth2-client-1.1.0
- old
+ new
@@ -1,26 +1,32 @@
# OAuth2 Ruby Client
+[][gem]
[][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
## Usage Examples
@@ -83,44 +89,85 @@
# exchange device authorization code for access token
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
providers.
## Google Client
```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',
:redirect_uri => 'https://oauth2-login-demo.appspot.com/code',
:approval_prompt => 'force')
# => https://accounts.google.com/o/oauth2/auth?scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.email&state=%2Fprofile&redirect_uri=https%3A%2F%2Foauth2-login-demo.appspot.com%2Ftoken&approval_prompt=force&response_type=token&client_id=812741506391.apps.googleusercontent.com
```
### 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',
:redirect_uri => 'http://localhost/oauth/code',
:approval_prompt => 'force')
@@ -144,9 +191,52 @@
"id_token" : "eyJhbGciOiJSUzI1NiIsImtpZCI6IjY4ZGM2ZmIxNDQ5OGJmMWRhNjNiMWYyMDA2YmRmMDA2N2Q4MzY",
"refresh_token" : "6/Ju8uhi9xOctGEyHRzWwHhaYimfxmY0tiJ_qW3qvjWXM"
}
```
+## 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
\ No newline at end of file