Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 77 lines (51 sloc) 2.742 kb
13ff555 @mislav initial import of middleware (v0.1.0)
authored
1 Drop-in login functionality for your webapp
2 ===========================================
3
4 Drop this Rack middleware in your web application to enable user logins through Twitter.
5
8e52b3d @mislav correct docs for `twitter_client` helper
authored
6 Newer versions of "twitter-login" are a Rack endpoint rather than middleware. Check this
7 out in the ["master" branch][master].
13ff555 @mislav initial import of middleware (v0.1.0)
authored
8
9 How to use
10 ----------
11
12 First, [register a new Twitter application][register] (if you haven't already). Check
13 the <i>"Yes, use Twitter for login"</i> option. You can put anything as <i>"Callback
14 URL"</i> since the real callback URL is provided dynamically, anyway. Note down your
15 OAuth consumer key and secret.
16
17 You have to require 'twitter/login' in your app. If you're using Bundler:
18
19 ## Gemfile
ce83bb9 @mislav update README
authored
20 gem 'twitter-login', '~> 0.3.1', :require => 'twitter/login'
13ff555 @mislav initial import of middleware (v0.1.0)
authored
21
22 Now configure your app to use the middleware. This might be different across web
f273aea @mislav change Rails instructions to pass class name as string for `config.mi…
authored
23 frameworks. For Sinatra this would be:
13ff555 @mislav initial import of middleware (v0.1.0)
authored
24
25 ## Sinatra
26 enable :sessions
47a2a6c @mislav don't store consumer key/secret in session. slight API changes
authored
27 use Twitter::Login, :consumer_key => 'KEY', :secret => 'SECRET'
13ff555 @mislav initial import of middleware (v0.1.0)
authored
28 helpers Twitter::Login::Helpers
f273aea @mislav change Rails instructions to pass class name as string for `config.mi…
authored
29
30 In Rails:
31
13ff555 @mislav initial import of middleware (v0.1.0)
authored
32 ## Rails
33 # environment.rb:
f273aea @mislav change Rails instructions to pass class name as string for `config.mi…
authored
34 config.middleware.use 'Twitter::Login', :consumer_key => 'KEY', :secret => 'SECRET'
13ff555 @mislav initial import of middleware (v0.1.0)
authored
35
36 # application_controller.rb
37 include Twitter::Login::Helpers
38
47a2a6c @mislav don't store consumer key/secret in session. slight API changes
authored
39 Fill in the `:consumer_key`, `:secret` placeholders with real values. You're done.
13ff555 @mislav initial import of middleware (v0.1.0)
authored
40
41
42 What it does
43 ------------
44
45 This middleware handles GET requests to "/login" resource of your app. Make a login
46 link that points to "/login" and you're all set to receive logins from Twitter.
47
48 The user will first be redirected to Twitter to approve your application. After that he
49 or she is redirected back to "/login" with an OAuth verifier GET parameter. The
50 middleware then identifies the authenticating user, saves this info to session and
51 redirects to the root of your website.
52
53
54 Configuration
55 -------------
56
57 Available options for `Twitter::Login` middleware are:
58
47a2a6c @mislav don't store consumer key/secret in session. slight API changes
authored
59 * `:consumer_key` -- OAuth consumer key *(required)*
13ff555 @mislav initial import of middleware (v0.1.0)
authored
60 * `:secret` -- OAuth secret *(required)*
61 * `:login_path` -- where user goes to login (default: "/login")
62 * `:return_to` -- where user goes after login (default: "/")
63
64
65 Helpers
66 -------
67
68 The `Twitter::Login::Helpers` module (for Sinatra, Rails) adds these methods to your app:
69
70 * `twitter_user` (Hashie::Mash) -- Info about authenticated user. Check this object to
71 know whether there is a currently logged-in user. Access user data like `twitter_user.screen_name`
72 * `twitter_logout` -- Erases info about Twitter login from session, effectively logging-out the Twitter user
8e52b3d @mislav correct docs for `twitter_client` helper
authored
73 * `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
74
75 [register]: http://twitter.com/apps/new
8e52b3d @mislav correct docs for `twitter_client` helper
authored
76 [master]: https://github.com/mislav/twitter-login#readme
Something went wrong with that request. Please try again.