Codebase list ruby-omniauth-facebook / 7bede2d
update README in preparation for 1.0. allow passing of display via option Mark Dodwell 12 years ago
3 changed file(s) with 79 addition(s) and 8 deletion(s). Raw diff Collapse all Expand all
+76
-7
README.md less more
00 # OmniAuth Facebook  [![Build Status](http://travis-ci.org/mkdynamic/omniauth-facebook.png?branch=master)](http://travis-ci.org/mkdynamic/omniauth-facebook)
11
22 This gem contains the Facebook strategy for OmniAuth 1.0.
3
4 Supports the OAuth 2.0 server-side flow. Read the Facebook docs for more details: http://developers.facebook.com/docs/authentication
35
46 ## Installing
57
68 Add to your `Gemfile`:
79
810 ```ruby
9 gem 'omniauth-facebook', '~> 1.0.0.rc1'
11 gem 'omniauth-facebook'
1012 ```
1113
1214 Then `bundle install`.
1315
14 ## Supported Flows
16 ## Usage
1517
16 Supports the Server-side Flow as described in the the Facebook docs:
17 http://developers.facebook.com/docs/authentication
18 `OmniAuth::Strategies::Facebook` is simply a Rack middleware. Read the OmniAuth 1.0 docs for detailed instructions: https://github.com/intridea/omniauth.
1819
19 **Pending:** Supports the Client-side Flow via parsing out the verification code from the signed request cookie.
20 Here's a quick example, adding the middleware to a Rails app in `config/initializers/omniauth.rb`:
2021
21 ## Ruby
22 ```ruby
23 Rails.application.config.middleware.use OmniAuth::Builder do
24 provider :facebook, ENV['FACEBOOK_KEY'], ENV['FACEBOOK_SECRET'], :scope => 'email', :display => 'popup'
25 end
26 ```
2227
23 Tested with the following Ruby versions:
28 ## Configuring
29
30 You can configure several options, which you pass in to the `provider` method via a `Hash`:
31
32 * `scope`: A comma-separated list of permissions you want to request from the user. See the Facebook docs for a full list of available permissions: http://developers.facebook.com/docs/reference/api/permissions. Default: `email,offline_access`
33 * `display`: The display context to show the authentication page. Options are: `page`, `popup`, `iframe`, `touch` and `wap`. Read the Facebook docs for more details: http://developers.facebook.com/docs/reference/dialogs#display. Default: `page`
34
35 For example, to request `email`, `offline_access` and `read_stream` permissions and display the authentication page in a popup window:
36
37 ```ruby
38 Rails.application.config.middleware.use OmniAuth::Builder do
39 provider :facebook, ENV['FACEBOOK_KEY'], ENV['FACEBOOK_SECRET'], :scope => 'email,offline_access,read_stream', :display => 'popup'
40 end
41 ```
42
43 *NB.* If you want to set the `display` format on a per-request basis, you can just pass it to the OmniAuth request phase URL, for example: `/auth/facebook?display=popup`.
44
45 ## Authentication Hash
46
47 Here's an example *Authentication Hash* available in `request.env['omniauth.auth']`:
48
49 ```ruby
50 {
51 :provider => 'facebook',
52 :uid => '1234567',
53 :info => {
54 :nickname => 'jbloggs',
55 :email => 'joe@bloggs.com',
56 :name => 'Joe Bloggs',
57 :first_name => 'Joe',
58 :last_name => 'Bloggs',
59 :image => 'http://graph.facebook.com/1234567/picture?type=square',
60 :urls => { :Facebook => 'http://www.facebook.com/jbloggs' },
61 :location => 'Palo Alto, California'
62 },
63 :credentials => {
64 :token => 'ABCDEF...',
65 :expires_at => 1321747205, # when the access token expires
66 :expires => true # if you request `offline_access` this will be false
67 },
68 :extra => {
69 :raw_info => {
70 :id => '1234567',
71 :name => 'Joe Bloggs',
72 :first_name => 'Joe',
73 :last_name => 'Bloggs',
74 :link => 'http://www.facebook.com/jbloggs',
75 :username => 'jbloggs',
76 :location => { :id => '123456789', :name => 'Palo Alto, California' },
77 :gender => 'male',
78 :email => 'joe@bloggs.com',
79 :timezone => -8,
80 :locale => 'en_US',
81 :verified => true,
82 :updated_time => '2011-11-11T06:21:03+0000'
83 }
84 }
85 }
86 ```
87
88 The precise information available may depend on the permissions which you request.
89
90 ## Supported Rubies
91
92 Actively tested with the following Ruby versions:
2493
2594 - MRI 1.9.3
2695 - MRI 1.9.2
+1
-1
example/config.ru less more
2020 use Rack::Session::Cookie
2121
2222 use OmniAuth::Builder do
23 provider :facebook, ENV['APP_ID'], ENV['APP_SECRET'], :scope => 'email,read_stream', :authorize_params => { :display => 'popup' }
23 provider :facebook, ENV['APP_ID'], ENV['APP_SECRET'], :scope => 'email,read_stream', :display => 'popup'
2424 end
2525
2626 run App.new
+2
-0
lib/omniauth/strategies/facebook.rb less more
1717 :header_format => 'OAuth %s',
1818 :param_name => 'access_token'
1919 }
20
21 option :authorize_options, [:scope, :display]
2022
2123 uid { raw_info['id'] }
2224