Phone Authentication in Ruby

Using SMS to authenticate a user has the following benefits:

  • Everybody has a phone.
  • Users don't have to remember passwords.
  • Protect against robots & duplicate accounts.
  • Familiarity.

You should not use SMS a sole authentication method for systems that require high-security.

What I am going to cover in this article is how to make an API that generates "phone tokens" that can be used to sign-in / sign-up. This way you don't need to create a user record before a phone is verified.

User stories

Below is 2 user stories we are going to cover.

As a returning user.
I want to sign-in.
I go to the login screen and enter my phone.
I receive an SMS with the verification code, enter the code.
I am logged in.


As a new user.
I want to sign-up.
I go to the login screen and enter my phone.
I receive an SMS with the verification code, enter the code.
I enter my name and email and hit submit.
I am registered and logged in.



To make the 2nd story (sign up) work, upon phone verification we want to return a secure phone token that, together with name and email can be exchanged to create a new account.

Phone token is going to be an encoded phone string signed by our secret key as proof that it originated from our system.

Pseudo-code API (Controller Code)

An important bit is that both sign-in and sign-up flows start with entering a phone number and getting a phone token. Your app can then check if a user with such phone already exists, if it does, then simply login, otherwise proceed to sign up.


# ask user for a phone and send an SMS code
POST /send-phone-verification { phone: '+19178456780' }
PhoneVerification.send_verification(phone: params[:phone])
=> {}


# verify the phone entering the code from SMS,
# get encoded phoneToken in return
POST /verify-phone { phone: '+19178456780', code: '123456' }
phone_token = PhoneVerification.code_to_phone_token(
  phone: params[:phone],
  code: params[:code]
)
=> { phoneToken: phone_token }


# exchange the phoneToken to a user information
POST /sign-in { phoneToken: 'xxxxxxxxxxxxx' }
trusted_phone = PhoneVerification.phone_token_to_phone(params[:phone_token])
user = User.find_by_phone(trusted_phone)
=> { user: user }

# OR

# use the phone token to create a new user with verified phone
POST /sign-up { phoneToken: 'xxxxxxxxxxxxx', name: 'John Doe', email: 'john@example.com' }
trusted_phone = PhoneVerification.phone_token_to_phone(params[:phone_token])
user = User.find_or_create_by!(phone: trusted_phone) do |u|
  u.name = params[:name]
  u.email = params[:email]
end
=> { user: user }

Implementation

In order to implement this we are going to need the following:

Without further ado, let's jump into code

You can read the full code at https://github.com/TheRusskiy/rails-phone-auth.
Thank you for reading!

p.s. I recommend against using SMS as a sole means of authentication for security-critical apps such as banking, admin dashboards and other systems where gaining access to a single account can give a lot of value, only use it in conjunction with passwords. A dedicated attacker can spoof SMS of a specific user.

Popular posts from this blog

HTTP server in Ruby 3 - Fibers & Ractors

Image
This is part #2. Head over to part #1 to learn about HTTP in Ruby. Motivation Historically Ruby's been lacking in the concurrency department. Ruby has "native" threads (prior to 1.9 there were only "green"), which means there can be multiple threads controlled by an OS, but only 1 thread can be executed at a time, this is managed via Global Interpreter Lock (GIL). However, native calls and I/O calls can be executed in parallel. During an I/O call, a thread gives up control and waits for a signal that the I/O has finished. This means I/O heavy applications can benefit from multiple threads. In this article we are going to explore different concurrency modes for our HTTP server: Single-threaded Multi-threaded Fibers Ractors Single-threaded Let's start simple and see how a single threaded HTTP server could look like ( full code ): def start socket = TCPServer.new(HOST, PORT) sock...
Read more

Next.js: restrict pages to authenticated users

Image
Many websites have pages that need to be restricted to authenticated users, for example profile pages or dashboards. Next.js web framework comes with a lot of functionality built-in JS compilation, rendering code on server and caching. When it comes to most other aspecs, it's up to a programmer to build, including such needed functionality as restricting access to some pages only to authenticated users. In this article we are going to build just that: a function that augments a page object, that could be used like that: Here's the implementation in TypeScript: In order to make it work on server we are going to need one more utility function fetchWithCookies . When making HTTP request from inside a Web Browser, the browser automatically sends cookies with each requests and then stores new cookies if a response comes in with set-cookie header. On server-side we need to build this feature ourselves, because neither Next.js nor NodeJS make any a...
Read more

Migration locks for TypeORM

Image
Schema migrations is a must-have functionality for any DB framework. TypeORM provides decent utilities for dealing with migrations, however having a decade of experience in Ruby on Rails I got really spoiled and take some features for granted. One of these features is locking a database while a migration going on so 2 processes running concurrently don't step on each other's toes. This is also important when you run migrations in Kubernetes before launching your app. I was really surprised to find out that this basic feature is not supported , so decided to implement it on my own. Implementation // typeormMigrationUtils.ts import { Connection, createConnection } from 'typeorm' import config from '../ormconfig' import CRC32 from 'crc-32' const MIGRATOR_SALT = 2053462845 async function withAdvisoryLock( connection: Connection, callback: () => Promise<void> ): Promise<boolean> { // generate a unique lock...
Read more