Ruby on Rails

This guide will demonstrate how to integrate Authsignal in a Ruby on Rails app in two scenarios, Multi-factor Authentication flows on “Sign in” and on a example user action e.g. “Withdrawing Money”.

This guide uses the most widely used Authentication gem Devise/Warden as an example, the Stimulus.JS as the client side library to handle challenge flows, and assumes that you have these libraries already configured.

Installation

Add the Authsignal Ruby gem into your Gemfile:

Github: https://github.com/authsignal/authsignal-ruby

Rubygems: https://rubygems.org/gems/authsignal-ruby

gem 'authsignal-ruby'

Add the @authsignal/browser JavaScript client:

npm

npm install @authsignal/browser

Yarn

yarn add @authsignal/browser

pnpm

pnpm add @authsignal/browser

Add the Authsignal initialization code block into config/initializers/authsignal.rb:

require 'authsignal'

Authsignal.setup do |config|
    config.api_secret_key = ENV["AUTHSIGNAL_SECRET_KEY"]
end

Initialize the @authsignal/browser) client anywhere your Javascript gets loaded. This could be in app/javascript/application.js. Doing this initializes the Authsignal cookie.

window.authsignal = new Authsignal({tenantId: "YOUR_TENANT_ID"})

Allowing your users to enroll

The first step is allow your user to enroll authenticators. This step assumes you have already setup at least one Authenticator for your tenant in the admin portal.

Authsignal's ruby SDK allows you to check a user's enrollment status and provides the URL for your user to manage their authenticators.

The following is an example of a controller action that redirects the user to the Authsignal enrollment and management flow and sets a redirect url when the user completes the self-service flows.

The most important thing to note is that in order to trigger a flow which allows the self service enrollment and management screens you need to add the following attribute to the track_action input redirect_to_settings: true Read more on enrolling authenticators

class MfaController < ApplicationController

    def index
        response = Authsignal.track_action({
                                action_code: "enrollment",
                                redirect_url: root_url,
                                user_id: user.id,
                                email: user.email,
                                device_id: authsignal_cookie,
                                user_agent: auth.request.user_agent,
                                ip_address: auth.request.ip,
                                redirect_to_settings: true})

        redirect_to response[:url], allow_other_host: true
    end
end

Devise/Warden - (Sign In Scenario)

This step in the guide implements MFA challenge flows in a typical Devise Sign in scenario and uses the authsignal-ruby SDK. If Authsignal returns a challenge and the user is enrolled with authentication factors, we will redirect the user to a challenge flow and on completion of the challenge, complete the login process.

Insert the following after_authentication hook into config/initializers/warden.rb. This block fires after a successful login and makes the track_action call.

Warden::Manager.after_authentication do |user,auth,opts|
        # Using this cookie will help with rules that require device tracking
    authsignal_cookie = auth.request.cookies["__as_aid"]
    response = Authsignal.track_action({
                                action_code: "signIn",
                                redirect_url: Rails.application.routes.url_helpers.complete_mfa_url(idempotencyKey: idempotencyKey),
                                user_id: user.id,
                                email: user.email,
                                device_id: authsignal_cookie,
                                user_agent: auth.request.user_agent,
                                ip_address: auth.request.ip})

    case response[:state]
    when "BLOCK"
        # If Authsignal rules give back a BLOCK decision, then do
        # not log the user in and log out
        auth.logout
        throw(:warden, :message => "Your account is blocked")
    when "CHALLENGE_REQUIRED"
        auth.env["authsignal_devise.response"] = response
    end
end

Override the Devise Sessions controller by creating a new controller file in app/controllers/users/sessions_controller.rb:

class Users::SessionsController < Devise::SessionsController
    def create
        super do |resource|

            # If There's a challenge flow initiated
            if request.env["authsignal_devise.response"]
                session[:authsignal_user_id] = resource.id
                sign_out(resource)
                redirect_to request.env["authsignal_devise.response"][:challengeUrl], allow_other_host: true
                return
            end
        end
    end

    def complete_mfa
        idempotency_key = params[:idempotencyKey]
        user_id = session[:authsignal_user_id]
        user = User.find(user_id)
        session[:authsignal_user_id] = nil
        response = Authsignal.get_action(user_id: user.id,
                                           action_code: "signIn",
                                         idempotency_key: idempotency_key)

        if response[:state] === "CHALLENGE_SUCCEEDED"
            sign_in user
            redirect_to after_sign_in_path_for(user)
            return
        end

        flash[:alert] = "Failed Step Up Authentication"
        redirect_to root_path
    end
end

Register the newly created Sessions controller and the new complete_mfa action into your routes.rb file:

devise_for :users, :controllers => {:registrations => "users/registrations", :sessions => "users/sessions"}

devise_scope :user do
  get 'users/complete_mfa', to: 'users/sessions#complete_mfa', as: :complete_mfa
end

You now have your sign-in flows protected with Authsignal.

User Action Scenario

Authsignal is designed to be dropped into any part of your user journey, not just sign-in. The next part of the guide will show how to use the Challenge flow pop-up via the @authsignal/browser) JavaScript client, in conjunction with the server-side track action call.

It assumes that that you are using Stimulus as the client-side library for handling browser-based Javascript, but this approach could be used with any client-side library or framework (React, Vue). The flow follows the convention described in the How Authsignal Works section.

Server-side

class WithdrawalController < ApplicationController
    before_action :authenticate_user!
    skip_before_action :verify_authenticity_token, only:[:create, :complete]

    def create
        # Using this cookie will help with rules that require device tracking
        authsignal_cookie = auth.request.cookies["__as_aid"]

        response = Authsignal.track_action({
                                    action_code: "withdrawal",
                                    user_id: current_user.id,
                                    email: current_user.email,
                                    device_id: authsignal_cookie,
                                    user_agent: request.user_agent,
                                    ip_address: request.ip
                                    custom: {
                                        withdrawal_amount: params[:amount]
                                    }
                                })

        case response[:state]
        when "BLOCK"
            render :json => { error: "Withdrawal has been blocked" }, :status => :forbidden
            return
        when "CHALLENGE_REQUIRED"
            render :json => { challenge_url: response[:url],
                              idempotency_key: response[:idempotency_key]
                               error: "Challenge Required" }, :status => :unprocessable_entity
            return
        when "ALLOW"
            complete_withdrawal
            render :json => { success: true }
            return
        end
    end

    def complete
        idempotency_key = params[:idempotency_key]

        # This call fetches the action that was previously created
        # The response specifies whether the user has completed the challenge successfully
        response = Authsignal.get_action(user_id: current_user.id,
                                        action_code: "withdrawal",
                                        idempotency_key: idempotency_key)

        # Complete your action if the challenge was successful
        if ["CHALLENGE_SUCCEEDED", "ALLOW"].include?(response[:state])
            complete_withdrawal
            render :json => { success: true }
            return
        else
            render :json => { error: "Challenge has not been completed" }, :status => :forbidden
            return
        end
    end

    private
    def complete_withdrawal
        # Business logic to complete your withdrawal step
    end
end

Here is an example of a server-side action that simulates a “Withdraw” money flow, which is a typical use case where you might want to protect your user with a step-up challenge. There are two actions in this controller: create which calls track_action and complete which is called after the user finishes a challenge flow. These are all called via a JSON request from the stimulus client-side.

Client side

Rails View

<div data-controller="withdrawal">
  <input data-withdrawal-target="amount" type="text" />
  <button type="button" data-action="click->withdrawal#withdraw">
    Withdraw
  </button>
  <div></div>
</div>

Stimulus Controller

// withdrawal_controller.js
import { Controller } from "@hotwired/stimulus";

export default class extends Controller {
  static targets = ["amount"];

  async withdraw() {
    const amount = { amount: this.amountTarget.value };
    const response = await fetch("/withdrawal", {
      method: "POST",
      headers: {
        Accept: "application/json",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ amount }),
    });

    const result = await response.json();

    // If the challenge_url is returned then we need to trigger
    // the authsignal challenge flow
    if (result.challenge_url) {
      const { idempotency_key } = result;

      // This step brings up the challenge pop up
      // When the challenge flow completes the pop up will close and the promise
      // will resolve
      const challengeFlow = await window.authsignal.launch(
        result.challenge_url,
        { mode: "popup" }
      );

      // Return the idempotency key from the initial result,
      // as part of the complete request
      if (challengeFlow) {
        const complete_step_response = await fetch("/withdrawal/complete", {
          method: "POST",
          headers: {
            Accept: "application/json",
            "Content-Type": "application/json",
          },
          body: JSON.stringify({ amount, idempotency_key }),
        });
        const complete_step_result = await complete_step_response.json();

        const { success } = complete_step_result;

        success
          ? alert("Great your user has successfully completed the action")
          : alert("Great your user has  not successfully completed the action");
      }
    }
  }
}