Userbin for Ruby

Userbin for Ruby adds user authentication, login flows and user management to your Rails, Sinatra or Rack app, with users stored in your own database.

Userbin provides a set of login, signup, and password reset forms that drop right into your application without any need of styling or writing markup. Connect your users via traditional logins or third party social networks. It takes care of linking accounts across networks, resetting passwords, and keeping everything safe and secure.

Create a free account at Userbin to start accepting users in your application.

Installation

Add the userbin gem to your Gemfile
```
gem "userbin"
```
Install the gem
```
bundle install
```
Generate configuration
```
curl https://lib.userbin.com/install.sh | sh YOUR_APP_ID YOUR_API_SECRET
```
If you don't configure the App ID and API Secret, the Userbin module will read the USERBIN_APP_ID and USERBIN_API_SECRET environment variables. This may come in handy on Heroku.
Rack/Sinatra apps only: Load and activate the Userbin Rack middleware
```
require 'userbin'

use Userbin::Authentication
```

Configuration

Authenticating

You need to configure Userbin in order to provide the current_user model:

Userbin.configure do
  current_user do |profile|
    User.find(profile.uid).first_or_initialize(
      email: profile.email,
      image: profile.image
    )
  end
end

This code is run in the context of your application so you have access to your models, session or routes helpers. However, since this code is not run in the context of your application's ApplicationController it doesn't have access to the methods defined over there.

Protecting routes

Use authorize to control access in controllers:

class ArticlesController < ApplicationController
  before_filter :authorize

  def index
    current_user.articles
  end
end

Or, you can authorize users in config/routes.rb:

Blog::Application.routes.draw do
  constraints Userbin::Protect.new { |user| user.admin? } do
    root to: 'admin'
  end

  constraints Userbin::Protect.new do
    mount MagicalWorker
  end
end

Usage

The current user

Userbin keeps track of the currently logged in user which can be accessed through the current_user property. This automatically taps into libraries such as the authorization solution CanCan.

Welcome to your account, <%= current_user.email %>

To check if a user is logged in, use user_logged_in? (or its alias user_signed_in? if you prefer Devise conventions)

<% if user_logged_in? %>
  You are logged in!
<% end %>

Rack/Sinatra apps only: Since above helpers aren't available outside Rails, instead use Userbin.current_user and Userbin.user_logged_in?.

Forms

An easy way to integrate Userbin is via the Widget, which will take care of building forms, validating input and provides a drop-in design that adapts nicely to all devices.

The Widget is fairly high level, so remember that you can still use Userbin with your own forms if it doesn't fit your use-case.

Use current_user and logged_in? in controllers, views, and helpers:

- if signed_in?
  = current_user.email
  = link_to 'Log out', '/', class: 'ub-logout'
- else
  = link_to 'Sign up', '/dashboard', class: 'ub-signup'
  = link_to 'Log in', '/dashboard', class: 'ub-login'

Protecting resources

...

Configuration

The Userbin.configure block supports a range of options additional to the Userbin credentials. None of the following options are mandatory.

protected_path

By default, Userbin reloads the current page on a successful login. If you set the protected_path option, users will be redirected to this path instead.

Once set, this path and any sub-path of it will be protected from unauthenticated users by instead rendering a login form.

config.protected_path = '/dashboard'

root_path

By default, Userbin reloads the current page on a successful logout. If you set the root_path option, users will be redirected to this path instead.

config.root_path = '/login'

create_user and find_user

By default, current_user will reference a limited Userbin profile, enabling you to work without a database. If you override the functions create_user and find_user, the current user will instead reference one of your models. The profile object is an extended Userbin profile. For more information about the available attributes in the profile see the Userbin profile documentation.

config.create_user = Proc.new { |profile|
  User.create! do |user|
    user.userbin_id = profile.id
    user.email      = profile.email
    user.photo      = profile.image
  end
}

config.find_user = Proc.new { |userbin_id|
  User.find_by_userbin_id(userbin_id)
}

You'll need to migrate your users and add a reference to the Userbin profile:

rails g migration AddUserbinIdToUsers userbin_id:integer:index

skip_script_injection

By default, the Userbin middleware will automatically insert a <script> tag before the closing </body> in your HTML files in order to handle forms, sessions and user tracking. This script loads everything asynchronously, so it won't affect your page load speed. However if you want to have control of this procedure, set skip_script_injection to true and initialize the library yourself. To do that, checkout the Userbin.js configuration guide.

config.skip_script_injection = true

lock_file

By default, no locking is performed to ensure that multiple processes race for finding and creating users. Setting this option in multi-process (not multi-thread) setups like Unicorn is highly recommended.

config.lock_file = File.join(Rails.root, 'tmp/userbin.lock')

Further configuration and customization

Your Userbin dashboard gives you access to a range of functionality:

Configure the appearance of the login widget to feel more integrated with your service
Connect 10+ OAuth providers like Facebook, Github and Google.
Use Markdown to generate mobile-ready transactional emails
Invite users to your application
See who is logging in and when
User management: block, remove and impersonate users
Export all your user data from Userbin

Documentation

For complete documentation go to userbin.com/docs