Authic Client Gem

The Authic Client Gem is the quickest and easiest way to integrate your Rails 3 application with the most excellent Authic cloud authentication service. This Gem will have your Application using Authic to authenticate and manage your application’s users in about the time it takes to read this document (5-10 min - no joke!) letting you concentrate on you application’s unique value proposition and not on the mundane business of password reset forms.

Installation

In your Rails 3 or Rails 4 applications Gemfile add:

gem "authic_client"

Run bundle install from the command line:

bundle install

Generators

The authic_client gem comes with two generators to make setup a snap. After the gem is installed you can run the authic_client generators to generate configuration, database migration and model files.

To generate the initializer files config/initializers/authic.rb and config/initializers/omniauth.rb run the following from the command line:

rails g authic:install

To generate the database migration and model files run the following command from the command line:

rails g active_record:authic User

NOTE: if the User model already exists the generator will insert the appropriate attr_accessor calls at the top of your User model definition file (app/models/user.rb) and the migration is smart enough to add columns to an existing model if they don’t already exist.

Database Migration

To add the required fields to the your users table, run a database migration using the following command:

rake db:migrate

This will create/update the application’s User model to include the following fields.

t.string :email # the email address of the user
t.string :provider # always 'authic' - to be deprecated soon
t.string :uid # A unique identifier for the user assigned by Authic
t.text :authic_data # a JSON encoded varibles related to the user, e.g the user's facebook id
t.string :first_name # The first name of the user
t.string :last_name # The last name of the user
t.string :full_name # the combined first and last name of the user
t.string :mobile # the mobile (cell) phone number of the user
t.string :phone # the landline phone number of the user
t.date :birth_date # the birth date of the user
t.text :groups # which groups the user belongs to (future road map)
t.text :roles # which roles the user belongs to (future road map)
t.string :middle_name # the middle name of the user
t.string :gender # the gender of the user
t.string :timezone # the timezone in which the user is located
t.string :country # the country in which the user is located
t.text :address # the address in which the user is located

Configuration

Edit /config/initializers/authic.rb and add your Authic details. The details include your Authic client key, secret and subdomain. These values can be found on Authic’s Client Application details screen.

The initializer looks like:

module AuthicClient
  # Authic config
  AUTHIC_CLIENT_KEY ||= ENV['AUTHIC_CLIENT_KEY'] ||= '< your authic client key >'
  AUTHIC_CLIENT_SECRET ||= ENV['AUTHIC_CLIENT_SECRET'] ||= '< your authic client secret >'
  AUTHIC_CLIENT_SUBDOMAIN ||= ENV['AUTHIC_CLIENT_SUBDOMAIN'] ||= '< your authic subdomain >'
end

Just replace the <XXXX> strings between the quotes with the values. There is no need to change any other part of this file.

Alternatively you can leave the file alone and initialize these variables with heroku style environment configuration values:

AUTHIC_CLIENT_KEY: ‘< your authic client key >’
AUTHIC_CLIENT_SECRET: ‘< your authic client secret >’
AUTHIC_CLIENT_SUBDOMAIN: ‘< your authic subdomain >’

NOTE: Make sure keep the quotation marks around these values and don’t include any ‘<’ or ‘>’s.

NOTE2: For the configuration to take effect (with either style of configuration) you will need to restart your application.

Helpful Helpers

The Authic Client gem provides the following handy helper methods which are available in both your controllers and views:

current_user: Returns the current user logged into your app via Authic
login_required: Returns true if there is currently a user logged into your app, and false if not
user_account_path: This will give you the URL to the hosted user account screen in Authic. You would use it on your “edit my account” link/button
signin_path: This path will initiate sign in with Authic. You would use it on your “login” or “signin” links/buttons
signup_path: This path will initiate sign up with Authic. You would use it on your “signup” links/buttons
signout_path: Redirecting to this path will log the current user out of your app as well as Authic. You would use it on your “sign out” links/buttons

Other Useful Tidbits

Here are some other bits and pieces that might be useful while having fun using authic_client

session: Set this session variable before initiating signin and authic_client will punt your user to this path after the Oauth callback process is complete

About Authic

Authic is a secure, brandable cloud authentication service that integrates into your web app in seconds leaving you to concentrate on your core business functionality.

License

(The MIT License)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.