Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 106 lines (64 sloc) 7.029 kB
152d76c Initial commit, includes some basic specs and setup.
Michael Bleigh authored
1 TwitterAuth
2 ===========
3
4 TwitterAuth aims to provide a complete authentication and API access solution for creating Twitter applications in Rails. It provides a generator and all of the necessary components to use Twitter as the sole authentication provider for an application using either Twitter's OAuth or HTTP Basic authentication strategies.
5
6 Installation
7 ============
8
9 You can include TwitterAuth as a gem in your project like so:
10
a71312d Trying to set up for RubyForge.
Michael Bleigh authored
11 config.gem 'twitter-auth', :lib => 'twitter_auth'
152d76c Initial commit, includes some basic specs and setup.
Michael Bleigh authored
12
13 Or you can install it as a traditional Rails plugin:
14
2e4be42 Adding things to 1.0_dev
Michael Bleigh authored
15 script/plugin install git://github.com/mbleigh/twitter-auth.git
152d76c Initial commit, includes some basic specs and setup.
Michael Bleigh authored
16
17 Note that because TwitterAuth utilizes Rails Engines functionality introduced in Rails 2.3, it will not work with earlier versions of Rails.
18
4088ed0 Added in the Cryptify module for password encryption with specs. Firs…
Michael Bleigh authored
19 **NOTE:** TwitterAuth requires Rails version 2.3 or later because it makes extensive use of the new support for Rails Engines. Previous versions of Rails are not supported.
20
152d76c Initial commit, includes some basic specs and setup.
Michael Bleigh authored
21 Usage
22 =====
23
24 To utilize TwitterAuth in your application you will need to run the generator:
25
8b9bdf1 Added Dispatcher classes to perform API calls without depending on an…
Michael Bleigh authored
26 script/generate twitter_auth [--oauth (default) | --basic]
4088ed0 Added in the Cryptify module for password encryption with specs. Firs…
Michael Bleigh authored
27
28 This will generate a migration as well as set up the stubs needed to use the Rails Engines controllers and models set up by TwitterAuth. It will also create a User class that inherits from TwitterUser, abstracting away all of the Twitter authentication functionality and leaving you a blank slate to work with for your application.
152d76c Initial commit, includes some basic specs and setup.
Michael Bleigh authored
29
4088ed0 Added in the Cryptify module for password encryption with specs. Firs…
Michael Bleigh authored
30 Finally, it will create a configuration file in `config/twitter_auth.yml` in which you should input your OAuth consumer key and secret (if using the OAuth strategy) as well as a custom callback for development (the `oauth_callback` option is where Twitter will send the browser after authentication is complete. If you leave it blank Twitter will send it to the URL set up when you registered your application).
152d76c Initial commit, includes some basic specs and setup.
Michael Bleigh authored
31
4b8856e Updated README for Sign in with Twitter
Michael Bleigh authored
32 Sign in with Twitter
33 --------------------
34
50d1187 Updated README again.
Michael Bleigh authored
35 Twitter recently implemented a convenience layer on top of OAuth called [Sign in with Twitter](http://apiwiki.twitter.com/Sign-in-with-Twitter). TwitterAuth makes use of this by default in newly generated applications by setting the `authorize_path` in `twitter_auth.yml`.
4b8856e Updated README for Sign in with Twitter
Michael Bleigh authored
36
37 If you already have an application utilizing TwitterAuth that you would like to utilize the new system, simply add this line to your `twitter_auth.yml` in each environment:
38
39 authorize_path: "/oauth/authenticate"
40
208c0ef Documentation update.
Michael Bleigh authored
41 Usage Basics
42 ------------
43
4088ed0 Added in the Cryptify module for password encryption with specs. Firs…
Michael Bleigh authored
44 If you need more information about how to use OAuth with Twitter, please visit Twitter's [OAuth FAQ](http://apiwiki.twitter.com/OAuth-FAQ).
45
46 TwitterAuth borrows heavily from [Restful Authentication](http://github.com/technoweenie/restful-authentication) for its API because it's simple and well-known. Here are some of the familiar methods that are available:
208c0ef Documentation update.
Michael Bleigh authored
47
48 * `login_required`: a before filter that can be added to a controller to require that a user logs in before he/she can view the page.
49 * `current_user`: returns the logged in user if one exists, otherwise returns `nil`.
50 * `logged_in?`: true if logged in, false otherwise.
51 * `redirect_back_or_default(url)`: redirects to the location where `store_location` was last called or the specified default URL.
52 * `store_location`: store the current URL for returning to when a `redirect_back_or_default` is called.
53 * `authorized?`: override this to add fine-grained access control for when `login_required` is already called.
54
784e9c9 Updated docs.
Michael Bleigh authored
55 Accessing the Twitter API
56 -------------------------
57
58 Obviously if you're using Twitter as an authentication strategy you probably have interest in accessing Twitter API information as well. Because I wasn't really satisfied with either of the popular Twitter API Ruby libraries ([Twitter4R](http://twitter4r.rubyforge.org) and [Twitter](http://twitter.rubyforge.org)) and also because neither support OAuth (yet), I decided to go with a simple, dependency-free API implementation.
59
60 The `User` class will have a `twitter` method that provides a generic dispatcher with HTTP verb commands available (`get`, `put`, `post`, and `delete`). These are automatically initialized to the `base_url` you specified in the `twitter_auth.yml` file, so you need only specify a path. Additionally, it will automatically append a .json extension and parse the JSON if you don't provide (it returns strings for XML because, well, I don't like XML and don't feel like parsing it).
61
62 # This code will work with the OAuth and Basic strategies alike.
63 user = User.find_by_login('mbleigh')
64
65 user.twitter.get('/account/verify_credentials')
66 # => {'screen_name' => 'mbleigh', 'name' => 'Michael Bleigh' ... }
67
68 user.twitter.post('/statuses/update.json', 'status' => 'This is my status.')
69 # => {"user"=>{"login" => "mbleigh" ... }, "text"=>"This is my status.", "id"=>1234567890 ... }
70
7332d1a Adding dispatcher error handling to README.
Michael Bleigh authored
71 If Twitter returns something other than a 200 response code, TwitterAuth will catch it and try to raise a salient error message. The exception class is `TwitterAuth::Dispatcher::Error` if you're in the mood to catch it.
72
784e9c9 Updated docs.
Michael Bleigh authored
73 This area of the code is still a little raw, but hopefully will evolve to be a little more user-friendly as TwitterAuth matures. In the meantime, it's a perfectly workable foundation library, and the fact that it works the same with OAuth and HTTP Basic makes it all the better!
74
bd42bbb Abstracted authorization_failed into its own method, more specs and w…
Michael Bleigh authored
75 Customizing TwitterAuth
76 -----------------------
77
78 There are a number of hooks to extend the functionality of TwitterAuth. Here is a brief description of each of them.
79
80 ### Controller Methods
81
fa9b42c Fixed up authentication callbacks.
Michael Bleigh authored
82 TwitterAuth provides some default controller methods that may be overridden in your `ApplicationController` to behave differently.
bd42bbb Abstracted authorization_failed into its own method, more specs and w…
Michael Bleigh authored
83
208c0ef Documentation update.
Michael Bleigh authored
84 * `authentication_failed(message)`: called when Twitter authorization has failed during the process. By default, simply redirects to the site root and sets the `flash[:error]`.
85 * `authentication_succeeded(message=default)`: called when Twitter authorization has completed successfully. By default, simply redirects to the site root and sets the `flash[:notice]`.
86 * `access_denied`: what happens when the `login_required` before filter fails. By default it stores the current location to return to and redirects to the login process.
87
708a665 Added some more info to README in resources section.
Michael Bleigh authored
88 Tips and Tricks
89 ---------------
90
91 * If you are getting an `OpenSSL::SSL:SSLError (certificate verify failed)` you may want to [see this ticket and comments](https://mbleigh.lighthouseapp.com/projects/27783-twitterauth/tickets/6-error-on-login#ticket-6-2).
92
c5d76c2 Added lighthouse to README.
Michael Bleigh authored
93 Resources
94 ---------
95
4b8856e Updated README for Sign in with Twitter
Michael Bleigh authored
96 * **Bug Reports:** See the [Issues Page](http://github.com/mbleigh/twitter-auth/issues) to report any problems you have using TwitterAuth.
708a665 Added some more info to README in resources section.
Michael Bleigh authored
97 * **Blog Post:** The [original blog post about TwitterAuth](http://intridea.com/2009/3/23/twitter-auth-for-near-instant-twitter-apps) has a tutorial as well to get you started.
98 * **GitHub Pages:** TwitterAuth has a [simple GitHub page](http://mbleigh.com/twitter-auth)
bd42bbb Abstracted authorization_failed into its own method, more specs and w…
Michael Bleigh authored
99
c34d3f4 We're moving right along here...OAuth is essentially complete. Seriou…
Michael Bleigh authored
100 Copyright
101 ---------
fa9b42c Fixed up authentication callbacks.
Michael Bleigh authored
102
c34d3f4 We're moving right along here...OAuth is essentially complete. Seriou…
Michael Bleigh authored
103 **TwitterAuth** is Copyright (c) 2009 [Michael Bleigh](http://www.mbleigh.com) and [Intridea, Inc.](http://www.intridea.com/), released under the MIT License.
fa9b42c Fixed up authentication callbacks.
Michael Bleigh authored
104
c34d3f4 We're moving right along here...OAuth is essentially complete. Seriou…
Michael Bleigh authored
105 TwitterAuth is not affiliated with Twitter, Inc.
Something went wrong with that request. Please try again.