Otherwise, Please follow the steps below to configure your existing Ruby On Rails WebApp to use it with Auth0.

1. Add dependencies

Add the following dependencies to your Gemfile and run bundle install

gem 'omniauth', '~> 1.3.1'
gem 'omniauth-auth0', '~> 1.4.1'

2. Initialize Omniauth Auth0

Create a file named auth0.rb under config/initializers with the following content:

Rails.application.config.middleware.use OmniAuth::Builder do
  provider(
    :auth0,
    'YOUR_CLIENT_ID',
    'YOUR_CLIENT_SECRET',
    'YOUR_NAMESPACE',
    callback_path: "/auth/auth0/callback"
  )
end

3. Add the Auth0 callback handler

Use the following command to create the controller that will handle Auth0 callback:

rails generate controller auth0 callback failure --skip-template-engine --skip-assets

Now, go to the newly created controller and add the code to handle the success and failure of the callback.

class Auth0Controller < ApplicationController
  def callback
    # This stores all the user information that came from Auth0
    # and the IdP
    session[:userinfo] = request.env['omniauth.auth']

    # Redirect to the URL you want after successfull auth
    redirect_to '/dashboard'
  end

  def failure
    # show a failure page or redirect to an error page
    @error_msg = request.params['message']
  end
end

Now, replace the generated routes on routes.rb with the following ones:

get "/auth/auth0/callback" => "auth0#callback"
get "/auth/failure" => "auth0#failure"

4. Specify the callback on Auth0 Dashboard

http://YOUR_APP/callback

In this case, the callbackURL should look something like:

http://yourUrl/auth/auth0/callback

5. Triggering login manually or integrating the Auth0Lock

For more information on using Lock see the documentation.

<script src="https://cdn.auth0.com/js/lock/10.2/lock.min.js"></script>
<script>
  var lock = new Auth0Lock('YOUR_CLIENT_ID', 'YOUR_NAMESPACE', {
    auth: {
      redirectUrl: 'http://YOUR_APP/callback',
      responseType: 'code',
      params: {
        scope: 'openid email' // Learn about scopes: https://auth0.com/docs/scopes
      }
    }
  });
</script>
<button onclick="lock.show();">Login</button>

<div id="root" style="width: 320px; margin: 40px auto; padding: 10px; border-style: dashed; border-width: 1px; box-sizing: border-box;">
    embedded area
</div>
<script src="https://cdn.auth0.com/js/lock/10.2/lock.min.js"></script>
<script>
  var lock = new Auth0Lock('YOUR_CLIENT_ID', 'YOUR_NAMESPACE', {
    container: 'root',
    auth: {
      redirectUrl: 'http://YOUR_APP/callback',
      responseType: 'code',
      params: {
        scope: 'openid email' // Learn about scopes: https://auth0.com/docs/scopes
      }
    }
  });
  lock.show();
</script>

<script src="https://cdn.auth0.com/js/lock-passwordless-2.2.min.js"></script>
<script>
  var lock = new Auth0LockPasswordless('YOUR_CLIENT_ID', 'YOUR_NAMESPACE');
  function open() {
    lock.sms({
      callbackURL: 'http://YOUR_APP/callback',
      authParams: {
        scope: 'openid email' // Learn about scopes: https://auth0.com/docs/scopes
      }
    });
  }
</script>
<button onclick="window.open();">SMS</button>

<script src="https://cdn.auth0.com/js/lock-passwordless-2.2.min.js"></script>
<script>
  var lock = new Auth0LockPasswordless('YOUR_CLIENT_ID', 'YOUR_NAMESPACE');
  function open() {
    lock.magiclink({
      callbackURL: 'http://YOUR_APP/callback',
      authParams: {
        scope: 'openid email' // Learn about scopes: https://auth0.com/docs/scopes
      }
    });
  }
</script>
<button onclick="window.open();">Magic Link</button>

<script src="https://cdn.auth0.com/js/lock-passwordless-2.2.min.js"></script>
<script>
  var lock = new Auth0LockPasswordless('YOUR_CLIENT_ID', 'YOUR_NAMESPACE');
  function open() {
    lock.emailcode({
      callbackURL: 'http://YOUR_APP/callback',
      authParams: {
        scope: 'openid email'  // Learn about scopes: https://auth0.com/docs/scopes
      }
    });
  }
</script>
<button onclick="window.open();">Email Code</button>

<button class="signin-google">Sign in with Google (redirect)</button><br>
<button class="signin-google-popup">Sign in with Google (popup)</button><br>
<br><p>--- or ---</p>
<label>Email</label><input type="text" id="email"><br>
<label>Password</label><input type="password" id="password"><br>
<button class="signin-db">Sign in with Email/Password</button>

<script src="https://cdn.auth0.com/w2/auth0-7.1.min.js"></script>
<script src="http://code.jquery.com/jquery.js"></script>
<script>
  var auth0 = new Auth0({
    domain:         'YOUR_NAMESPACE',
    clientID:       'YOUR_CLIENT_ID',
    callbackURL:    'http://YOUR_APP/callback'
  });
  // sign-in with social provider with plain redirect
  $('.signin-google').on('click', function() {
    auth0.signin({connection: 'google-oauth2'}); // use connection identifier
  });
  // sign-in with social provider using a popup (window.open)
  $('.signin-google-popup').on('click', function() {
    auth0.signin({popup: true, connection: 'google-oauth2'},
                function(err, profile, id_token, access_token, state) {
                    /*
                      store the profile and id_token in a cookie or local storage
                        $.cookie('profile', profile);
                        $.cookie('id_token', id_token);
                    */
                });
  });
  $('.signin-db').on('click', function() {
    auth0.signin({
      connection: 'foo',
      username: 'bar',
      password: 'foobar'
    },
    function (err, profile, id_token, access_token, state) {
      /*
          store the profile and id_token in a cookie or local storage
            $.cookie('profile', profile);
            $.cookie('id_token', id_token);
        */
    });
  });
</script>

https://YOUR_NAMESPACE/authorize?response_type=code
  &scope=openid%20profile
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=http://YOUR_APP/callback
  &connection=CONNECTION_NAME

Note: Please note that the redirectUrl specified in the Auth0Lock constructor must match the callback specified in the previous step

Also if you need to force an identity provider just redirect to Omniauth's path like this:

redirect_to '/auth/auth0?connection=CONNECTION_NAME'

6. Accessing user information

You can access the user information via the userinfo you stored in the session on step 3

class DashboardController < SecuredController
  def show
    @user = session[:userinfo]
  end
end

<div>
  <img class="avatar" src="<%= @user[:info][:image] %>"/>
  <h2>Welcome <%= @user[:info][:name] %></h2>
</div>

Click here to check all the information that the userinfo hash has.

7. You're done!

You have configured your Ruby on Rails Webapp to use Auth0. Congrats, you're awesome!

Optional steps

Checking if the user is authenticated

You can add the following parent controller to all pages that need the user to be authenticated:

class SecuredController < ApplicationController

  before_action :logged_in_using_omniauth?

  private

  def logged_in_using_omniauth?
    unless session[:userinfo].present?
      # Redirect to page that has the login here
      redirect_to '/'
    end
  end

end

Optional steps

Getting the error description on Failure

In case of failure, you may want to get the description of the error. For that, in your config/environments/production.rb add the following:

OmniAuth.config.on_failure = Proc.new { |env|
  message_key = env['omniauth.error.type']
  error_description = Rack::Utils.escape(env['omniauth.error'].error_reason)
  new_path = "#{env['SCRIPT_NAME']}#{OmniAuth.config.path_prefix}/failure?message=#{message_key}&error_description=#{error_description}"
  Rack::Response.new(['302 Moved'], 302, 'Location' => new_path).finish
}

Troubleshooting

Troubleshooting ActionDispatch::Cookies::CookieOverflow issue

If you are getting this error it means that you are using Cookie sessions and since you are storing the whole profile it overflows the max-size of 4K. Also, if you are unable to access the user profile and you get an error similar to NoMethodError, undefined method '[]' for nil:NilClass, please try this solution as well.

You can change to use In-Memory store for development as follows.

1. Go to /config/initializers/session_store.rb and add the following:

Rails.application.config.session_store :cache_store

2. Go to /config/enviroments/development.rb and add the following

config.cachestore = :memorystore

For production, we recommend using another memory store like MemCached or something similar

Troubleshooting SSL issues

It seems that under some configurations Ruby can't find certification authority certificates (CA Certs).

Download CURL's CA certs bundle to the project directory:

$ curl -o lib/ca-bundle.crt http://curl.haxx.se/ca/ca-bundle.crt

Then add this initializer config/initializers/fix_ssl.rb:

require 'open-uri'
require 'net/https'

module Net
  class HTTP
    alias_method :original_use_ssl=, :use_ssl=

    def use_ssl=(flag)
      path = ( Rails.env == "development") ? "lib/ca-bundle.crt" : "/usr/lib/ssl/certs/ca-certificates.crt"
      self.ca_file = Rails.root.join(path).to_s
      self.verify_mode = OpenSSL::SSL::VERIFY_PEER
      self.original_use_ssl = flag
    end
  end
end

Troubleshooting "failure message=invalid_credentials"

This issue isn't presented while working on your local (development). After deployment on your staging or production environment and after hitting your callback this issue may appear.

Example of an error message that may occur:

omniauth: (auth0) Authentication failure! invalid_credentials: OAuth2::Error, server_error: The redirect URI is wrong. You send [wrong url], and we expected [callback url set in your app settings]

To fix the above error, add the following at your config/environments/staging.rb or production.rb

OmniAuth.config.full_host = "http://www.example.com"

Substitute http://www.example.com with the actual URL you'll be using in your application.