Installation

gem 'authsignal-ruby'

Initialization

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

You can find your client or tenant ID in the Authsignal Portal.

You must specify the correct base URL for your tenant’s region.

RegionBase URL
US (Oregon)https://api.authsignal.com/v1
AU (Sydney)https://au.api.authsignal.com/v1
EU (Dublin)https://eu.api.authsignal.com/v1

For example, to set the base URL to use our AU region:

require 'authsignal'

Authsignal.setup do |config|
    config.api_secret_key = ENV["AUTHSIGNAL_SECRET_KEY"]
    config.base_uri = "https://au.api.authsignal.com/v1"
end

track

track lets you record actions performed by users and initiate challenges.

result = Authsignal.track({
    user_id: "usr_123",
    action: "withdrawal",
    redirect_url: "https://example.com/finalize-withdrawal",
})

case result[:state]
when "ALLOW"
    # Carry on with your operation/business logic
when "BLOCK"
    # Stop your operations
when "CHALLENGE_REQUIRED"
    # Step up authentication required, redirect or pass the url to the front end
    result[:url]
end

Arguments

Returns

validate_challenge

validate_challenge lets you validate the result of a challenge using the token which is obtained after a redirect (if using the pre-built UI) or returned by a client SDK (if using an embedded flow).

result = Authsignal.validate_challenge(
    token: token
)

When performing MFA for a user who has already been authenticated by a primary factor (e.g. username & password), it’s important to check the token belongs to that user. The validateChallenge method will do this check if you pass both the token and the userId.

Arguments

Returns

get_user

get_user retrieves a user and their MFA enrollment status.

result = Authsignal.get_user(user_id: current_user.id)

is_enrolled = result[:is_enrolled]

Arguments

Returns

get_action

Get detailed information on a tracked action.

result = Authsignal.get_action(
    user_id: "1234",
    action: "signIn",
    idempotency_key: "15cac140-f639-48c5-92db-835ec8d3d144")

Arguments

Returns

rules
object[]

enroll_verified_authenticator

enroll_verified_authenticator can be used to enroll an authenticator on behalf of a user if it has already been verified.

Authsignal.enroll_verified_authenticator(user_id: "1234",
                              authenticator:{ oob_channel: "SMS",
                                              phone_number: "+64270000000" })

Arguments

Returns

authenticator
object
recoveryCodes
string[]