Ruby On Rails API Authentication

Sample Project

Download a sample project specific to this tutorial configured with your Auth0 API Keys.

System Requirements
  • Ruby 2.1.8
  • Rails
Show requirements

To restrict access to the resources served by your API, a check needs to be made to determine whether the incoming request contains valid authorization information. There are various methods for including authorization information in a request, but for integration with Auth0, your API needs to check for a valid JSON Web Token (JWT). When users log into your application, they will receive an id_token and an access_token which are both JWTs. The specific JWT that needs to be sent to your API is the access_token.

This sample demonstrates how to check for a JWT in the Authorization header of an incoming HTTP request and verify that it is valid. The validity check is done using the jwt Gem within a custom JsonWebToken class. A Concern called Secured is used to mark endpoints which require authentication through an incoming access_token. If the token is valid, the resources which are served by the endpoint can be released, otherwise a 401 Authorization error will be returned.

Install the Dependencies

Install the jwt Gem.

gem `jwt`
bundle install

Create a JsonWebToken Class

By default, your API will be set up to use RS256 as the algorithm for signing tokens. Since RS256 works by using a private/public keypair, tokens can be verified against the public key for your Auth0 account. This public key is accessible at https://YOUR_AUTH0_DOMAIN/.well-known/jwks.json.

It is highly recommended that you use the default signing algorithm of RS256 for your API. If you do require HS256 as the algorithm, see the HS256 integration sample.

Create a class called JsonWebToken which decodes and verifies the incoming access_token taken from the Authorization header of the request. The public key for your Auth0 tenant can be fetched to verify the token.

# lib/tasks/json_web_token.rb

# frozen_string_literal: true
class JsonWebToken
  def self.verify(token)
    JWT.decode(token, nil,
               true, # Verify the signature of this token
               algorithm: 'RS256',
               iss: Rails.application.secrets.auth0_domain,
               verify_iss: true,
               aud: Rails.application.secrets.auth0_api_audience,
               verify_aud: true) do |header|

  def self.jwks_hash
    jwks_raw = Net::HTTP.get URI("#{Rails.application.secrets.auth0_domain}.well-known/jwks.json")
    jwks_keys = Array(JSON.parse(jwks_raw)['keys'])
      .map do |k|


Define a Secured Concern

Create a Concern called Secured which looks for the access_token in the Authorization header of an incoming request. If the token is present, it should be passed to JsonWebToken.verify.

# app/controllers/concerns/secured.rb

# frozen_string_literal: true
module Secured
  extend ActiveSupport::Concern

  included do
    before_action :authenticate_request!


  def authenticate_request!
  rescue JWT::VerificationError, JWT::DecodeError
    render json: { errors: ['Not Authenticated'] }, status: :unauthorized

  def http_token
    if request.headers['Authorization'].present?
      request.headers['Authorization'].split(' ').last

  def auth_token

Apply Authentication to Routes

With the Secured Concern in place, you can now apply it to whichever endpoints you wish to protect. Applying the Concern means that a valid access_token must be present in the request before the resource can be released.

# app/controllers/secured_ping_controller.rb

# frozen_string_literal: true
class SecuredPingController < ActionController::API
  include Secured

  def ping
    render json: "All good. You only get this message if you're authenticated."

Configure Scopes

The JsonWebToken.verify method above verifies that the access_token included in the request is valid; however, it doesn't yet include any mechanism for checking that the token has the sufficient scope to access the requested resources.

Scopes provide a way for you to define which resources should be accessible by the user holding a given access_token. For example, you might choose to permit read access to a messages resource if a user has a manager access level, or a write access to that resource if they are an administrator.

To configure scopes in your Auth0 dashboard, navigate to your API and choose the Scopes tab. In this area you can apply any scopes you wish, including one called read:messages, which will be used in this example.

Protect Individual Endpoints

To look for a particular scope in an access_token, provide an array of required scopes and check if they are present in the payload of the token.

In this example the SCOPES array for the given key /restricted_resource is intersected with the scopes coming in the payload, to determine if it contains one or more items from the other array.

# app/controllers/concerns/secured.rb

  SCOPES = {
    '/restricted_resource' => ['read:messages'],
    '/another_resource'    => ['some:scope', 'some:other_scope']


  def authenticate_request!
    @auth_payload, @auth_header = auth_token

    render json: { errors: ['Insufficient scope'] }, status: :unauthorized unless scope_included
  rescue JWT::VerificationError, JWT::DecodeError
    render json: { errors: ['Not Authenticated'] }, status: :unauthorized

  def scope_included
    # The intersection of the scopes included in the given JWT and the ones in the SCOPES hash needed to access
    # the PATH_INFO, should contain at least one element
    (String(@auth_payload['scope']).split(' ') & (SCOPES[request.env['PATH_INFO']])).any?

With this configuration in place, only access_tokens which have a scope of read:messages will be allowed to access this endpoint.

Previous Tutorial
1. Getting Started
Use Auth0 for FREECreate free Account