Clef + Rails

Getting started

Clef is secure two-factor auth without passwords. With the wave of their phone, users can log in to your site — it's like ✨ magic ✨!

Get started in three easy steps:

• Download the iOS or Android app on your phone
• Sign up for a Clef developer account at https://www.getclef.com/developer and create an application. That's where you'll get your API credentials (app_id and app_secret) and manage settings for your Clef integration.
• Follow the directions below to integrate Clef into your site's log in flow.

Usage

We'll walk you through the full Clef integration with Ruby and Rails below. You can also run this sample app locally.

Adding the Clef button

The Clef button is the entry point into the Clef experience. Adding it to your site is as easy as dropping a script tag wherever you want the button to show up.

Set the data-redirect-url to the URL in your app where you will complete the OAuth handshake. You'll also want to set data-state to an unguessable random string.

<script type='text/javascript' 
    class='clef-button' 
    src='https://clef.io/v3/clef.js' 
    data-app-id='YOUR_APP_ID' 
    data-redirect-url='http://localhost:3000/auth/clef/callback' 
    data-state='<%= state_parameter %>'>
</script>

See the code in action or read more here.

Completing the OAuth handshake

Once you've set up the Clef button, you need to be able to handle the OAuth handshake. This is what lets you retrieve information about a user after they authenticate with Clef. The easiest way to do this is to use OmniAuth, which you should add to your Gemfile:

$ gem 'omniauth-clef'

Configure it with your app_id and app_secret in a config/initializers/omniauth.rb file.

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :clef, 'YOUR_APP_ID', 'YOUR_APP_SECRET'
end

Clef requires verifying the state parameter in the OAuth handhsake. OmniAuth handles verification for you, but you'll need to generate the parameter in your own helper method in users_controller.rb and pass it to the Clef button.

When you handle the OmniAuth callback, you can get or create a user from your database and set them in the session.

# POST /users
# POST /users.json
def create
  @user = User.find_or_create_from_auth_hash(request.env['omniauth.auth'])

  respond_to do |format|
    if @user.save
      if @user.persisted?
        notice = "User was logged in."
      else
        notice = "User was created."
      end
      session[:user] = @user.id
      format.html { redirect_to @user, notice: notice }
      format.json { render json: @user, status: :created, location: @user }
    else
      format.html { render action: "new" }
      format.json { render json: @user.errors, status: :unprocessable_entity }
    end
  end
end

See the code in action or read more here.

Running this sample app

To run this sample app, clone the repo:

$ git clone https://github.com/clef/sample-rails.git

Then install the dependencies, set up a local database and run on localhost.

$ bundle install
$ rails generate scaffold User email:string clef_id:integer
$ rake db:migrate
$ rails s 

Documentation

You can find our most up-to-date documentation at http://docs.getclef.com. It covers additional topics like customizing the Clef button and testing your integration.

Support

Have a question or just want to chat? Send an email to [[email protected]](mailto: [email protected]).

We're always around, but we do an official Q&A every Friday from 10am to noon PST :) — would love to see you there!

About

Clef is an Oakland-based company building a better way to log in online. We power logins on more than 80,000 websites and are building a beautiful experience and inclusive culture. Read more about our values, and if you like what you see, come work with us!