Auth0

This add-on is operated by AUTH0 INC

APIs and tools that enables Single Sign On and user management for all your apps

Auth0

Last Updated: 21 March 2014

Table of Contents

Auth0 is an add-on for providing single sign on and user management with social and enterprise identities.

  • Add SAML authentication without worrying about the integration with multiple providers (ADFS, SiteMinder, PingFederate, Okta, OneLogin, etc.), we take care of that.
  • Add social authentication with Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Salesforce, Box, 37Signals, FitBit.
  • Add your username/password databases or use Auth0 user database to completely outsource user management (coming soon!).
  • Get a normalized user profile regardless of the provider used.
  • Add support for linking user accounts.
  • Pull data from other sources and add it to the user profile, through JavaScript rules.

Auth0 is accessible via an API and has supported client libraries for Ruby and Node.js.

Provisioning the add-on

Auth0 can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

$ heroku addons:add auth0 --type=[nodejs|rails] --subdomain=myapp
-----> Adding Auth0 to sharp-mountain-4005... done, v18 (free)

Once Auth0 has been added you will have three settings on your app:

  • AUTH0_CLIENT_ID: the id that identifies your application.
  • AUTH0_CLIENT_SECRET: the secret for your application
  • AUTH0_DOMAIN: you will get your own subdomain on auth0
  • AUTH0_CALLBACK_URL: the url where auth0 will redirect the user after authentication
$ heroku config:get AUTH0_CLIENT_ID
9jf020kksfiuhifruiudtgudjsoeiuk

After installing Auth0 the application should be configured to fully integrate with the add-on.

Local setup

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable it’s also possible to set local environment variables using export AUTH0_CLIENT_ID=value.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the values retrieved from heroku config to .env.

$ heroku config -s | grep 'AUTH0_CLIENT_ID\|AUTH0_CLIENT_SECRET\|AUTH0_DOMAIN' | tee -a .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

If you are trying from localhost you might want to change or add localhost as the callback url

Using with Rails

Ruby on Rails applications will need to add the following entry into their Gemfile specifying the Auth0 client library.

gem 'auth0'

Update application dependencies with bundler.

$ bundle install

Append a callback url for development to .env:

$ echo "\nAUTH0_CALLBACK_URL=http://localhost:5000/callback" >> .env

We set a callback URL in your production environment by using the domains of your app in heroku, you will have to check if it is the correct domain and change it later eg: heroku config:set AUTH0_CALLBACK_URL=http://fo.com/callback

Initialize Auth0’s omniauth strategy creating a new auth0.rb file under the config/initializers directory as follows:

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :auth0, ENV['AUTH0_CLIENT_ID'], ENV['AUTH0_CLIENT_SECRET'], ENV['AUTH0_DOMAIN'], :callback_path => "/callback"
end

Create a callback controller:

$ rails generate controller callback store failure

Open the callback_controller.rb and paste the following code:

class CallbackController < ApplicationController
  def store
    #use this session to show user info in other pages
    session[:userinfo] = request.env['omniauth.auth']
    redirect_to "/"
  end

  def failure
    @error_msg = request.params['message']
  end
end

Add the following routes in routes.rb:

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

Trigger the login widget in your main page as follows:

<script src="https://d19p4zemcycm7a.cloudfront.net/w2/auth0-widget-2.4.6.min.js"></script>
<script type="text/javascript">

  var widget = new Auth0Widget({
    domain:         '<%= ENV["AUTH0_DOMAIN"] %>',
    clientID:       '<%= ENV["AUTH0_CLIENT_ID"] %>',
    callbackURL:    '<%= ENV["AUTH0_CALLBACK_URL"] %>'
  });

</script>
<button onclick="widget.signin()">Login</button>

This is how the widget looks by default without any customization when habing Facebook, Salesforce, Microsoft Account and a database connection enabled.

ss-2013-09-04T08-25-34.png

Alternatively you can customize the widget with css or trigger the authentication with one specific provider directly with a simple redirect. For more details, checkout our Ruby on Rails tutorial.

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

Using with Node

Append the localhost callback to your .env file:

$ echo "\nAUTH0_CALLBACK_URL=http://localhost:5000/callback" >> .env

We set a callback URL in your production environment by using the domains of your app in heroku, you will have to check if it is the correct domain and change it later eg: heroku config:set AUTH0_CALLBACK_URL=http://fo.com/callback

Install the Passport and Passport-Auth0 modules as follows:

$ npm install passport passport-auth0 --save

then create a new file called setup_passport.js:

var passport = require('passport');
var Auth0Strategy = require('passport-auth0');

var strategy = new Auth0Strategy({
    domain: process.env['AUTH0_DOMAIN'],
    clientID: process.env['AUTH0_CLIENT_ID'],
    clientSecret: process.env['AUTH0_CLIENT_SECRET'],
    callbackURL: process.env['AUTH0_CALLBACK_URL']
  }, function(accessToken, refreshToken, profile, done) {
    //Some tracing info
    console.log('profile is', profile);
    //save the profile
    return done(null, profile);
  });

passport.use(strategy);

// you can use this section to keep a smaller payload
passport.serializeUser(function(user, done) {
  done(null, user);
});

passport.deserializeUser(function(user, done) {
  done(null, user);
});

module.exports = strategy;

Configure Express to use Passport:

app.configure (function () {
  this.use(express.cookieParser());
  this.use(express.session({secret: 'foo'}));

  //..
  this.use(passport.initialize());
  this.use(passport.session());
  //..

  this.use(app.router);
});

// Auth0 callback handler
app.get('/callback',
  passport.authenticate('auth0'),
  function(req, res) {
    res.redirect("/");
  });

app.get('/', function (req, res) {
  res.render('home', {
    user: req.user, //use this to display user information
    env: process.env
  })
});

Trigger the login widget in your main page as follows:

<script src="https://d19p4zemcycm7a.cloudfront.net/w2/auth0-widget-2.4.6.min.js"></script>
<script type="text/javascript">

  var widget = new Auth0Widget({
    domain:         '<%= env["AUTH0_DOMAIN"] %>',
    clientID:       '<%= env["AUTH0_CLIENT_ID"] %>',
    callbackURL:    '<%= env["AUTH0_CALLBACK_URL"] %>'
  });

</script>
<button onclick="widget.signin()">Login</button>

This is how the widget looks by default without any customization when habing Facebook, Salesforce, Microsoft Account and a database connection enabled.

ss-2013-09-04T08-25-34.png

Alternatively you can customize the widget with css or trigger the authentication with one specific provider directly with a simple redirect. For more details, checkout our node.js tutorial.

Dashboard

The Auth0 dashboard allows you to configure the social, enterprise or database providers you want to enable for your application, looking at who is logging in and when, configure single sign on with other applications, create new rules for authorization or whitelist and more.

ss-2013-09-04T07-50-12.png

The dashboard can be accessed via the CLI:

$ heroku addons:open auth0
Opening Auth0 for sharp-mountain-4005…

or by visiting the Heroku apps web interface and selecting the application in question. Select Auth0 from the Add-ons menu.

Migrating between plans

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade auth0:pro3
-----> Upgrading auth0:pro3 to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: auth0:pro3

Removing the add-on

Auth0 can be removed via the CLI.

This will destroy all associated data and cannot be undone.

$ heroku addons:remove auth0
-----> Removing auth0 from sharp-mountain-4005... done, v20 (free)

Before removing Auth0 a data export can be performed using the API.

Support

All Auth0 support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome via the small question icon on the dashboard or via our chat chat.auth0.com.