carla_urrea

I've been working as a software engineer since 2014, particularly as a backend engineer and doing system design. I consider myself a language-agnostic developer but if I had to choose, I like to work with Ruby and Python.  

After realizing how fun it was to create content and share experiences with the developer community I made the switch to Developer Advocacy. I like to learn and work with new technologies. 

When I'm not coding or creating content you could probably find me going on a bike ride, hiking, or just hanging out with my dog, Dasha. 

Staff Developer Advocate

Carla Urrea Stabile

The way to implement an authorization system depends on your application's needs. Let's explore Relationship-Based Access Control (ReBAC) and implement it in a Rails API using OpenFGA.

How to Implement Relationship-Based Access Control (ReBAC) in a Ruby On Rails API?

There are different ways to implement an authorization system and the one you choose depends on your application's needs. Attribute-Based Access Control (ABAC) is just one of them, so let's go ahead and learn how to implement it in a Rails API.

Previously on your access control series \*read with TV show presenter's voice\*... You learned about [Role-Based Access Control (RBAC) and how to integrate it into your Rails API](https://auth0.com/blog/what-is-rbac-and-how-to-implement-it-rails-api/).
In this blog post, you’ll continue learning about different authorization systems, this time about Attribute-Based Access Control and how to migrate the access control of the expense management API from RBAC to ABAC. 

<details>
<summary>Starting from here?</summary>

If you want to start this tutorial from the beginning, [start from this blog post.](https://auth0.com/blog/what-is-rbac-and-how-to-implement-it-rails-api/)

Clone the application repo and check out the `add-rbac` branch:

``` bash  
git clone -b add-rbac https://github.com/auth0-blog/rails-api-authorization 
```

Make the project folder your current directory:

``` bash  
cd rails-api-authorization
```

Then, install the project dependencies:

``` bash  
bundle install
```

Then, setup the database

``` bash
  rails db:setup
```

Finally, create a `.env` hidden file:

``` bash  
touch .env
```

Populate `.env` using the `.env.example` file:

``` bash  
cp .env.example .env
```

Add your Auth0 configuration variables to the .env file and run the project by executing the following command:

``` bash  
rails s
```

</details>

## What Are Attributes in the Context of Access Control?

Let's consider the use case of the expense management API you are using in this tutorial. For RBAC, you created an `admin` role and assigned it to users using Auth0 Actions. Users with the `admin` role can approve and review expenses, and so far, that's so good. 

The following requirement you have is that only certain users can do certain things on specific expense reports: 

- Users can only see a report they own (submitted by them)
- Users can only see a report if they are the approver
- Users who are approvers can only *approve* reports on weekdays (we don't want people working on weekends!)

With the current RBAC implementation, a user with the `admin` role can do all of these things, but unfortunately, not all admin users need to approve reports. So, as a solution, you think adding these guards to your code sounds good, so **you are going to check the attributes of the report** (the user is either the approver or submitter of this report), the date the report is being approved, etc. 

This practice has a name, and it's called Attribute-Based Access Control.

## What Is Attribute-Based Access Control (ABAC)?

[According to NIST, Attribute-Based Access Control (ABAC)](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-162.pdf) is an access control method where a subject's requests to perform operations on objects are granted or denied **based on assigned attributes of the subject, assigned attributes of the object**, environment conditions, and a set of policies that are specified in terms of those attributes and conditions.

In other words, any access decision that your application makes based on attributes of an entity can be considered ABAC and it'll be specific to your application and access control needs. 

ABAC also gives you more control and granularity over your access decisions, making it more flexible than RBAC. 

Regarding the expense management API, RBAC and ABAC can coexist; in fact, checking for a role or permission is also checking for attributes, in this case, attributes assigned to the user, so we can say RBAC is an implementation of ABAC with a limited scope of roles and permissions. So now, let's say it is a requirement that the user also needs to be an admin to perform the approver actions. Why not? 😛 

Let's look at what you'll need to change in your Ruby on Rails API to comply with the new access control requirements and implement ABAC. 

## ABAC Implementation in a Ruby on Rails API

Let's take a look at the requirements you need to implement: 

- Users can only see a report they own (submitted by them)
- Only approvers can see reports submitted by other users
- Only admin users can approve reports
- Users who are approvers can only *approve* reports on weekdays (we don't want people working on weekends!)

Based on this, there are a few changes you could make to the application; most of them are related to the `report` entity. 

Let's think of the scenario where a **user can only see a report they have submitted, or they are the approver**; you could think of this as multiple things like the user needs to have some relationship with the expense report, meaning they are either the submitter or the approver.

There's little we can do with the relationship example now. Still, you can define that if a user is the submitter or approver of a report, they have some **ownership** over it and are allowed to see that report, so let's start there. 

In the API context, you can define this ownership such that **the user making the request is the same user for which we want to see reports.** At the moment, your API doesn't have the context of the user other than an access token, which tells you only that they are authorized to access your API and that they are `admin` because [you added this role as a custom claim in the access token.](https://auth0.com/blog/what-is-rbac-and-how-to-implement-it-rails-api/#Creating-and-Assigning-Roles-with-Auth0)

So, that's great 🫠 how can you get information from the user in your API using Auth0? The answer is by connecting your Auth0 API and your Auth0 Application!

### Connect Your Auth0 API with your Auth0 Application 

If you have a REST API as your backend, chances are you have a frontend application where your users authenticate and manage their data, etc. 

When you use Auth0, your users can authenticate using [Universal Login](https://auth0.com/docs/authenticate/login/auth0-universal-login). So, you need to create an Auth0 Application for either a SPA or a Regular Web Application and [integrate it with your code using one of the SDKs](https://auth0.com/docs/libraries). For this blog post, let's focus on the example of the regular web application. 

[When you created the expense management API](https://auth0.com/blog/what-is-rbac-and-how-to-implement-it-rails-api/#Building-the-Starter-Application), you created an [Auth0 API](https://auth0.com/docs/get-started/apis) and an Auth0 Regular Web Application for testing purposes, well now you are going to use this Regular Web Application because in a real-life scenario, your users will probably authenticate themselves *somewhere* and once they're authenticated you proceed to do X or Y in your REST API. 

In the Regular Web Application you created in Auth0 for your users to authenticate, you need to implement login, logout, etc., and you can learn how to do so by following [any of the Developer Center Guides on Authentication](https://developer.auth0.com/resources/guides?type=web-app). Still, the general process is almost identical in all of them, and the outcome is that **you will get an access token from Auth0 issued for the authenticated user.** 
 
Then, you need to tell your Regular Web Application that your users will be interacting with your REST API and, therefore, its counterpart in Auth0, so when you request the access token, you need to provide the `audience` as well. An example of how to do this in a [Ruby on Rails Web application](https://developer.auth0.com/resources/guides/web-app/rails/basic-authentication) would be: 

```ruby
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: AUTH0_CONFIG['auth0_callback_path'],
 authorize_params: {
 scope: 'openid profile email',
 audience: 'https://rails-api-authorization', # pass the audience ✨
 }
 )
end
```

Once you pass the `audience`, you'll get a JWT token containing the information about the user, as well as any scopes and claims you've added. To learn more about the audience parameter [you can check out this post.](https://community.auth0.com/t/what-is-the-audience)

That's all you need to do for now in Auth0 to make this work, so let's get back to the code!

### Validate Ownership of the User Making the Request

You already added a method to check for the user's role, so similarly, you could do the same to check for the user's *ownership*. In the context of the expense management app, we'll say: 

> A user is allowed to see an expense report of another user if they are the subject of the access token 

At the moment, you do not store any information about the user's data in your database, but you will need the Auth0 user's ID to compare it. 

#### Add the Auth0 ID to the User Model

Let's create a migration to add a new field to the User model using the following command on your terminal: 

```bash
rails g migration AddAuth0IDToUsers auth0_id:string 
```

The command above will generate a new migration file under `db/migrate/YYYYMMDDHHMM_add_auth0_id_to_users.rb` that looks like this:

```ruby
class AddAuth0IdToUsers < ActiveRecord::Migration[7.0]
  def change
 add_column :users, :auth0_id, :string
  end
end
```

Then, execute the migration by running `rails db:migrate` on your terminal. 

Now, let's add a validation to the User model to make sure the `auth0_id` field is always present and unique. Go to `app/models/user.rb` and add the following code: 

```ruby
class User < ApplicationRecord
 has_many :expenses, foreign_key: :submitter_id
 has_many :submitted_reports, class_name: 'Report', foreign_key: 'submitter_id'
 has_many :reports_to_review, class_name: 'Report', foreign_key: 'approver_id'

 validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }, presence: true, uniqueness: true
  # 👇 new code 
 validates :auth0_id, presence: true, uniqueness: true
end
```

You're all set from the model level. Let's move to the controller level. 

#### Add the Ownership Validation to the Controller

Go to the `Secured` concern in `app/controllers/concerns/secured.rb` and add the following code: 

```ruby
# 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
  INSUFFICIENT_ROLES = {
 error: 'insufficient_roles',
 error_description: 'The access token does not contain the required roles',
 message: 'Permission denied'
 }.freeze
  # 👇 new code 
  NOT_OWNER = {
 error: 'not_owner',
 error_description: 'The access token does not belong to the current user',
 message: 'Permission denied'
 }.freeze
  # 👆 new code 

  def authorize
 token = token_from_request

 validation_response = Auth0Client.validate_token(token)

    @decoded_token = validation_response.decoded_token

    return unless (error = validation_response.error)

 render json: { message: error.message }, status: error.status
  end

  def validate_roles(roles)
    raise 'validate_roles needs to be called with a block' unless block_given?
    return yield if @decoded_token.validate_roles(roles)

 render json: INSUFFICIENT_ROLES, status: :forbidden
  end

  # 👇 new code 
  def validate_ownership(current_user)
    raise 'validate_ownership needs to be called with a block' unless block_given?
    return yield if @decoded_token.validate_user(current_user)

 render json: NOT_OWNER, status: :forbidden
  end
  # 👆 new code 

  private
  # ... 
end
```

You are adding a new hash called `NOT_OWNER` to specify the error message in case the user is not the owner of the access token being passed. Then, in the `validate_ownership` method, you're checking the access token and returning an error if the user is not the owner. Since you haven't implemented the `validate_user` method yet, let's add it to the token structure. 

Go to your `Auth0Client` class in `app/lib/auth0_client.rb` and add the following code: 

```ruby
# frozen_string_literal: true

require 'jwt'
require 'net/http'

class Auth0Client

  # Class members
  Response = Struct.new(:decoded_token, :error)
  Error = Struct.new(:message, :status)
  Token = Struct.new(:token) do
    def validate_roles(roles)
 required_roles = Set.new roles
 token_roles = Set.new token[0][Rails.configuration.auth0.roles]
 required_roles <= token_roles
    end
    # 👇 new code
    def validate_user(current_user)
 current_user.auth0_id == token[0]["sub"]
    end
    # 👆 new code
  end

  # Helper Functions
  # ...
end
```

The `validate_user` method checks the `current_user` variable (the user from whom you want to check the reports) against the owner of the access token. In the access token, you have information about the user's ID in Auth0 under the `sub` field, so you are comparing that against the `auth0_id` from the local database. 

Next, call the `validate_ownership` method in the `ReportsController`. You want to validate the user's ownership when they request to review or submit a report, so let's add the validation to the corresponding actions. 

Go to `app/controllers/reports_controller.rb` and add the following code: 

```ruby
class ReportsController < ApplicationController
 before_action :set_report, only: %i[ show approve ]
 before_action :set_user
 before_action :authorize

  # GET users/:user_id/reports/submitted
  def submitted
    # 👇 new code
 validate_ownership(@user) do # user is the owner of these reports
      @reports = Report.where(submitter_id: @user.id) # list only reports where user is submitter

 render json: @reports
    end
    # 👆 new code
  end

  # GET users/:user_id/reports/review
  def review
    # 👇 new code
 validate_ownership(@user) do # user is the owner of these reports
      @reports = Report.where(approver_id: @user.id) # list only reports where user is approver

 render json: @reports
    end
    # 👆 new code
  end

  # GET users/:user_id/reports/1/approve
  # ...
end
```

By adding the `validate_ownership` block in the controller together with the condition inside the query, you are implementing a form of ABAC because you're allowing or denying access based on certain attributes of the user or the report. 

### Validate that Only Approver Users can Approve Reports 

Even though this might be a new requirement, you already took care of this scenario when you first added RBAC. If you look at the `approve` action in the `ReportsController`:

```ruby
class ReportsController < ApplicationController
 before_action :set_report, only: %i[ show approve ]
 before_action :set_user
 before_action :authorize

  # GET users/:user_id/reports/submitted
  # ...

  # GET users/:user_id/reports/1/approve
  def approve
 validate_roles [ADMIN] do # if user is admin
      if @report.is_approver?(@user) # if user is the approver for this report
        @report.status = "approved"
        @report.save
 render json: @report
      end
    end
  end

  # GET users/:user_id/reports/1
  #...
end
```

The check for `@report.is_approver?(@user)` already confirms that 
 `@user` is the approver of `@report`. This is interesting because sometimes we mix up different authorization models without even realizing it, and that's okay as long as it fits your business model. s

### Validate that Approvals Only on Weekdays

You only have to add another validation to allow users to approve expense reports on weekdays, and this is possible by adding a new check to the `approve` action in the `ReportsController`. Go to `app/controllers/reports_controller.rb` and add the following code: 

```ruby
class ReportsController < ApplicationController
 before_action :set_report, only: %i[ show approve ]
 before_action :set_user
 before_action :authorize

  # GET users/:user_id/reports/submitted
  #...

  # GET users/:user_id/reports/1/approve
  def approve
 validate_roles [ADMIN] do # if user is admin
      if @report.is_approver?(@user) # if user is the approver for this report
        # 👇 new code 
        if Date.current.on_weekday? # can only approve on weekdays
          @report.status = "approved"
          @report.save
 render json: @report
        else
 render json: {message: "Can only approve on weekdays"}, status: 401
        end
        # 👆 new code 
      end
    end
  end

  # GET users/:user_id/reports/1
  #...
end
```

[The function `Date.current.on_weekday?`](https://api.rubyonrails.org/classes/DateAndTime/Calculations.html#method-i-on_weekday-3F) returns true if it's a weekday (Mon-Fri) and false otherwise. Users who try to approve during the week will get an error.

At this point, you've fulfilled all the requirements you've received so far! 🚀 It's time to go back to the client and discuss the progress you've made. 

> Up until here, all the changes in the code are available in the [`add-abac` branch of the repository.](https://github.com/auth0-blog/rails-api-authorization/tree/add-abac)

## What About Policies?

You're introducing a lot of extra complexity in the application code that needs to be recreated by each environment, such as web, mobile, CLI, etc. Using a policy engine can streamline application decision-making. 

[A policy](https://csrc.nist.gov/glossary/term/access_control_policy) is a set of rules defining a software service's behavior. There are access control systems like [Open Policy Agent (OPA)](https://www.openpolicyagent.org/), a full-featured policy engine that offloads policy decisions from your software so you don't have to implement it from scratch, or [Policy-Based Access Control (PBAC)](https://csrc.nist.gov/glossary/term/policy_based_access_control), where access control decisions are made based on the business roles of users and is combined with policies.

You won't implement PBAC for the sake of this tutorial, but I thought it was interesting for you to know that decision-making engines like these exist.

## Oh, No. What's Next?

You are showing your implementation to the client, and they're satisfied, but as usual, they came back with more requirements 🥲 

- Users who are managers can see the reports of their directs, plus the reports of their directs' directs, and so on 😵‍💫

You think of a way to implement this with your current solution and... recursiveness 🥲 you know this is possible, but you also start exploring what options are out there for these scenarios. You bump into Relationship-Based Access Control, which seems interesting 🤔 because you feel like basing your implementation on the relationships of your users could work, but you need to do more research. 

## Conclusion 

When we talk about attributes, we refer to properties of the entities of your application; in the expense management application example, we are talking about attributes of a user or an expense report. Attribute-Based Access Control is an authorization model that allows you to make decisions based on these attributes. ABAC gives you more granularity than RBAC because you can specify access control on specific resources other than a role that usually includes more than one resource. 

In the next blog post, you'll learn about ReBAC and its implementations. 

How to Implement Attribute-Based Access Control (ABAC) in a Ruby On Rails API?

There are different ways to implement an authorization system and the one you chose depends on your application's needs. Role-Based Access Control (RBAC) is just one of them, so let's go ahead and learn how to implement it in a Rails API.

How to Implement Role-Based Access Control (RBAC) in a Ruby On Rails API?

square-2

I develop software for a living, and then I go home and continue thinking about software because I just can’t get enough. I’m a full-stack engineer with infrastructure skills. I’ve led multiple agile delivery teams, being an individual contributor, driving architecture topics, and coaching and supporting other team members.<br>
I believe in high-quality software and advocate for Continuous Delivery, Test-Driven Development, and quick iteration. I <a href="https://hceris.com/blog">write</a> and <a href="https://hceris.com/talks">speak</a> about my experience regularly. Needless to say, all the opinions expressed in this blog are mine and only mine.

Staff Engineer

Mario Fernandez

Learn how to secure an API written using Ruby On Rails with Auth0 authorization services.

If you want to expose an API publicly on the Internet, authorization will be a requirement for you sooner or later. You want to verify that the client consuming the API has the appropriate permissions.

This guide is exactly about that. We'll be securing an API written using [Ruby On Rails](https://rubyonrails.org/), with [Auth0](https://auth0.com/) as the authorization server.

There's a repository with the code so that you can follow along in [Github](https://github.com/auth0-blog/rails-api-auth0).

## Securing an API

I didn't explain what I mean by securing an API yet. Essentially, we're ensuring that protected routes are accessible only for the users with enough rights.

When it comes to security, it's generally considered a bad idea to roll your own bespoke implementation. Instead, I'm using [OAuth](https://auth0.com/docs/protocols/protocol-oauth2), a battle-tested and widely used authorization framework for web applications.

In this context, Auth0 fulfills the role of the _authorization server_ and abstracts a significant part of the work away from us. That way, we can focus on delivering value to our users.

Without getting into too many details on how OAuth works, we assume that calls to our API will include a bearer token using the industry-standard [JWT](https://jwt.io/) format. The token contains a series of claims regarding its issuer, how long it is valid, and what rights it grants. Let's have a look at a sample token:

```json
{
  "iss": "https://yourTenant.eu.auth0.com/",
  "sub": "zHwnsh0j2sTj4u3ss6YedSFrzyb2",
  "aud": "https://targetAudience.com",
  "iat": 1621369130,
  "exp": 1791455530,
  "azp": "ThEkgdG1NndLlWoNMcEdEr2KJIs9vKad",
  "scope": "openid profile read:admin-messages",
  "permissions": ["read:admin-messages"]
}
```

We're going to implement verification for that token and reject requests that don't have the required permissions.

## Getting Started

We're getting started with our base application, bootstrapped with Rails 6. This [branch](https://github.com/auth0-blog/rails-api-auth0/tree/starter) is a good starting point. You can download it by running the following command in a terminal window:

```shell
git clone -b starter --single-branch https://github.com/auth0-blog/rails-api-auth0.git
```

The API has three endpoints with different levels of protection:

- `/api/messages/public`: Public route.
- `/api/messages/protected`: Requires a valid access token.
- `/api/messages/admin`: Requires a valid access token. Since Auth0 uses JWT as its access token format, we can inspect it and make sure it has a `permissions` claim that contains the scope `read:admin-messages`.

### Running the Application

To run the application, we first need the correct ruby version. The easiest way to do so is to use a version manager like [rbenv](https://github.com/rbenv/rbenv). Once you install it, run this command inside the repository to install the right version of ruby:

```shell
rbenv install
```

Install the dependencies for the application:

```shell
bundle install
```

And finally, run the application:

```shell
bin/rails s
```

You can verify that the application is working correctly with `curl`:

```shell
curl localhost:6060/api/messages/public
```

The command will return a 200 code, plus the message:

```json
{"message": "The API doesn't require an access token to share this message."}
```

### Creating an API on Auth0

To secure the API with Auth0, you need an Auth0 account. If you haven't one, you can <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up for free</a> right now. In the *APIs* section of the [Auth0 dashboard](https://manage.auth0.com/), click *Create API*. Provide a name and an identifier for your API. You will use the identifier as an `audience` later, when you are configuring the access token verification. Leave the *Signing Algorithm* as RS256.

![Create API](https://images.ctfassets.net/23aumh6u8s0i/5y9rQHvjBzjxQo5aDIrsKE/842c2fadf99e521fc20a8326dfa8ee2e/create-auth0-api.png)

Once you create the API, go to the _Permissions_ tab in the API details and add a permission called `read:admin-messages`.

![Create permission](https://images.ctfassets.net/23aumh6u8s0i/jT9dzB4AcCM0BAoYgCizu/2abc44d5604d03267b957281e93749a8/configure-permissions.png)

> **Note**: While you are in the Auth0 Dashboard, take note of your Auth0 domain. You will need it soon. This is a string in the form `YOUR-TENANT-NAME.auth0.com` where `YOUR-TENANT-NAME` is the name you provided when you created your account with Auth0. For more information, [check the documentation](https://auth0.com/docs/getting-started/the-basics#domains).

## Preparing the Application for Validation

Alright, our application is ready to go and in dire need of some _security_. Before that, we need to add some configurations.

You dutifully stored the `domain` and the `audience` after creating the API, right? Let's use them. In the _Rails_ world, the convention is to add this in the `config` folder, using [YAML](https://yaml.org/). The file is called `config/auth0.yml`.

We don't want to store credentials in our code, so we'll export the values as environment variables, named `AUTH0_DOMAIN` and `AUTH0_AUDIENCE`. The configuration uses those values and keeps them safely away from source control!

```yaml
development:
  issuerUri: <%= ENV["AUTH0_DOMAIN"] %>
  audience: <%= ENV["AUTH0_AUDIENCE"] %>
```

Now, set `AUTH0_DOMAIN` and `AUTH0_AUDIENCE` environment variables to the `domain` and `audience` values for your API.

With this, the application is ready to connect with Auth0. Let's move on to the implementation.

## Validating the Access Token

Before we get started, let's talk for a second about authentication frameworks for rails. There are a bunch of alternatives in the ecosystem, such as [CanCanCan](https://github.com/CanCanCommunity/cancancan), or [devise](https://github.com/heartcombo/devise).

However, our case is an awkward fit for those. We don't want to take over user management. We only want to validate tokens issued by the authorization server. In this case, using a framework won't bring us as much benefit as something like, say, [Spring Security](https://spring.io/projects/spring-security). That's why we only rely on an extra gem, [jwt](https://github.com/jwt/ruby-jwt).

The code implementing the authorization check lives in the [add-authorization](https://github.com/auth0-blog/rails-api-auth0/tree/add-authorization) branch. Let's see how it works!

### Utilizing the JWT Library

The `jwt` library brings a lot of functionality to make our API able to validate and manage tokens in JWT formats like the ones issued by Auth0. We need to do three things:

- We need to fetch the [JWKS](https://auth0.com/docs/tokens/json-web-tokens/json-web-key-sets) configuration from _Auth0_ so that we know what is the public key to verify the access token signature
- With the public key, the issuer, and the audience, we want to verify the token
- After verifying the token, we're decoding it to access the `permissions` claim (or any other information contained in the token, really)

### Decoding the Token

Let's get down to business. We're implementing the verification/decoding logic in the `lib` folder, in a file called `json_web_token.rb`. We're starting by fetching the _JWKS_ data:

```ruby
# lib/json_web_token.rb
require 'jwt'
require 'net/http'

class JsonWebToken
  class << self
    def algorithm
      'RS256'
    end

    def key(header)
      jwks_hash[header['kid']]
    end

    def jwks_hash
      jwks_raw = Net::HTTP.get URI("#{issuer}.well-known/jwks.json")
      jwks_keys = Array(JSON.parse(jwks_raw)['keys'])
      jwks_keys.map do |k|
        [
          k['kid'],
          OpenSSL::X509::Certificate.new(Base64.decode64(k['x5c'].first)).public_key
        ]
      end.to_h
    end

    def issuer
      "https://#{Rails.application.config.x.auth0.issuerUri}/"
    end
  end
end
```

As you can see, through the `issuerUri` we know where to look for the data. Then, we parse the key so that we can consume it in the library.

The next step is to add an extra method to the class, `verify`, that verifies and decodes the token at the same time:

```ruby
# lib/json_web_token.rb
class JsonWebToken
  class << self
    def verify(token)
      JWT.decode(token, nil,
                 true, # Verify the signature of this token
                 algorithm: algorithm,
                 iss: Rails.application.config.x.auth0.issuerUri,
                 verify_iss: true,
                 aud: Rails.application.config.x.auth0.audience,
                 verify_aud: true) do |header|
        key(header)
      end
    end
    
    # ... existing code ...
    
  end
end
```

This is all the code that we need for the actual verification. Neat, isn't it? But our controllers are still insecure. Not for long, though.

## Protecting the Endpoints

To make it as convenient as possible, we're creating a hook that we're going to run before any route that needs authentication. To make it available for every controller, it lives in the `app/controllers/application_controller.rb`:

```ruby
# app/controllers/application_controller.rb
require 'json_web_token'

class ApplicationController < ActionController::API
  def authorize!
    valid, result = verify(raw_token(request.headers))

    head :unauthorized unless valid

    @token ||= result
  end

  private

  def verify(token)
    payload, = JsonWebToken.verify(token)
    [true, payload]
  rescue JWT::DecodeError => e
    [false, e]
  end

  def raw_token(headers)
    return headers['Authorization'].split.last if headers['Authorization'].present?

    nil
  end
end
```

We take the token from the standard _Authorization_ header. Then, we verify it with the code from the previous section. There are two possible paths after running `authorize!`:

- If the token isn't there, or it's invalid for any reason, the processing stops right there, and the call returns a 401
- If the token is valid, we continue the execution and store the token in `@token` so that it's available

We're protecting both the `protected` and the `admin` routes with this hook, thanks to [before_action](https://api.rubyonrails.org/v6.1.4/classes/AbstractController/Callbacks/ClassMethods.html#method-i-before_action):

```ruby
# app/controllers/api/messages_controller.rb
module Api
  class MessagesController < ApplicationController
    before_action :authorize!, except: %i[public]
end
```

### Custom Error Messages

Don't you feel better knowing that the application is not exposing private stuff anymore? I definitely do. But we got to help our users. A blank 401 message might not give them enough information to debug the issue. Let's extend the hook to return something more explicit:

```ruby
# app/controllers/application_controller.rb
class ApplicationController < ActionController::API
   def authorize!
     valid, result = verify(raw_token(request.headers))

     # 👇 old code
     # head :unauthorized unless valid
     # 👇 new code
     render json: { message: result }.to_json, status: :unauthorized unless valid

     @token ||= result
   end
```

Now we get a message that's more helpful than an HTTP code without a body.

## Testing the Protected Endpoints

Let's test the protected endpoint:

```shell
curl localhost:6060/api/messages/protected
```

The command will return a 401, because we're not authorized. We need to get a valid token from Auth0.

The simplest way is to access the [API section of your Auth0 Dashboard](https://manage.auth0.com/#/apis) again, select the API that you created before and click the *Test* tab. In this section, you can get a temporary token to test your Web API by clicking the *Copy Token* icon as shown in the following picture:

![Test Token](https://images.ctfassets.net/23aumh6u8s0i/6zmU9XWwgZLWIAFF0qu6IP/50e2aa27469142c138b814731aa0233d/copy-access-token.png)

Let's attach the token to the request:

```shell
export TOKEN=the-test-token
curl localhost:6060/api/messages/protected -H "Authorization: Bearer $TOKEN"
```

The request works now! 

```json
{"message": "The API successfully validated your access token."}
```

## Checking for permissions

There's one requirement pending. As you might recall, for `/api/messages/admin` a valid token isn't enough. Rather, we expect the correct permission in the `permissions` claim. This extra check allows us to define more granular access criteria for our endpoints. This functionality is implemented in the [add-rbac](https://github.com/auth0-blog/rails-api-auth0/tree/add-rbac) branch.

We're adding a new method in the `application_controller`, `check_permissions`. It takes the decoded token and looks for a given permission:

```ruby
# app/controllers/application_controller.rb
require 'json_web_token'

class ApplicationController < ActionController::API
  # ... existing code ...
  
  def can_read_admin_messages!
    check_permissions(@token, 'read:admin-messages')
  end
  
  def check_permissions(token, permission)
    permissions = token['permissions'] || []
    permissions = permissions.split if permissions.is_a? String

    unless permissions.include?(permission)
      render json: { message: 'Access is denied' }.to_json,
             status: :unauthorized
    end
  end
  
  # ... existing code ...
end
```

We use a `before_action` again to protect the `admin` endpoint:

```ruby
# app/controllers/api/messages_controller.rb
module Api
  class MessagesController < ApplicationController
    before_action :can_read_admin_messages!, only: %i[admin]
    
    # ... existing code ...
end
```

With this, each route in our sample application is safe the way we wanted.

### Testing Permissions

If you try to call the `/api/messages/admin` endpoint with the token we generated before, it will return a 401. Our token is valid but doesn't have the necessary permissions. Let's create a new one!

Back in your [API configuration page on the Auth0 Dashboard](https://manage.auth0.com/#/apis), select the *Machine to Machine Applications* tab. You'll get a list of applications, some of them with the *(Test Application)* label in the name. These applications are automatically created by Auth0 when you create an API there. They are meant as test clients from your API. One of them should have the *Authorized* switch on. Click the dropdown next to it and check the `read:admin-messages` permission:

![Adding Permissions](https://images.ctfassets.net/23aumh6u8s0i/2Iva8EtxfjdsunLbDTGVyD/71034bf799e82e51c7e5f7152ccd6adf/adding-permissions.png)

Then, click the *Update* button, move again to the *Test* tab, and copy the new token that has been generated for you. Let's try again:

```shell
export TOKEN=the-new-test-token
curl localhost:6060/api/messages/admin -H "Authorization: Bearer $TOKEN"
```

The request works now!

```json
{"message":"The API successfully recognized you as an admin."}
```

## Conclusion

In this guide, we've added authorization to a Rails API by using Auth0 as an authorization server. Thanks to the `jwt` gem, we don't have to invest much effort. We use the library to decode the bearer token that the API receives. After that, it's a matter of checking the relevant routes before each request.


Secure a Rails API with Auth0

685342d5e7f42c3ab8d251d7d4a53308?s=100&d=mm&r=g avatar

685342d5e7f42c3ab8d251d7d4a53308?s=100&d=mm&r=g

Former Auth0 Employee

Robin Percy

Using Ruby on Rails to combine Auth0 Login with Iris Recognition for Two Factor Authentication

"ruby on rails"