Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 97 lines (64 sloc) 3.692 kb
13ff555 @mislav initial import of middleware (v0.1.0)
authored
1 Drop-in login functionality for your webapp
2 ===========================================
3
2f78d1e @mislav update stale docs to indicate there is no longer Rack middleware
authored
4 Mount this Rack endpoint in your web application to enable user logins through Twitter.
13ff555 @mislav initial import of middleware (v0.1.0)
authored
5
4d503be @mislav add our apps that use "twitter-login" to the docs
authored
6 Check out the sister project, ["facebook-login"][facebook].
13ff555 @mislav initial import of middleware (v0.1.0)
authored
7
8 How to use
9 ----------
10
11 First, [register a new Twitter application][register] (if you haven't already). Check
12 the <i>"Yes, use Twitter for login"</i> option. You can put anything as <i>"Callback
13 URL"</i> since the real callback URL is provided dynamically, anyway. Note down your
14 OAuth consumer key and secret.
15
16 You have to require 'twitter/login' in your app. If you're using Bundler:
17
18 ## Gemfile
2f78d1e @mislav update stale docs to indicate there is no longer Rack middleware
authored
19 gem 'twitter-login', '~> 0.4.1', :require => 'twitter/login'
13ff555 @mislav initial import of middleware (v0.1.0)
authored
20
2f78d1e @mislav update stale docs to indicate there is no longer Rack middleware
authored
21 Now mount the Rack endpoint in your application. In **Rails 3** this would be:
f273aea @mislav change Rails instructions to pass class name as string for `config.mi…
authored
22
2f78d1e @mislav update stale docs to indicate there is no longer Rack middleware
authored
23 ## application.rb:
24 config.twitter_login = Twitter::Login.new \
25 :consumer_key => 'CONSUMER_KEY', :secret => 'SECRET'
26
27
28 ## routes.rb
29 twitter = YourApp::Application.config.twitter_login
30 twitter_endpoint = twitter.login_handler(:return_to => '/')
f273aea @mislav change Rails instructions to pass class name as string for `config.mi…
authored
31
2f78d1e @mislav update stale docs to indicate there is no longer Rack middleware
authored
32 mount twitter_endpoint => 'login', :as => :login
13ff555 @mislav initial import of middleware (v0.1.0)
authored
33
2f78d1e @mislav update stale docs to indicate there is no longer Rack middleware
authored
34
35 ## application_controller.rb
13ff555 @mislav initial import of middleware (v0.1.0)
authored
36 include Twitter::Login::Helpers
2f78d1e @mislav update stale docs to indicate there is no longer Rack middleware
authored
37
38 def logged_in?
39 !!session[:twitter_user]
40 end
41 helper_method :logged_in?
42
13ff555 @mislav initial import of middleware (v0.1.0)
authored
43
47a2a6c @mislav don't store consumer key/secret in session. slight API changes
authored
44 Fill in the `:consumer_key`, `:secret` placeholders with real values. You're done.
13ff555 @mislav initial import of middleware (v0.1.0)
authored
45
2f78d1e @mislav update stale docs to indicate there is no longer Rack middleware
authored
46 It is less trivial to mount a Rack endpoint in **Rails 2** or Sinatra.
47 This library was once Rack *middleware*, and if you prefer to use that, install the 0.3.x
48 version and [check out the "middleware-0.3" branch][middleware].
49
13ff555 @mislav initial import of middleware (v0.1.0)
authored
50
51 What it does
52 ------------
53
2f78d1e @mislav update stale docs to indicate there is no longer Rack middleware
authored
54 The user will first get redirected to Twitter to approve your application. After that he
55 or she is redirected back to your app with an OAuth verifier GET parameter. Then, the
56 authenticating user is identified, this info is saved to session and the user is sent back
57 to the root path of your website.
13ff555 @mislav initial import of middleware (v0.1.0)
authored
58
59
60 Configuration
61 -------------
62
2f78d1e @mislav update stale docs to indicate there is no longer Rack middleware
authored
63 Available options for `Twitter::Login` are:
13ff555 @mislav initial import of middleware (v0.1.0)
authored
64
47a2a6c @mislav don't store consumer key/secret in session. slight API changes
authored
65 * `:consumer_key` -- OAuth consumer key *(required)*
13ff555 @mislav initial import of middleware (v0.1.0)
authored
66 * `:secret` -- OAuth secret *(required)*
2f78d1e @mislav update stale docs to indicate there is no longer Rack middleware
authored
67 * `:site` -- the API endpoint that is used (default: "http://api.twitter.com")
13ff555 @mislav initial import of middleware (v0.1.0)
authored
68 * `:return_to` -- where user goes after login (default: "/")
69
70
71 Helpers
72 -------
73
74 The `Twitter::Login::Helpers` module (for Sinatra, Rails) adds these methods to your app:
75
76 * `twitter_user` (Hashie::Mash) -- Info about authenticated user. Check this object to
77 know whether there is a currently logged-in user. Access user data like `twitter_user.screen_name`
78 * `twitter_logout` -- Erases info about Twitter login from session, effectively logging-out the Twitter user
2f78d1e @mislav update stale docs to indicate there is no longer Rack middleware
authored
79 * `twitter_client` (OAuth::AccessToken) -- A consumer token able to query the API, e.g. `twitter_client.get('/1/path')`
13ff555 @mislav initial import of middleware (v0.1.0)
authored
80
4d503be @mislav add our apps that use "twitter-login" to the docs
authored
81
82 Apps that use "twitter-login"
83 -----------------------------
84
85 * [The Movie App][movieapp] ([source code](https://github.com/mislav/movieapp))
86 * [config/application.rb](https://github.com/mislav/movieapp/blob/b8f6bd9/config/application.rb#L48-49)
87 * [config/routes.rb](https://github.com/mislav/movieapp/blob/b8f6bd9/config/routes.rb#L18-23)
88 * [application_controller.rb](https://github.com/mislav/movieapp/blob/b8f6bd9/app/controllers/application_controller.rb#L4-43)
89 * [sessions_controller.rb](https://github.com/mislav/movieapp/blob/b8f6bd9/app/controllers/sessions_controller.rb#L11-32)
90 * [Todas Listas][todo] ([source code](https://github.com/ivana/todofrenzy))
91
13ff555 @mislav initial import of middleware (v0.1.0)
authored
92 [register]: http://twitter.com/apps/new
2f78d1e @mislav update stale docs to indicate there is no longer Rack middleware
authored
93 [middleware]: https://github.com/mislav/twitter-login/tree/middleware-0.3#readme
4d503be @mislav add our apps that use "twitter-login" to the docs
authored
94 [movieapp]: http://movi.im/
95 [todo]: http://todaslistas.heroku.com/
96 [facebook]: https://github.com/mislav/facebook#readme
Something went wrong with that request. Please try again.