Fb::Auth

Fb::Auth can authenticate a Facebook user and return an access token with permission to manage pages of that user.

Build Status Coverage Status Dependency Status Code Climate Online docs Gem Version

The source code is available on GitHub and the documentation on RubyDoc.

Installing and Configuring Fb::Auth

First, add fb-auth to your Gemfile:

gem 'fb-auth'

Then run bundle install.

Fb::Auth will require an Client ID and an Client Secret which you can obtain after registering as a developer on Facebook for developers.

By default, Fb::Auth will look for the environment variables called FB_CLIENT_ID and FB_CLIENT_SECRET. You can put those keys in your .bash_profile and Fb::Auth will work.

export FB_CLIENT_ID="YourAppID"
export FB_CLIENT_SECRET="YourAppSecret"

Usage

Fb::Auth#url

The url method helps you obtain a URL where to redirect users who need to authenticate with their Facebook account in order to use your application:

redirect_uri = 'https://example.com/auth' # REPLACE WITH REAL ONE
Fb::Auth.new(redirect_uri: redirect_uri).url
 # => https://www.facebook.com/dialog/oauth?client_id=...&scope=manage_pages&redirect_uri=https%3A%2F%2Fexample.com%2Fauth

Note that access is always requested with permission to access email, manage pages and read insights.

Fb::Auth#access_token

After users have authenticated with their Facebook account, they will be redirected to the redirect_uri you indicated, with an extra code query parameter, e.g. https://example.com/auth?code=1234#_=_

The access_token method allows you to get a non-expiring access token of the user:

redirect_uri = 'https://example.com/auth' # REPLACE WITH REAL ONE
code = '1234#_=_' # REPLACE WITH REAL ONE
Fb::Auth.new(redirect_uri: redirect_uri, code: code).access_token
 # => "kefjej49s82hFS@2333233222FDh66"

Development

After checking out the repo, run bin/setup to install dependencies. If you would like to run tests for Fb::Auth, please obtain a long-term access token that manages at least one page and has permission to read your Facebook email (set scope to include email, pages_show_list, & read_insights). Then set the token as as an environment variable:

export FB_TEST_ACCESS_TOKEN="YourToken"

Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Fullscreen/fb-auth. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.