Solidus Social

Social login support for Solidus. Solidus Social handles authorization, account creation and association through third-party services. Currently Twitter, Facebook, Github, Google OAuth2, and Amazon are available out of the box.

Installation

Add this extension to your Gemfile:

gem 'solidus_social'

Then run:

$ bundle && bundle exec rails g solidus_social:install
$ bundle exec rake db:migrate

Optional: By default the login path will be '/users/auth/:provider'. If you want something else, configure it in config/initializers/solidus_social.rb.

Spree::SocialConfig[:path_prefix] = 'member'  # for /member/auth/:provider
Spree::SocialConfig[:path_prefix] = 'profile' # for /profile/auth/:provider
Spree::SocialConfig[:path_prefix] = ''        # for /auth/:provider

Using OAuth Sources

Login as an admin user and navigate to Configuration > Social Authentication Methods

Click "New Authentication Method" and enter your API key for the service. (See below for instructions on setting up the different providers.)

Multiple key entries can now be entered based on the Rails environment. This allows for portability and the lack of need to check in your key to your repository. You also have the ability to enable and disable sources. These setting will be reflected on the client UI as well.

If you store your configuration/credentials in environment variables, you can create Authentication Methods on application boot via an initializer if they don't already exist.

# Ensure our environment is bootstrapped with a Facebook Connect app
if ActiveRecord::Base.connection.table_exists? 'spree_authentication_methods'
  Spree::AuthenticationMethod.where(environment: Rails.env, provider: 'facebook').first_or_create do |auth_method|
    auth_method.api_key = ENV['FACEBOOK_APP_ID']
    auth_method.api_secret = ENV['FACEBOOK_APP_SECRET']
    auth_method.active = true
  end
end

You MUST restart your application after configuring or updating an authentication method.

Registering Your Application

Facebook, Twitter, Github, Google OAuth2, and Amazon are supported out of the box but, you will need to register your application with each of the sites you want to use.

When setting up development applications, keep in mind that most services do not support localhost for your URL/domain. You will need to us a regular domain (i.e. domain.tld, hostname.local) or an IP addresses (127.0.0.1). Make sure you specifity the right IP address.

Facebook

Facebook / Developers / Apps

1. Name the app and agree to the terms.
2. Fill out the capcha.
3. Under the "Web Site" tab enter:

• Site URL: http://yourhostname.local:3000 for development and http://your-site.com for production
• Site domain: yourhostname.local and your-site.com respectively

Twitter

Twitter / Application Management / Create an application

1. Fill in the name and description.
2. Fill in the rest of the details:

• Application Website: http://yourhostname.local:3000 for development and http://your-site.com for production
• Application Type: "Browser"
• Callback URL: http://yourhostname.local:3000 for development and http://your-site.com` for production
• Default Access Type: "Read & Write"

6. Save the application.

Github

Github / Applications / Register a new OAuth application

1. Name the application.
2. Fill in the details

• Main URL: http://yourhostname.local:3000 for development and http://your-site.com for production
• Callback URL: http://yourhostname.local:3000 for development and http://your-site.com for production

4. Click Create.

Amazon

Amazon / App Console / Register a new OAuth application

1. Register New Application.
2. Name the Application, provide description and URL for Privacy Policy.
3. Click Save.
4. Add Your site under Web Settings > Allowed Return URLs (example: http://localhost:3000/users/auth/amazon/callback)

The app console is available at https://login.amazon.com/manageApps

Google OAuth2

TODO: Write instructions.

Other OAuth Providers

Other OAuth providers are supported, given that there is an OmniAuth strategy for them. (If there isn't, you can write one.)

LinkedIn Example

1. Add gem "omniauth-linkedin" to your Gemfile and run bundle install.

2. In config/initializers/solidus_social.rb add and initialize a new provider for SolidusSocial:

   SolidusSocial::OAUTH_PROVIDERS << ['LinkedIn', 'linkedin']
   SolidusSocial.init_provider('linkedin')

3. Activate your provider as usual (via initializer or admin interface).

4. Do one of the following:

   • Override the spree/users/social view to render OAuth links to display your LinkedIn link.
   • Include in your CSS a definition for .icon-spree-linkedin-circled and an embedded icon font for LinkedIn from Fontello (the way existing icons for Facebook, Twitter, etc are implemented). You can also override CSS classes for other providers, .icon-spree-<provider>-circled, to use different font icons or classic background images, without having to override views.

Documentation

API documentation is available on RubyDoc.info.

Contributing

See corresponding guidelines.

Copyright (c) 2014 John Dyer and contributors, released under the New BSD License