Class: SecondFactor::AuthManager

Inherits:
Object
  • Object
show all
Defined in:
lib/second_factor/auth_manager.rb

Overview

This class is responsible for managing any actions that require second factor authentication before a user is allowed to perform them. Such actions include granting another user admin access, changing password and signing in. In a more technical sense, an action is the logic encapsulated in a Rails controller action without the logic related to 2fa enforcement/handling.

When a user attempts to perform a 2fa-protected action, there are 3 possible outcomes:

  1. the user doesn’t have any suitable 2fa methods enabled, so they should be

allowed to perform the action right away.

  1. the user has a suitable 2fa method enabled, in which case there are 2

possibilities:

a. the user hasn't done 2fa for the action so they should be redirected to
the 2fa page and complete the 2fa before they are allowed to proceed.
b. the user has done 2fa for the action so they should be allowed to perform
the action.

This class, the auth manager, contains the logic for deciding which outcome should happen and performing it.

To use the auth manager for requiring 2fa for an action, it needs to be invoked from the controller action using the ‘run_second_factor!` method which is available in all controllers. This method takes a single argument which is a class that inherits from the `SecondFactor::Actions::Base` class and implements at least the following methods:

  1. no_second_factors_enabled!(params):

This method corresponds to outcome (1) above, i.e. it's called when the user
performing the action has no suitable 2fa method enabled. It receives the
request params of the controller action. Return value is insignificant.

  1. second_factor_auth_required!(params):

This method corresponds to outcome (2a) above. It also receives the request
params of the controller action. The purpose of this method is to keep track
of the params that are needed to perform the action and where they should be
redirected after the user completes the 2fa.

To communicate this information to the auth manager, the return value of this
method is utilized for this purpose. This method must return a Hash that
should have 2 keys:

:callback_params => another Hash containing the params that are needed to
finish the action once 2fa is completed. Everything in this Hash must be
serializable to JSON.

:redirect_url => where the user should be redirected after they confirm 2fa.
A relative path (must be subfolder-aware) is a valid value for this key.

:description => optional action-specific description message that's shown on
the 2FA page.

After this method is called, the auth manager will send a 403 response with a
JSON body. It does that by raising an exception that's then rescued by a
`rescue_from` handler. The JSON response contains a challenge nonce which the
client/frontend will need to complete the 2fa. More on this later.

  1. second_factor_auth_completed!(callback_params):

This method corresponds to outcome (2b) above. It's called after the user has
successfully completed the 2fa for the 2fa-protected action and the purpose
of this method is to actually perform that action.

The `callback_params` param of this method is the `callback_params` Hash from
the return value of the previous method.

There are 2 additionals methods in the base class that can be overridden, but they’re optional:

  1. skip_second_factor_auth?(params):

This method returns false by default. As the name implies, this method can be
used to skip the 2FA for the action entirely. For example, if your action
deletes a user, then you may want to require 2FA only if the deleted user has
more than a specific number of posts. If you override this method in your
action, you must implement the following method as well.

  1. second_factor_auth_skipped!(params):

This method is called when the `skip_second_factor_auth?` method above
returns true.

If there are permission/security checks that the current user must pass in order to perform the 2fa-protected action, it’s important to run the checks in all of the 3 methods of the action class and raise errors if the user doesn’t pass the checks.

Rendering a response to the client in the outcomes (1) and (2b) is a task for the controller action. The return value of the ‘run_second_factor!` method, which is an instance of `SecondFactor::AuthManagerResult`, can be used to know which outcome the auth manager has picked and render a different response based on the outcome.

The results object also has a ‘data` method that returns the return value of the hook/method of your action class. For example, if `second_factor_auth_required!` is called and it returns a hash object, you can get that hash object by calling the `data` method of the results object.

For a real example where the auth manager is used, please refer to:

  • The ‘lib/second_factor/actions` directory where all existing actions live.

  • ‘Admin::UsersController#grant_admin` controller action.

  • ‘SessionController#sso_provider` controller action.

Defined Under Namespace

Classes: SecondFactorRequired

Constant Summary collapse

MAX_CHALLENGE_AGE = 
5.minutes

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(guardian, action) ⇒ AuthManager

Returns a new instance of AuthManager.



147
148
149
150
151
152
153
 
# File 'lib/second_factor/auth_manager.rb', line 147

def initialize(guardian, action)
  @guardian = guardian
  @current_user = guardian.user
  @action = action
  @allowed_methods =
    Set.new([UserSecondFactor.methods[:totp], UserSecondFactor.methods[:security_key]]).freeze
end

Instance Attribute Details

#allowed_methods ⇒ Object (readonly)

Returns the value of attribute allowed_methods.



121
122
123
 
# File 'lib/second_factor/auth_manager.rb', line 121

def allowed_methods
  @allowed_methods
end

Class Method Details

.find_second_factor_challenge(nonce, secure_session) ⇒ Object 



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/second_factor/auth_manager.rb', line 123

def self.find_second_factor_challenge(nonce, secure_session)
  challenge_json = secure_session["current_second_factor_auth_challenge"]
  if challenge_json.blank?
    raise SecondFactor::BadChallenge.new(
            "second_factor_auth.challenge_not_found",
            status_code: 404,
          )
  end

  challenge = JSON.parse(challenge_json).deep_symbolize_keys
  if challenge[:nonce] != nonce
    raise SecondFactor::BadChallenge.new(
            "second_factor_auth.challenge_not_found",
            status_code: 404,
          )
  end

  generated_at = challenge[:generated_at]
  if generated_at < MAX_CHALLENGE_AGE.ago.to_i
    raise SecondFactor::BadChallenge.new("second_factor_auth.challenge_expired", status_code: 401)
  end
  challenge
end

Instance Method Details

#allow_backup_codes! ⇒ Object 



155
156
157
 
# File 'lib/second_factor/auth_manager.rb', line 155

def allow_backup_codes!
  add_method(UserSecondFactor.methods[:backup_codes])
end

#run!(request, params, secure_session) ⇒ Object 



159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/second_factor/auth_manager.rb', line 159

def run!(request, params, secure_session)
  if nonce = params[:second_factor_nonce].presence
    data = verify_second_factor_auth_completed(nonce, secure_session)
    create_result(:second_factor_auth_completed, data)
  elsif @action.skip_second_factor_auth?(params)
    data = @action.second_factor_auth_skipped!(params)
    create_result(:second_factor_auth_skipped, data)
  elsif !allowed_methods.any? { |m| @current_user.valid_second_factor_method_for_user?(m) }
    data = @action.no_second_factors_enabled!(params)
    create_result(:no_second_factor, data)
  else
    nonce = initiate_second_factor_auth(params, secure_session, request)
    raise SecondFactorRequired.new(nonce: nonce)
  end
end