Sign up for an{" "}
Auth0 account
{" "}
or{" "}
console.log("log in")}>
log in
{" "}
to your existing account to integrate directly with your own tenant.
;
};
export const sections = [{
id: "configure-auth0",
title: "Configure Auth0"
}, {
id: "add-dependencies",
title: "Add dependencies"
}, {
id: "configure-the-sdk",
title: "Configure the SDK"
}, {
id: "configure-the-omniauth-middleware",
title: "Configure the OmniAuth middleware"
}, {
id: "add-an-auth0-controller",
title: "Add an Auth0 controller"
}, {
id: "configure-routes",
title: "Configure routes"
}, {
id: "add-login-to-your-application",
title: "Add login to your application"
}, {
id: "add-logout-to-your-application",
title: "Add logout to your application"
}, {
id: "show-user-profile-information",
title: "Show user profile information"
}];
To use Auth0 services, you’ll need to have an application set up in the Auth0 Dashboard. The Auth0 application is
where you will configure how you want authentication to work for the project you are developing.
### Configure an application
Use the interactive selector to create a new Auth0 application or select an existing application that represents
the project you want to integrate with. Every application in Auth0 is assigned an alphanumeric, unique client ID
that your application code will use to call Auth0 APIs through the SDK.
Any settings you configure using this quickstart will automatically update for your Application in the [Dashboard](https://manage.auth0.com/#/), which is where you
can manage your Applications in the future.
If you would rather explore a complete configuration, you can view a sample application instead.
### Configure Callback URLs
A callback URL is a URL in your application that you would like Auth0 to redirect users to after they have
authenticated. If not set, users will not be returned to your application after they log in.
If you are following along with our sample project, set this to
`http://localhost:3000/auth/auth0/callback`.
### Configure Logout URLs
A logout URL is a URL in your application that you would like Auth0 to redirect users to after they have logged
out. If not set, users will not be able to log out from your application and will receive an error.
If you are following along with our sample project, set this to `http://localhost:3000`.
### Configure Allowed Web Origins
An Allowed Web Origin is a URL that you want to be allowed to access to your authentication flow. This must
contain the URL of your project. If not properly set, your project will be unable to silently refresh
authentication tokens, so your users will be logged out the next time they visit your application or refresh a
page.
If you are following along with our sample project, set this to `http://localhost:3000`.
Use `omniauth-auth0`, a custom [OmniAuth strategy](https://github.com/intridea/omniauth#omniauth-standardized-multi-provider-authentication), to handle the authentication flow.
Add the following dependencies to your `Gemfile`:
```gem lines theme={null}
gem 'omniauth-auth0', '~> 3.0'
gem 'omniauth-rails_csrf_protection', '~> 1.0' # prevents forged authentication requests
```
Once your gems are added, install the gems with `bundle install`.
Create a configuration file `./config/auth0.yml` to specify your Auth0 domain, client ID, and client
secret values located in your Auth0 Dashboard under application **Settings**.
Create the following initializer file `./config/initializers/auth0.rb` and [configure](https://github.com/auth0/omniauth-auth0/blob/master/EXAMPLES.md#send-additional-authentication-parameters) the **OmniAuth** middleware with the configuration
file you created in the previous step.
Ensure that `callback_path` matches the value given in the "Allowed Callback URLs" setting in your
Auth0 application.
Create an Auth0 controller to handle the authentication callback, `logout` action, and methods for
constructing the logout URL.
Run the command:
`rails generate controller auth0 callback failure logout --skip-assets --skip-helper --skip-routes --skip-template-engine`.
Inside the callback method, assign the hash of user information - returned as
`request.env['omniauth.auth']` - to the active session.
To configure logout, clear all the objects stored within the session by calling the `reset_session`
method within the `logout` action. Then, redirect to the Auth0 logout endpoint. To learn more about
`reset_session`, read [Ruby on Rails ActionController documentation](http://api.rubyonrails.org/classes/ActionController/Base.html#M000668).
Add these routes to your `./config/routes.rb` file.
Routes must be in place so Rails knows how to route the various Auth0 callback URLs to the Auth0 controller you
created in the previous step.
##### Checkpoint
Run your application to verify it continues to work as intended and you aren't receive any errors
relating to Auth0.
A user can now log into your application by visiting the `/auth/auth0` endpoint.
To [prevent forged authentication requests](https://github.com/cookpad/omniauth-rails_csrf_protection), use the `link_to` or
`button_to` helper methods with the `:post` method.
```ruby lines theme={null}
<%= button_to 'Login', '/auth/auth0', method: :post %>
```
##### Checkpoint
Add a button to your application that redirects the user to the `/auth/auth0` endpoint when
selected. Observe that you redirect to Auth0 to log in, and then back to your app after successful
authentication.
Now that you can log in to your Rails application, you need a
way to log out. Log out a user by redirecting to the `auth/logout` action, which redirects them
to the Auth0 logout endpoint.
To test this after the previous step, you may need to clear out your session and then redirect the user
to the Auth0 logout endpoint.
```ruby lines theme={null}
<%= button_to 'Logout', 'auth/logout', method: :get %>
```
##### Checkpoint
Add a button to your application that redirects the user to the `/auth/logout` endpoint when
selected. Verify that you redirect to Auth0 and then quickly back to your application, and that you are no
longer logged in.
To display the user's profile, your application should provide a protected route. You can use a [Concern](https://guides.rubyonrails.org/getting_started.html#using-concerns) to control access to routes that can be shared across multiple
controllers. The concern should automatically redirect to Auth0 when the user is unauthenticated. Otherwise, the
concern should return the current user profile.
Once you have a Concern, include it in any controller that requires a logged-in user. You can then access the
user from the session `session[:userinfo]` as in the following example:
```ruby lines theme={null}
class DashboardController < ApplicationController
include Secured
def show
@user = session[:userinfo]
end
end
```
Once the user loads from the session, use it to display information in your frontend:
```html lines theme={null}
Normalized User Profile:<%= JSON.pretty_generate(@user[:info])%>
Full User Profile:<%= JSON.pretty_generate(@user[:extra][:raw_info])%>
```
##### Checkpoint
Add the `Secured` concern to your app and then include it in the controller that requires an
authenticated user to access it. Verify that an authenticated user has access to actions within that
controller and that unauthenticated users are redirected to Auth0 for authentication.
## Next Steps
Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.
This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:
* [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
* [omniauth-auth0 SDK](https://github.com/auth0/omniauth-auth0) - Explore the SDK used in this tutorial more fully
* [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
```yml config/auth0.yml lines theme={null}
development:
auth0_domain: {yourDomain}
auth0_client_id: {yourClientId}
auth0_client_secret: {yourClientSecret}
```
```ruby auth0.rb lines theme={null}
AUTH0_CONFIG = Rails.application.config_for(:auth0)
Rails.application.config.middleware.use OmniAuth::Builder do
provider(
:auth0,
AUTH0_CONFIG['auth0_client_id'],
AUTH0_CONFIG['auth0_client_secret'],
AUTH0_CONFIG['auth0_domain'],
callback_path: '/auth/auth0/callback',
authorize_params: {
scope: 'openid profile'
}
)
end
```
```ruby auth0_controller.rb lines theme={null}
class Auth0Controller < ApplicationController
def callback
# OmniAuth stores the informatin returned from
# Auth0 and the IdP in request.env['omniauth.auth'].
# In this code, you will pull the raw_info supplied
# from the id_token and assign it to the session.
# Refer to https://github.com/auth0/omniauth-auth0/blob/master/EXAMPLES.md#example-of-the-resulting-authentication-hash
# for complete information on 'omniauth.auth' contents.
auth_info = request.env['omniauth.auth']
session[:userinfo] = auth_info['extra']['raw_info']
# Redirect to the URL you want after successful auth
redirect_to '/dashboard'
end
def failure
# Handles failed authentication
@error_msg = request.params['message']
end
def logout
reset_session
redirect_to logout_url
end
private
AUTH0_CONFIG = Rails.application.config_for(:auth0)
def logout_url
request_params = {
returnTo: root_url,
client_id: AUTH0_CONFIG['auth0_client_id']
}
URI::HTTPS.build(host: AUTH0_CONFIG['auth0_domain'], path: '/v2/logout', query: to_query(request_params)).to_s
end
def to_query(hash)
hash.map { |k, v| "#{k}=#{CGI.escape(v)}" unless v.nil? }.reject(&:nil?).join('&')
end
end
```
```ruby routes.rb lines theme={null}
Rails.application.routes.draw do
# . .
get '/auth/auth0/callback' => 'auth0#callback'
get '/auth/failure' => 'auth0#failure'
get '/auth/logout' => 'auth0#logout'
end
```
```ruby secured.rb lines theme={null}
module Secured
extend ActiveSupport::Concern
included do
before_action :logged_in_using_omniauth?
end
def logged_in_using_omniauth?
redirect_to '/' unless session[:userinfo].present?
end
end
```
```ruby auth0.rb lines theme={null}
AUTH0_CONFIG = Rails.application.config_for(:auth0)
Rails.application.config.middleware.use OmniAuth::Builder do
provider(
:auth0,
AUTH0_CONFIG['auth0_client_id'],
AUTH0_CONFIG['auth0_client_secret'],
AUTH0_CONFIG['auth0_domain'],
callback_path: '/auth/auth0/callback',
authorize_params: {
scope: 'openid profile'
}
)
end
```
```yml config/auth0.yml lines theme={null}
development:
auth0_domain: {yourDomain}
auth0_client_id: {yourClientId}
auth0_client_secret: {yourClientSecret}
```
```ruby auth0_controller.rb lines theme={null}
class Auth0Controller < ApplicationController
def callback
# OmniAuth stores the informatin returned from
# Auth0 and the IdP in request.env['omniauth.auth'].
# In this code, you will pull the raw_info supplied
# from the id_token and assign it to the session.
# Refer to https://github.com/auth0/omniauth-auth0/blob/master/EXAMPLES.md#example-of-the-resulting-authentication-hash
# for complete information on 'omniauth.auth' contents.
auth_info = request.env['omniauth.auth']
session[:userinfo] = auth_info['extra']['raw_info']
# Redirect to the URL you want after successful auth
redirect_to '/dashboard'
end
def failure
# Handles failed authentication
@error_msg = request.params['message']
end
def logout
reset_session
redirect_to logout_url
end
private
AUTH0_CONFIG = Rails.application.config_for(:auth0)
def logout_url
request_params = {
returnTo: root_url,
client_id: AUTH0_CONFIG['auth0_client_id']
}
URI::HTTPS.build(host: AUTH0_CONFIG['auth0_domain'], path: '/v2/logout', query: to_query(request_params)).to_s
end
def to_query(hash)
hash.map { |k, v| "#{k}=#{CGI.escape(v)}" unless v.nil? }.reject(&:nil?).join('&')
end
end
```
```ruby routes.rb lines theme={null}
Rails.application.routes.draw do
# . .
get '/auth/auth0/callback' => 'auth0#callback'
get '/auth/failure' => 'auth0#failure'
get '/auth/logout' => 'auth0#logout'
end
```
```ruby secured.rb lines theme={null}
module Secured
extend ActiveSupport::Concern
included do
before_action :logged_in_using_omniauth?
end
def logged_in_using_omniauth?
redirect_to '/' unless session[:userinfo].present?
end
end
```
```ruby auth0_controller.rb lines theme={null}
class Auth0Controller < ApplicationController
def callback
# OmniAuth stores the informatin returned from
# Auth0 and the IdP in request.env['omniauth.auth'].
# In this code, you will pull the raw_info supplied
# from the id_token and assign it to the session.
# Refer to https://github.com/auth0/omniauth-auth0/blob/master/EXAMPLES.md#example-of-the-resulting-authentication-hash
# for complete information on 'omniauth.auth' contents.
auth_info = request.env['omniauth.auth']
session[:userinfo] = auth_info['extra']['raw_info']
# Redirect to the URL you want after successful auth
redirect_to '/dashboard'
end
def failure
# Handles failed authentication
@error_msg = request.params['message']
end
def logout
reset_session
redirect_to logout_url
end
private
AUTH0_CONFIG = Rails.application.config_for(:auth0)
def logout_url
request_params = {
returnTo: root_url,
client_id: AUTH0_CONFIG['auth0_client_id']
}
URI::HTTPS.build(host: AUTH0_CONFIG['auth0_domain'], path: '/v2/logout', query: to_query(request_params)).to_s
end
def to_query(hash)
hash.map { |k, v| "#{k}=#{CGI.escape(v)}" unless v.nil? }.reject(&:nil?).join('&')
end
end
```
```yml config/auth0.yml lines theme={null}
development:
auth0_domain: {yourDomain}
auth0_client_id: {yourClientId}
auth0_client_secret: {yourClientSecret}
```
```ruby auth0.rb lines theme={null}
AUTH0_CONFIG = Rails.application.config_for(:auth0)
Rails.application.config.middleware.use OmniAuth::Builder do
provider(
:auth0,
AUTH0_CONFIG['auth0_client_id'],
AUTH0_CONFIG['auth0_client_secret'],
AUTH0_CONFIG['auth0_domain'],
callback_path: '/auth/auth0/callback',
authorize_params: {
scope: 'openid profile'
}
)
end
```
```ruby routes.rb lines theme={null}
Rails.application.routes.draw do
# . .
get '/auth/auth0/callback' => 'auth0#callback'
get '/auth/failure' => 'auth0#failure'
get '/auth/logout' => 'auth0#logout'
end
```
```ruby secured.rb lines theme={null}
module Secured
extend ActiveSupport::Concern
included do
before_action :logged_in_using_omniauth?
end
def logged_in_using_omniauth?
redirect_to '/' unless session[:userinfo].present?
end
end
```
```ruby routes.rb lines theme={null}
Rails.application.routes.draw do
# . .
get '/auth/auth0/callback' => 'auth0#callback'
get '/auth/failure' => 'auth0#failure'
get '/auth/logout' => 'auth0#logout'
end
```
```yml config/auth0.yml lines theme={null}
development:
auth0_domain: {yourDomain}
auth0_client_id: {yourClientId}
auth0_client_secret: {yourClientSecret}
```
```ruby auth0.rb lines theme={null}
AUTH0_CONFIG = Rails.application.config_for(:auth0)
Rails.application.config.middleware.use OmniAuth::Builder do
provider(
:auth0,
AUTH0_CONFIG['auth0_client_id'],
AUTH0_CONFIG['auth0_client_secret'],
AUTH0_CONFIG['auth0_domain'],
callback_path: '/auth/auth0/callback',
authorize_params: {
scope: 'openid profile'
}
)
end
```
```ruby auth0_controller.rb lines theme={null}
class Auth0Controller < ApplicationController
def callback
# OmniAuth stores the informatin returned from
# Auth0 and the IdP in request.env['omniauth.auth'].
# In this code, you will pull the raw_info supplied
# from the id_token and assign it to the session.
# Refer to https://github.com/auth0/omniauth-auth0/blob/master/EXAMPLES.md#example-of-the-resulting-authentication-hash
# for complete information on 'omniauth.auth' contents.
auth_info = request.env['omniauth.auth']
session[:userinfo] = auth_info['extra']['raw_info']
# Redirect to the URL you want after successful auth
redirect_to '/dashboard'
end
def failure
# Handles failed authentication
@error_msg = request.params['message']
end
def logout
reset_session
redirect_to logout_url
end
private
AUTH0_CONFIG = Rails.application.config_for(:auth0)
def logout_url
request_params = {
returnTo: root_url,
client_id: AUTH0_CONFIG['auth0_client_id']
}
URI::HTTPS.build(host: AUTH0_CONFIG['auth0_domain'], path: '/v2/logout', query: to_query(request_params)).to_s
end
def to_query(hash)
hash.map { |k, v| "#{k}=#{CGI.escape(v)}" unless v.nil? }.reject(&:nil?).join('&')
end
end
```
```ruby secured.rb lines theme={null}
module Secured
extend ActiveSupport::Concern
included do
before_action :logged_in_using_omniauth?
end
def logged_in_using_omniauth?
redirect_to '/' unless session[:userinfo].present?
end
end
```
```ruby secured.rb lines theme={null}
module Secured
extend ActiveSupport::Concern
included do
before_action :logged_in_using_omniauth?
end
def logged_in_using_omniauth?
redirect_to '/' unless session[:userinfo].present?
end
end
```
```yml config/auth0.yml lines theme={null}
development:
auth0_domain: {yourDomain}
auth0_client_id: {yourClientId}
auth0_client_secret: {yourClientSecret}
```
```ruby auth0.rb lines theme={null}
AUTH0_CONFIG = Rails.application.config_for(:auth0)
Rails.application.config.middleware.use OmniAuth::Builder do
provider(
:auth0,
AUTH0_CONFIG['auth0_client_id'],
AUTH0_CONFIG['auth0_client_secret'],
AUTH0_CONFIG['auth0_domain'],
callback_path: '/auth/auth0/callback',
authorize_params: {
scope: 'openid profile'
}
)
end
```
```ruby auth0_controller.rb lines theme={null}
class Auth0Controller < ApplicationController
def callback
# OmniAuth stores the informatin returned from
# Auth0 and the IdP in request.env['omniauth.auth'].
# In this code, you will pull the raw_info supplied
# from the id_token and assign it to the session.
# Refer to https://github.com/auth0/omniauth-auth0/blob/master/EXAMPLES.md#example-of-the-resulting-authentication-hash
# for complete information on 'omniauth.auth' contents.
auth_info = request.env['omniauth.auth']
session[:userinfo] = auth_info['extra']['raw_info']
# Redirect to the URL you want after successful auth
redirect_to '/dashboard'
end
def failure
# Handles failed authentication
@error_msg = request.params['message']
end
def logout
reset_session
redirect_to logout_url
end
private
AUTH0_CONFIG = Rails.application.config_for(:auth0)
def logout_url
request_params = {
returnTo: root_url,
client_id: AUTH0_CONFIG['auth0_client_id']
}
URI::HTTPS.build(host: AUTH0_CONFIG['auth0_domain'], path: '/v2/logout', query: to_query(request_params)).to_s
end
def to_query(hash)
hash.map { |k, v| "#{k}=#{CGI.escape(v)}" unless v.nil? }.reject(&:nil?).join('&')
end
end
```
```ruby routes.rb lines theme={null}
Rails.application.routes.draw do
# . .
get '/auth/auth0/callback' => 'auth0#callback'
get '/auth/failure' => 'auth0#failure'
get '/auth/logout' => 'auth0#logout'
end
```
Sign up for an{" "}
Auth0 account
{" "}
or{" "}
console.log("log in")}>
log in
{" "}
to your existing account to integrate directly with your own tenant.