sinatra_omniauth

= sinatra_omniauth

Sinatra OmniAuth provides a Sinatra extension for adding pure OmniAuth authentication to your Sinatra application. "Pure" here means that you don't even need a username on the system, let alone a password; you just sign in using one of your existing social media accounts.

SinatraOmniAuth uses DataMapper and Haml, though you can write your own templates too. SinatraOmniAuth uses the wonderful icon set from https://github.com/intridea/authbuttons

== Description

Read Markus Proske's full article "Omniauth pure: Authentication with Facebook, Google, Google Apps, Twitter, Github, AOL, MyOpenID and many other OpenID providers" on CommunityGuides. Copyright (c) 2011 Markus Proske Copyright (c) 2011 Clifford Heath

This article demonstrates how to set up a multi-provider authentication in Rails using the fabulous Omniauth gem. Users can add multiple providers to their account and views for sign-in, sign-up and management of linked accounts are provided. The full source code is available on Github as a basis for your own projects.

This gem, sinatra_omniauth, provides a partial clone of the Omniauth_pure functionality, but as a Sinatra extension using DataMapper and various other goodies.

== Using sinatra_omniauth

In your Gemfile, add:

gem 'sinatra_omniauth'

In the root directory of your app (same dir as config.ru), add your API keys to "omniauth.yml"

In your application:

require 'sinatra/omniauth'

set :omniauth, YAML.load_file(File.dirname(__FILE__)+"/omniauth.yml")

register SinatraOmniAuth

Models: Copy user.rb and authentication.rb from the models directory, and add any other fields and relationships you need.

Routes which SinatraOmniAuth will handle (you may override these if needed): /auth presents a list of configured authentication services, including the user's current sign-in account and any other registered accounts. This page also includes a signout link and the ability to delete secondary authentication methods. /auth/signout Signs the user out immediately and redirects to '/' /auth//callback This URL is triggered when the authentication service redirects the user's browser here, after a successful authentication. The handler signs in the user, who may be a new user just joining, an existing user adding a new authentication method, or an existing user signing in or changing to a different authentication method /auth/failure Sets a flash saying that the authorization failed before redirecting to . /auth/:id A POST here with the magic _method=delete will delete this authentication method from the current user's account

Views: Copy views/auth.haml and css/auth.css to wherever they will be found.

Note that auth.haml uses assets helpers include_javascripts and include_stylesheets
to load packed or unpacked JS (jQuery required) and CSS. Youy'll be wanting to
style it all up yourself anyhow, but when you're there, replace the helpers as needed.

Images: Use the authbuttons images as noted. auth.haml expects them to be in </images/authbuttons/>

Helper methods: authenticate_user! Redirects to /auth if the user is not already signed in current_user The User record of the current signed-in user current_auth The Authentication record with which the user is signed in. Note that for most authentication services, this includes the user's name and email address.

Make sure you add a handler for the following routes: get '/auth/welcome' - When a new user first joins get '/auth/signedin' - When the user signs in

These handlers may simply set a flash and redirect to another place.

Oh, did I say flash? SinatraOmniAuth uses the "rack-flash" gem, so you can say:

flash.notice = "Welcome back!"; redirect to('/')
... and also access flash.error, flash.notice, etc, in your views.

== Contributing to sinatra_omniauth

• Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
• Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
• Fork the project
• Start a feature/bugfix branch
• Commit and push until you are happy with your contribution
• Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

== Credits:

Omniauth: http://github.com/intridea/omniauth authbuttons: http://github.com/intridea/authbuttons Omniauth pure and article: Markus Proske

== Copyright

Copyright (c) 2011 Clifford Heath. MIT Licensed. See LICENSE.txt for further details.