Authenticate Your Rails API with JWT

In this tutorial I will be teaching you how to add basic authentication to your Rails API using JWT. This authentication will help secure your API from any unauthorized user.

Before we proceed I will like to briefly explain some terms that we will encounter in this tutorial:

ATHENTICATION
According to Wikipedia, authentication is the act of proving an assertion, such as the identity of a computer user. This authentication will serve as routes guide to only allowing verified user with valid token to access our API resources.

And for this act we will be using a very popular gem called jwt or pronounced as ‘jot’

JWT
JWT is short for JSON Web Token, is an internet standard for creating data with optional signature and/or encryption whose payloads holds JSON (JavaScript Object Notation) that asserts some number of claims. JWT allows us to decode, verify and generate secret tokens for our applications.

For this tutorial we will be building a simple Rails CRUD API for posts.

And we will authenticate the post routes to prevent any unregistered and/or not logged in user from having access to the resource that the routes provides.

This functionality can be extended to other routes in your application if you want to, just by adding a simple before_action line of code in your controllers.

NOTE: This tutorial assumes that you already have a basic knowledge of Rails app and Ruby programming language although we will be building everything from scratch.

Without further ado let’s get started

STEP 1: Create a new project

Type the following command in your terminal and click enter
rails new post-app --api
This will create a project called “post-app” and the --api flag will create a minimal build for building api without adding all the bulk required for rendering views. Once this is done head into your app directory by typing cd post-app then click enter.

STEP 2: Configure your GemFile

Make sure you have the following gem in your GemFile you can either add them or uncomment them if already present.

gem 'bcrypt', '~> 3.1.7'
gem 'rack-cors'
gem 'jwt'

Once that is done, in your terminal run the command bundle install to add these 3 new dependencies to your project.

bcrypt: bcrypt gem will help us encrypt a user’s password on registration and also verify the password with the hashed password in our database during login. This will help keep our users account safe should in case someone hacks into our database.

rack-cors: rack-cors will allow us to manage Cross Origin Resource Sharing (CORS). This way we decide which URLs is allowed to make request to our API.

jwt: jwt will let us issue JSON Web Token containing encrypted information on user registration and login. Our API will search for this token in the header of subsequent requests that the user makes to verify if the user is authorized to access that data.

STEP 3: Setup CORS

Let’s setup our cors file; move into config/initializers/cors.rb and uncomment this file

Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins '*'

    resource '*',
      headers: :any,
      methods: [:get, :post, :put, :patch, :delete, :options, :head]
  end
end

then change the origins from example.com to * then save the file.

STEP 4: Generate Models

In your terminal run the commands to create the user and post model
User Model:
rails g model User firstname:string lastname:string email:string password:digest
This command will create a user.rb model in our Models folder and a create_users.rb migration file inside our migration folder in our db directory.

The digest data type used for our password field is a convention that tells bcrypt to encrypt whatever the user enters as password.

Post Model:
rails g model Post title:string body:text

Modify app/models/user.rb to look like this

class User < ApplicationRecord
  has_secure_password

  validates :firstname, presence: true
  validates :lastname, presence: true
  validates :email, presence: true
  validates :password, length: { minimum: 6 }, presence: true
end

Modify app/models/post.rb to look like this

class Post < ApplicationRecord
  validates :title, presence: true
  validates :body, presence: true
end

then run this command rails db:migrate to create our users and posts table in the database.

STEP 5: Create Users Controller

Now to the more fun part let’s create our users controller. Head into app/controllers create a folder named api then inside the api folder create another folder named v1 now inside the v1 folder create a file and name it users_controller.rb and write the following code.

https://gist.github.com/its-nedum/e1ad18732bdcd82dfd93e5844013dd65

create: this method create a new user record in the database but before that it ensures that a user doesn’t register more than once be checking if the email provided already exists in the database but if it doesn’t exists then a new record will be added in the database and a JSON web token will be generated for the user using his provide credentials (firstname, lastname, email and user_id from the database) with the help of the encode_token method which I will explain later.

NB: Be careful not to include sensitive user information like password in the generated token.

login: the login method finds the user in the database using their email and if the user exists and their password is verified with the encrypted password in the database by bcrypt using the authenticate method then a token will be generated and sent along with a success message.

SECRET_KEY: Every Rails application has a unique secret key that comes with it. We use the secret key to encrypt our JWT token. Although your secret key can be anything you want but I prefer to use the rails secret key.

encode_token: As the name implies it generate a token using the user’s credentials as payload and encrypt it with our Rails app secret key and an expiration time of 24hours after which the generated token can no longer be allowed on our app. This was made possible by the encode method found in our JWT object.

So now we can generate token for all of our users on successful registration and login, how do we check if user’s subsequent request has this token? Onto the next step

STEP 6: Configure Application Controller

Head into app/controllers/application_controller.rb This is where we write the method that retrieves the token from a user’s request headers(authorize_request), decodes it (decode_token) by verifying it with our SECRET_KEY and if the token is genuine then the user is allowed access to the data the requested else an error message will be returned.

https://gist.github.com/its-nedum/c83287243cfba317993e329380a5d9ff

STEP 7: Create Posts Controller

The post controller will hold our authenticated posts routes. Head into app/controllers/api/v1 and create a new file named posts_controller.rb

https://gist.github.com/its-nedum/72b92c9d699cb86e0ab7312dbd97976a

Adding the before_action :authorize_request command immediately after the class declaration tells Rails to run authorize_request method (that we created in our application_controller.rb file) first before running any of our posts endpoints. With this setup whenever a user try to access any post routes they will be required to provide an authorization token as part of the request header.

STEP 8: Configure Your Routes

As it is now we can’t consume any of these endpoints because our routes are not setup yet. So for the final step head into the config/routes.rb and set up your API routes like so

Rails.application.routes.draw do

  namespace 'api' do
    namespace 'v1' do
      resources :users, only: [:create]
      post '/login', to: "users#login"
      resources :posts
    end
  end

end