Ruby On Rails API: Authorization
This tutorial demonstrates how to add authorization to a Ruby on Rails API. We recommend that you log in to follow this quickstart with examples configured for your account.
I want to integrate with my app
15 minutesI want to explore a sample app
2 minutesGet a sample configured with your account settings or check it out on Github.
Configure Auth0 APIs
Create an API
In the APIs section of the Auth0 dashboard, click Create API. Provide a name and an identifier for your API, for example, https://quickstarts/api
. You will use the identifier as an audience
later, when you are configuring the Access Token verification. Leave the Signing Algorithm as RS256.
By default, your API uses RS256 as the algorithm for signing tokens. Since RS256 uses a private/public keypair, it verifies the tokens against the public key for your Auth0 account. The public key is in the JSON Web Key Set (JWKS) format, and can be accessed here.
Define permissions
Permissions let you define how resources can be accessed on behalf of the user with a given access token. For example, you might choose to grant read access to the messages
resource if users have the manager access level, and a write access to that resource if they have the administrator access level.
You can define allowed permissions in the Permissions view of the Auth0 Dashboard's APIs section.
This example demonstrates:
-
How to check for a JSON Web Token (JWT) in the
Authorization
header of an incoming HTTP request. -
How to check if the token is valid, using the JSON Web Key Set (JWKS) for your Auth0 account. To learn more about validating Access Tokens, see Validate Access Tokens.
Validate Access Tokens
Install dependencies
This tutorial performs access token validation using the jwt Gem within a custom Auth0Client
class. A Concern called Secured
is used to authorize endpoints which require authentication through an incoming access token.
Install the jwt Gem.
gem 'jwt'
bundle install
Was this helpful?
Create an Auth0Client class
Create a class called Auth0Client
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.
# app/lib/auth0_client.rb
# frozen_string_literal: true
require 'jwt'
require 'net/http'
class Auth0Client
# Auth0 Client Objects
Error = Struct.new(:message, :status)
Response = Struct.new(:decoded_token, :error)
# Helper Functions
def self.domain_url
"https://#{Rails.configuration.auth0.domain}/"
end
def self.decode_token(token, jwks_hash)
JWT.decode(token, nil, true, {
algorithm: 'RS256',
iss: domain_url,
verify_iss: true,
aud: Rails.configuration.auth0.audience,
verify_aud: true,
jwks: { keys: jwks_hash[:keys] }
})
end
def self.get_jwks
jwks_uri = URI("#{domain_url}.well-known/jwks.json")
Net::HTTP.get_response jwks_uri
end
# Token Validation
def self.validate_token(token)
jwks_response = get_jwks
unless jwks_response.is_a? Net::HTTPSuccess
error = Error.new(message: 'Unable to verify credentials', status: :internal_server_error)
return Response.new(nil, error)
end
jwks_hash = JSON.parse(jwks_response.body).deep_symbolize_keys
decoded_token = decode_token(token, jwks_hash)
Response.new(decoded_token, nil)
rescue JWT::VerificationError, JWT::DecodeError => e
error = Error.new('Bad credentials', :unauthorized)
Response.new(nil, error)
end
end
Was this helpful?
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 Auth0Client.validate_token
.
# app/controllers/concerns/secured.rb
# frozen_string_literal: true
module Secured
extend ActiveSupport::Concern
REQUIRES_AUTHENTICATION = { message: 'Requires authentication' }.freeze
BAD_CREDENTIALS = {
message: 'Bad credentials'
}.freeze
MALFORMED_AUTHORIZATION_HEADER = {
error: 'invalid_request',
error_description: 'Authorization header value must follow this format: Bearer access-token',
message: 'Bad credentials'
}.freeze
def authorize
token = token_from_request
return if performed?
validation_response = Auth0Client.validate_token(token)
return unless (error = validation_response.error)
render json: { message: error.message }, status: error.status
end
private
def token_from_request
authorization_header_elements = request.headers['Authorization']&.split
render json: REQUIRES_AUTHENTICATION, status: :unauthorized and return unless authorization_header_elements
unless authorization_header_elements.length == 2
render json: MALFORMED_AUTHORIZATION_HEADER, status: :unauthorized and return
end
scheme, token = authorization_header_elements
render json: BAD_CREDENTIALS, status: :unauthorized and return unless scheme.downcase == 'bearer'
token
end
end
Was this helpful?
Validate scopes
The Auth0Client.validate_token
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.
To look for a particular scope
in an access token, create a new struct in your Auth0Client
class called Token
and define a new method inside, validate_permissions
, that given an array of required scopes it will check if they are present in the payload of the token.
Go to the Auth0Client
class. Add the new Token
struct and update the return value of the validate_token
method as follows:
# app/lib/auth0_client.rb
# frozen_string_literal: true
require 'jwt'
require 'net/http'
class Auth0Client
# Auth0 Client Objects
Error = Struct.new(:message, :status)
Response = Struct.new(:decoded_token, :error)
Token = Struct.new(:token) do
def validate_permissions(permissions)
required_permissions = Set.new permissions
scopes = token[0]['scope']
token_permissions = scopes.present? ? Set.new(scopes.split(" ")) : Set.new
required_permissions <= token_permissions
end
end
# ...
# Token Validation
def self.validate_token(token)
jwks_response = get_jwks
unless jwks_response.is_a? Net::HTTPSuccess
error = Error.new(message: 'Unable to verify credentials', status: :internal_server_error)
return Response.new(nil, error)
end
jwks_hash = JSON.parse(jwks_response.body).deep_symbolize_keys
decoded_token = decode_token(token, jwks_hash)
Response.new(Token.new(decoded_token), nil)
rescue JWT::VerificationError, JWT::DecodeError => e
error = Error.new('Bad credentials', :unauthorized)
Response.new(nil, error)
end
end
Was this helpful?
Next, in the Secured
concern, define a new error constant INSUFFICIENT_PERMISSIONS
to return a proper error message in case there was a attempt to request a resource without the right permissions. Next, update the return value of the Auth0Client.validate_token
call and finally create a new method validate_permissions
where to check if the token has the right permissions, or return a 403 FORBIDDEN
status code with the INSUFFICIENT_PERMISSIONS
error message otherwise.
Apply these changes in your Secured
concern by adding the following code:
# app/controllers/concerns/secured.rb
# frozen_string_literal: true
module Secured
extend ActiveSupport::Concern
# ...
INSUFFICIENT_PERMISSIONS = {
error: 'insufficient_permissions',
error_description: 'The access token does not contain the required permissions',
message: 'Permission denied'
}.freeze
def authorize
token = token_from_request
return if performed?
validation_response = Auth0Client.validate_token(token)
@decoded_token = validation_response.decoded_token # Add this line
return unless (error = validation_response.error)
render json: { message: error.message }, status: error.status
end
def validate_permissions(permissions)
raise 'validate_permissions needs to be called with a block' unless block_given?
return yield if @decoded_token.validate_permissions(permissions)
render json: INSUFFICIENT_PERMISSIONS, status: :forbidden
end
private
# ...
end
Was this helpful?
Protect API Endpoints
The routes shown below are available for the following requests:
GET /api/public
: available for non-authenticated requestsGET /api/private
: available for authenticated requests containing an access token with no additional scopesGET /api/private-scoped
: available for authenticated requests containing an access token with theread:messages
scope granted
Add the Secured
concern to the ApplicationController
:
class ApplicationController < ActionController::API
include Secured
end
Was this helpful?
You only ned to protect the PrivateController
as follows:
class PrivateController < ApplicationController
before_action :authorize
# ...
end
Was this helpful?
In order to check that your access token has the right permissions, call the validate_permissions
method as follows in the private-scoped
action:
class PrivateController < ApplicationController
before_action :authorize
def private
render json: { message: 'Hello from a private endpoint! You need to be authenticated to see this.' }
end
def private_scoped
validate_permissions ['read:messages'] do
render json: { message: 'Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this.' }
end
end
end
Was this helpful?