Ruby

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.

Region	Base 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 challengeUrl to the front end
    result[:challenge_url]
end

Arguments

Refer to the Server API's Track action request object.

Returns

Refer to the Server API's Track action response object.

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
)

caution

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

Name	Type	Description
token	string	The token obtained after a redirect (if using the pre-built UI) or returned by a client SDK (if using an embedded flow).
user_id	string	(Optional) The ID of the user. Only pass this if doing step-up auth on an existing user session (i.e. not for login).

Returns

Name	Type	Description
is_valid	bool	True if the challenge was completed successfully.
state	hash	The state of the action associated with the challenge. Possible values are CHALLENGE_REQUIRED, CHALLENGE_SUCCEEDED, CHALLENGE_FAILED, ALLOW, or BLOCK.
user_id	string	The ID of the user.

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

Refer to the Server API's Retrieve user request object.

Returns

Refer to the Server API's Retrieve user response object.

get_action

get_action lets you determine the result of a challenge after the user has been redirected back from the Authsignal pre-built UI (or after the popup has been closed, if showing the page in a modal).

result = Authsignal.get_action(
    user_id: "1234",
    action: "signIn",
    idempotency_key: "15cac140-f639-48c5-92db-835ec8d3d144")
if (result.state === "CHALLENGE_SUCCEEDED") {
    // The user successfully completed the challenge
    // Proceed with the signIn
}

Arguments

Refer to the Server API's Get action status request object.

Returns

Refer to the Server API's Get action status response 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

Refer to the Server API's Enroll verified authenticator request object.

Returns

Refer to the Server API's Enroll verified authenticator response object.