Skip to main content
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”. It 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:
Add the @authsignal/browser JavaScript client:
Add the Authsignal initialization code block into config/initializers/authsignal.rb:
Initialize the @authsignal/browser client anywhere your Javascript gets loaded. This could be in app/javascript/application.js. Doing this initializes the Authsignal cookie.

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.

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 call.
Override the Devise Sessions controller by creating a new controller file in app/controllers/users/sessions_controller.rb:
Register the newly created Sessions controller and the new complete_mfa action into your routes.rb file:
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 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

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 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
Stimulus Controller