From 33964469b38e2b36b200b20fe3061371a5f5ab18 Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Fri, 18 Dec 2015 18:29:13 -0200
Subject: WIP require two factor authentication

---
 app/controllers/application_controller.rb          | 12 +++++
 .../profiles/two_factor_auths_controller.rb        |  2 +
 app/models/application_setting.rb                  | 59 ++++++++++++----------
 ...151218154042_add_tfa_to_application_settings.rb |  8 +++
 db/schema.rb                                       |  2 +
 spec/models/application_setting_spec.rb            |  1 +
 6 files changed, 58 insertions(+), 26 deletions(-)
 create mode 100644 db/migrate/20151218154042_add_tfa_to_application_settings.rb

diff --git a/app/controllers/application_controller.rb b/app/controllers/application_controller.rb
index 01e2e7b2f98..e15d83631b3 100644
--- a/app/controllers/application_controller.rb
+++ b/app/controllers/application_controller.rb
@@ -13,6 +13,7 @@ class ApplicationController < ActionController::Base
   before_action :validate_user_service_ticket!
   before_action :reject_blocked!
   before_action :check_password_expiration
+  before_action :check_tfa_requirement
   before_action :ldap_security_check
   before_action :default_headers
   before_action :add_gon_variables
@@ -223,6 +224,13 @@ class ApplicationController < ActionController::Base
     end
   end
 
+  def check_tfa_requirement
+    if two_factor_authentication_required? && current_user && !current_user.two_factor_enabled
+      redirect_to new_profile_two_factor_auth_path,
+                  alert: 'You must configure Two-Factor Authentication in your account'
+    end
+  end
+
   def ldap_security_check
     if current_user && current_user.requires_ldap_check?
       unless Gitlab::LDAP::Access.allowed?(current_user)
@@ -357,6 +365,10 @@ class ApplicationController < ActionController::Base
     current_application_settings.import_sources.include?('git')
   end
 
+  def two_factor_authentication_required?
+    current_application_settings.require_two_factor_authentication
+  end
+
   def redirect_to_home_page_url?
     # If user is not signed-in and tries to access root_path - redirect him to landing page
     # Don't redirect to the default URL to prevent endless redirections
diff --git a/app/controllers/profiles/two_factor_auths_controller.rb b/app/controllers/profiles/two_factor_auths_controller.rb
index e6b99be37fb..05c84fb720e 100644
--- a/app/controllers/profiles/two_factor_auths_controller.rb
+++ b/app/controllers/profiles/two_factor_auths_controller.rb
@@ -1,4 +1,6 @@
 class Profiles::TwoFactorAuthsController < Profiles::ApplicationController
+  skip_before_action :check_tfa_requirement
+
   def new
     unless current_user.otp_secret
       current_user.otp_secret = User.generate_otp_secret(32)
diff --git a/app/models/application_setting.rb b/app/models/application_setting.rb
index 724429e7558..7c107da116c 100644
--- a/app/models/application_setting.rb
+++ b/app/models/application_setting.rb
@@ -2,32 +2,34 @@
 #
 # Table name: application_settings
 #
-#  id                           :integer          not null, primary key
-#  default_projects_limit       :integer
-#  signup_enabled               :boolean
-#  signin_enabled               :boolean
-#  gravatar_enabled             :boolean
-#  sign_in_text                 :text
-#  created_at                   :datetime
-#  updated_at                   :datetime
-#  home_page_url                :string(255)
-#  default_branch_protection    :integer          default(2)
-#  twitter_sharing_enabled      :boolean          default(TRUE)
-#  restricted_visibility_levels :text
-#  version_check_enabled        :boolean          default(TRUE)
-#  max_attachment_size          :integer          default(10), not null
-#  default_project_visibility   :integer
-#  default_snippet_visibility   :integer
-#  restricted_signup_domains    :text
-#  user_oauth_applications      :boolean          default(TRUE)
-#  after_sign_out_path          :string(255)
-#  session_expire_delay         :integer          default(10080), not null
-#  import_sources               :text
-#  help_page_text               :text
-#  admin_notification_email     :string(255)
-#  shared_runners_enabled       :boolean          default(TRUE), not null
-#  max_artifacts_size           :integer          default(100), not null
-#  runners_registration_token   :string(255)
+#  id                                :integer          not null, primary key
+#  default_projects_limit            :integer
+#  signup_enabled                    :boolean
+#  signin_enabled                    :boolean
+#  gravatar_enabled                  :boolean
+#  sign_in_text                      :text
+#  created_at                        :datetime
+#  updated_at                        :datetime
+#  home_page_url                     :string(255)
+#  default_branch_protection         :integer          default(2)
+#  twitter_sharing_enabled           :boolean          default(TRUE)
+#  restricted_visibility_levels      :text
+#  version_check_enabled             :boolean          default(TRUE)
+#  max_attachment_size               :integer          default(10), not null
+#  default_project_visibility        :integer
+#  default_snippet_visibility        :integer
+#  restricted_signup_domains         :text
+#  user_oauth_applications           :boolean          default(TRUE)
+#  after_sign_out_path               :string(255)
+#  session_expire_delay              :integer          default(10080), not null
+#  import_sources                    :text
+#  help_page_text                    :text
+#  admin_notification_email          :string(255)
+#  shared_runners_enabled            :boolean          default(TRUE), not null
+#  max_artifacts_size                :integer          default(100), not null
+#  runners_registration_token        :string(255)
+#  require_two_factor_authentication :boolean          default(TRUE)
+#  two_factor_grace_period           :integer          default(48)
 #
 
 class ApplicationSetting < ActiveRecord::Base
@@ -58,6 +60,9 @@ class ApplicationSetting < ActiveRecord::Base
     allow_blank: true,
     email: true
 
+  validates :two_factor_grace_period,
+    numericality: { greater_than_or_equal_to: 0 }
+
   validates_each :restricted_visibility_levels do |record, attr, value|
     unless value.nil?
       value.each do |level|
@@ -112,6 +117,8 @@ class ApplicationSetting < ActiveRecord::Base
       import_sources: ['github','bitbucket','gitlab','gitorious','google_code','fogbugz','git'],
       shared_runners_enabled: Settings.gitlab_ci['shared_runners_enabled'],
       max_artifacts_size: Settings.artifacts['max_size'],
+      require_two_factor_authentication: false,
+      two_factor_grace_period: 48
     )
   end
 
diff --git a/db/migrate/20151218154042_add_tfa_to_application_settings.rb b/db/migrate/20151218154042_add_tfa_to_application_settings.rb
new file mode 100644
index 00000000000..dd95db775c5
--- /dev/null
+++ b/db/migrate/20151218154042_add_tfa_to_application_settings.rb
@@ -0,0 +1,8 @@
+class AddTfaToApplicationSettings < ActiveRecord::Migration
+  def change
+    change_table :application_settings do |t|
+      t.boolean :require_two_factor_authentication, default: false
+      t.integer :two_factor_grace_period, default: 48
+    end
+  end
+end
diff --git a/db/schema.rb b/db/schema.rb
index 0d53105b057..631979a7fd8 100644
--- a/db/schema.rb
+++ b/db/schema.rb
@@ -50,6 +50,8 @@ ActiveRecord::Schema.define(version: 20151224123230) do
     t.boolean  "shared_runners_enabled",       default: true,  null: false
     t.integer  "max_artifacts_size",           default: 100,   null: false
     t.string   "runners_registration_token"
+    t.boolean  "require_two_factor_authentication",             default: false
+    t.integer  "two_factor_grace_period",                       default: 48
   end
 
   create_table "audit_events", force: :cascade do |t|
diff --git a/spec/models/application_setting_spec.rb b/spec/models/application_setting_spec.rb
index 5f64453a35f..35d8220ae54 100644
--- a/spec/models/application_setting_spec.rb
+++ b/spec/models/application_setting_spec.rb
@@ -27,6 +27,7 @@
 #  admin_notification_email     :string(255)
 #  shared_runners_enabled       :boolean          default(TRUE), not null
 #  max_artifacts_size           :integer          default(100), not null
+#  runners_registration_token   :string(255)
 #
 
 require 'spec_helper'
-- 
cgit v1.2.3


From 31fb2b7702345fbf597c2cb17466567776433a56 Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Thu, 24 Dec 2015 00:02:52 -0200
Subject: Grace period support for TFA

---
 app/controllers/application_controller.rb            | 20 ++++++++++++++++++--
 .../profiles/two_factor_auths_controller.rb          | 14 +++++++++++++-
 app/helpers/auth_helper.rb                           | 12 ++++++++++++
 app/views/profiles/two_factor_auths/new.html.haml    |  1 +
 config/routes.rb                                     |  1 +
 .../20151221234414_add_tfa_additional_fields.rb      |  7 +++++++
 db/schema.rb                                         |  1 +
 7 files changed, 53 insertions(+), 3 deletions(-)
 create mode 100644 db/migrate/20151221234414_add_tfa_additional_fields.rb

diff --git a/app/controllers/application_controller.rb b/app/controllers/application_controller.rb
index e15d83631b3..978a269ca52 100644
--- a/app/controllers/application_controller.rb
+++ b/app/controllers/application_controller.rb
@@ -225,9 +225,13 @@ class ApplicationController < ActionController::Base
   end
 
   def check_tfa_requirement
-    if two_factor_authentication_required? && current_user && !current_user.two_factor_enabled
+    if two_factor_authentication_required? && current_user && !current_user.two_factor_enabled && !skip_two_factor?
+      grace_period_started = current_user.otp_grace_period_started_at
+      grace_period_deadline = grace_period_started + two_factor_grace_period.hours
+
+      deadline_text = "until #{l(grace_period_deadline)}" unless two_factor_grace_period_expired?(grace_period_started)
       redirect_to new_profile_two_factor_auth_path,
-                  alert: 'You must configure Two-Factor Authentication in your account'
+                  alert: "You must configure Two-Factor Authentication in your account #{deadline_text}"
     end
   end
 
@@ -369,6 +373,18 @@ class ApplicationController < ActionController::Base
     current_application_settings.require_two_factor_authentication
   end
 
+  def two_factor_grace_period
+    current_application_settings.two_factor_grace_period
+  end
+
+  def two_factor_grace_period_expired?(date)
+    date && (date + two_factor_grace_period.hours) < Time.current
+  end
+
+  def skip_two_factor?
+    session[:skip_tfa] && session[:skip_tfa] > Time.current
+  end
+
   def redirect_to_home_page_url?
     # If user is not signed-in and tries to access root_path - redirect him to landing page
     # Don't redirect to the default URL to prevent endless redirections
diff --git a/app/controllers/profiles/two_factor_auths_controller.rb b/app/controllers/profiles/two_factor_auths_controller.rb
index 05c84fb720e..49629e9894a 100644
--- a/app/controllers/profiles/two_factor_auths_controller.rb
+++ b/app/controllers/profiles/two_factor_auths_controller.rb
@@ -4,8 +4,11 @@ class Profiles::TwoFactorAuthsController < Profiles::ApplicationController
   def new
     unless current_user.otp_secret
       current_user.otp_secret = User.generate_otp_secret(32)
-      current_user.save!
     end
+    unless current_user.otp_grace_period_started_at && two_factor_grace_period
+      current_user.otp_grace_period_started_at = Time.current
+    end
+    current_user.save! if current_user.changed?
 
     @qr_code = build_qr_code
   end
@@ -36,6 +39,15 @@ class Profiles::TwoFactorAuthsController < Profiles::ApplicationController
     redirect_to profile_account_path
   end
 
+  def skip
+    if two_factor_grace_period_expired?(current_user.otp_grace_period_started_at)
+      redirect_to new_profile_two_factor_auth_path, alert: 'Cannot skip two factor authentication setup'
+    else
+      session[:skip_tfa] = current_user.otp_grace_period_started_at + two_factor_grace_period.hours
+      redirect_to root_path
+    end
+  end
+
   private
 
   def build_qr_code
diff --git a/app/helpers/auth_helper.rb b/app/helpers/auth_helper.rb
index 2c81ea1623c..0cfc0565e84 100644
--- a/app/helpers/auth_helper.rb
+++ b/app/helpers/auth_helper.rb
@@ -50,5 +50,17 @@ module AuthHelper
     current_user.identities.exists?(provider: provider.to_s)
   end
 
+  def two_factor_skippable?
+    current_application_settings.require_two_factor_authentication &&
+      !current_user.two_factor_enabled &&
+      current_application_settings.two_factor_grace_period &&
+      !two_factor_grace_period_expired?
+  end
+
+  def two_factor_grace_period_expired?
+    current_user.otp_grace_period_started_at &&
+      (current_user.otp_grace_period_started_at + current_application_settings.two_factor_grace_period.hours) < Time.current
+  end
+
   extend self
 end
diff --git a/app/views/profiles/two_factor_auths/new.html.haml b/app/views/profiles/two_factor_auths/new.html.haml
index 92dc58c10d7..1a5b6efce35 100644
--- a/app/views/profiles/two_factor_auths/new.html.haml
+++ b/app/views/profiles/two_factor_auths/new.html.haml
@@ -38,3 +38,4 @@
       = text_field_tag :pin_code, nil, class: "form-control", required: true, autofocus: true
   .form-actions
     = submit_tag 'Submit', class: 'btn btn-success'
+    = link_to 'Configure it later', skip_profile_two_factor_auth_path, :method => :patch,  class: 'btn btn-cancel' if two_factor_skippable?
diff --git a/config/routes.rb b/config/routes.rb
index b9242327de1..3e7d9f78710 100644
--- a/config/routes.rb
+++ b/config/routes.rb
@@ -297,6 +297,7 @@ Rails.application.routes.draw do
       resource :two_factor_auth, only: [:new, :create, :destroy] do
         member do
           post :codes
+          patch :skip
         end
       end
     end
diff --git a/db/migrate/20151221234414_add_tfa_additional_fields.rb b/db/migrate/20151221234414_add_tfa_additional_fields.rb
new file mode 100644
index 00000000000..c16df47932f
--- /dev/null
+++ b/db/migrate/20151221234414_add_tfa_additional_fields.rb
@@ -0,0 +1,7 @@
+class AddTfaAdditionalFields < ActiveRecord::Migration
+  def change
+    change_table :users do |t|
+      t.datetime :otp_grace_period_started_at, null: true
+    end
+  end
+end
diff --git a/db/schema.rb b/db/schema.rb
index 631979a7fd8..49fa258660d 100644
--- a/db/schema.rb
+++ b/db/schema.rb
@@ -840,6 +840,7 @@ ActiveRecord::Schema.define(version: 20151224123230) do
     t.integer  "layout",                     default: 0
     t.boolean  "hide_project_limit",         default: false
     t.string   "unlock_token"
+    t.datetime "otp_grace_period_started_at"
   end
 
   add_index "users", ["admin"], name: "index_users_on_admin", using: :btree
-- 
cgit v1.2.3


From b61a5bc20cbfcd8a2c914f19e8786a989bf69198 Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Thu, 24 Dec 2015 02:04:41 -0200
Subject: specs for forced two-factor authentication and grace period

simplified code and fixed stuffs
---
 app/controllers/application_controller.rb          | 10 ++---
 .../profiles/two_factor_auths_controller.rb        |  9 +++-
 spec/features/login_spec.rb                        | 52 ++++++++++++++++++++++
 3 files changed, 63 insertions(+), 8 deletions(-)

diff --git a/app/controllers/application_controller.rb b/app/controllers/application_controller.rb
index 978a269ca52..a945b38e35f 100644
--- a/app/controllers/application_controller.rb
+++ b/app/controllers/application_controller.rb
@@ -226,12 +226,7 @@ class ApplicationController < ActionController::Base
 
   def check_tfa_requirement
     if two_factor_authentication_required? && current_user && !current_user.two_factor_enabled && !skip_two_factor?
-      grace_period_started = current_user.otp_grace_period_started_at
-      grace_period_deadline = grace_period_started + two_factor_grace_period.hours
-
-      deadline_text = "until #{l(grace_period_deadline)}" unless two_factor_grace_period_expired?(grace_period_started)
-      redirect_to new_profile_two_factor_auth_path,
-                  alert: "You must configure Two-Factor Authentication in your account #{deadline_text}"
+      redirect_to new_profile_two_factor_auth_path
     end
   end
 
@@ -377,7 +372,8 @@ class ApplicationController < ActionController::Base
     current_application_settings.two_factor_grace_period
   end
 
-  def two_factor_grace_period_expired?(date)
+  def two_factor_grace_period_expired?
+    date = current_user.otp_grace_period_started_at
     date && (date + two_factor_grace_period.hours) < Time.current
   end
 
diff --git a/app/controllers/profiles/two_factor_auths_controller.rb b/app/controllers/profiles/two_factor_auths_controller.rb
index 49629e9894a..4f125eb7e05 100644
--- a/app/controllers/profiles/two_factor_auths_controller.rb
+++ b/app/controllers/profiles/two_factor_auths_controller.rb
@@ -10,6 +10,13 @@ class Profiles::TwoFactorAuthsController < Profiles::ApplicationController
     end
     current_user.save! if current_user.changed?
 
+    if two_factor_grace_period_expired?
+      flash.now[:alert] = 'You must configure Two-Factor Authentication in your account.'
+    else
+      grace_period_deadline = current_user.otp_grace_period_started_at + two_factor_grace_period.hours
+      flash.now[:alert] = "You must configure Two-Factor Authentication in your account until #{l(grace_period_deadline)}."
+    end
+
     @qr_code = build_qr_code
   end
 
@@ -40,7 +47,7 @@ class Profiles::TwoFactorAuthsController < Profiles::ApplicationController
   end
 
   def skip
-    if two_factor_grace_period_expired?(current_user.otp_grace_period_started_at)
+    if two_factor_grace_period_expired?
       redirect_to new_profile_two_factor_auth_path, alert: 'Cannot skip two factor authentication setup'
     else
       session[:skip_tfa] = current_user.otp_grace_period_started_at + two_factor_grace_period.hours
diff --git a/spec/features/login_spec.rb b/spec/features/login_spec.rb
index 922c76285d1..2451e56fe7c 100644
--- a/spec/features/login_spec.rb
+++ b/spec/features/login_spec.rb
@@ -98,4 +98,56 @@ feature 'Login', feature: true do
       expect(page).to have_content('Invalid login or password.')
     end
   end
+
+  describe 'with required two-factor authentication enabled' do
+    let(:user) { create(:user) }
+    before(:each) { stub_application_setting(require_two_factor_authentication: true) }
+
+    context 'with grace period defined' do
+      before(:each) do
+        stub_application_setting(two_factor_grace_period: 48)
+        login_with(user)
+      end
+
+      context 'within the grace period' do
+        it 'redirects to two-factor configuration page' do
+          expect(current_path).to eq new_profile_two_factor_auth_path
+          expect(page).to have_content('You must configure Two-Factor Authentication in your account until')
+        end
+
+        it 'two-factor configuration is skippable' do
+          expect(current_path).to eq new_profile_two_factor_auth_path
+
+          click_link 'Configure it later'
+          expect(current_path).to eq root_path
+        end
+      end
+
+      context 'after the grace period' do
+        let(:user) { create(:user, otp_grace_period_started_at: 9999.hours.ago) }
+
+        it 'redirects to two-factor configuration page' do
+          expect(current_path).to eq new_profile_two_factor_auth_path
+          expect(page).to have_content('You must configure Two-Factor Authentication in your account.')
+        end
+
+        it 'two-factor configuration is not skippable' do
+          expect(current_path).to eq new_profile_two_factor_auth_path
+          expect(page).not_to have_link('Configure it later')
+        end
+      end
+    end
+
+    context 'without grace pariod defined' do
+      before(:each) do
+        stub_application_setting(two_factor_grace_period: 0)
+        login_with(user)
+      end
+
+      it 'redirects to two-factor configuration page' do
+        expect(current_path).to eq new_profile_two_factor_auth_path
+        expect(page).to have_content('You must configure Two-Factor Authentication in your account.')
+      end
+    end
+  end
 end
-- 
cgit v1.2.3


From cde06999c939c6856a62cfdf764857d712d7a863 Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Thu, 24 Dec 2015 04:18:34 -0200
Subject: Add to application_settings forced TFA options

---
 app/controllers/admin/application_settings_controller.rb |  2 ++
 app/views/admin/application_settings/_form.html.haml     | 12 ++++++++++++
 2 files changed, 14 insertions(+)

diff --git a/app/controllers/admin/application_settings_controller.rb b/app/controllers/admin/application_settings_controller.rb
index 9dd16f8c735..2f4a855c118 100644
--- a/app/controllers/admin/application_settings_controller.rb
+++ b/app/controllers/admin/application_settings_controller.rb
@@ -49,6 +49,8 @@ class Admin::ApplicationSettingsController < Admin::ApplicationController
       :default_branch_protection,
       :signup_enabled,
       :signin_enabled,
+      :require_two_factor_authentication,
+      :two_factor_grace_period,
       :gravatar_enabled,
       :twitter_sharing_enabled,
       :sign_in_text,
diff --git a/app/views/admin/application_settings/_form.html.haml b/app/views/admin/application_settings/_form.html.haml
index 6c355366948..58f5c621f4a 100644
--- a/app/views/admin/application_settings/_form.html.haml
+++ b/app/views/admin/application_settings/_form.html.haml
@@ -104,6 +104,18 @@
           = f.label :signin_enabled do
             = f.check_box :signin_enabled
             Sign-in enabled
+    .form-group
+      = f.label :two_factor_authentication, 'Two-Factor authentication', class: 'control-label col-sm-2'
+      .col-sm-10
+        .checkbox
+          = f.label :require_two_factor_authentication do
+            = f.check_box :require_two_factor_authentication
+            Require all users to setup Two-Factor authentication
+    .form-group
+      = f.label :two_factor_authentication, 'Two-Factor grace period (hours)', class: 'control-label col-sm-2'
+      .col-sm-10
+        = f.number_field :two_factor_grace_period, min: 0, class: 'form-control', placeholder: '0'
+        .help-block Amount of time (in hours) that users are allowed to skip forced configuration of two-factor authentication
     .form-group
       = f.label :restricted_signup_domains, 'Restricted domains for sign-ups', class: 'control-label col-sm-2'
       .col-sm-10
-- 
cgit v1.2.3


From 6e3fb5024addf86d48c5723168f664d09d81a969 Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Thu, 24 Dec 2015 05:20:12 -0200
Subject: Updated CHANGELOG

---
 CHANGELOG | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG b/CHANGELOG
index 2e12889cb70..4591dc3013d 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -17,6 +17,7 @@ v 8.3.1
   - Fix Error 500 when doing a search in dashboard before visiting any project (Stan Hu)
   - Fix LDAP identity and user retrieval when special characters are used
   - Move Sidekiq-cron configuration to gitlab.yml
+  - Enable forcing Two-Factor authentication sitewide, with optional grace period
 
 v 8.3.0
   - Bump rack-attack to 4.3.1 for security fix (Stan Hu)
-- 
cgit v1.2.3


From 1249289f89feba725109ce769e685b07cf746e4b Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Thu, 24 Dec 2015 18:58:46 -0200
Subject: Fixed codestyle and added 2FA documentation

---
 app/controllers/application_controller.rb          |  4 +--
 .../profiles/two_factor_auths_controller.rb        |  4 ++-
 doc/security/README.md                             |  1 +
 doc/security/two_factor_authentication.md          | 38 ++++++++++++++++++++++
 4 files changed, 44 insertions(+), 3 deletions(-)
 create mode 100644 doc/security/two_factor_authentication.md

diff --git a/app/controllers/application_controller.rb b/app/controllers/application_controller.rb
index a945b38e35f..d9a37a4d45f 100644
--- a/app/controllers/application_controller.rb
+++ b/app/controllers/application_controller.rb
@@ -13,7 +13,7 @@ class ApplicationController < ActionController::Base
   before_action :validate_user_service_ticket!
   before_action :reject_blocked!
   before_action :check_password_expiration
-  before_action :check_tfa_requirement
+  before_action :check_2fa_requirement
   before_action :ldap_security_check
   before_action :default_headers
   before_action :add_gon_variables
@@ -224,7 +224,7 @@ class ApplicationController < ActionController::Base
     end
   end
 
-  def check_tfa_requirement
+  def check_2fa_requirement
     if two_factor_authentication_required? && current_user && !current_user.two_factor_enabled && !skip_two_factor?
       redirect_to new_profile_two_factor_auth_path
     end
diff --git a/app/controllers/profiles/two_factor_auths_controller.rb b/app/controllers/profiles/two_factor_auths_controller.rb
index 4f125eb7e05..6e91d9b4ad9 100644
--- a/app/controllers/profiles/two_factor_auths_controller.rb
+++ b/app/controllers/profiles/two_factor_auths_controller.rb
@@ -1,13 +1,15 @@
 class Profiles::TwoFactorAuthsController < Profiles::ApplicationController
-  skip_before_action :check_tfa_requirement
+  skip_before_action :check_2fa_requirement
 
   def new
     unless current_user.otp_secret
       current_user.otp_secret = User.generate_otp_secret(32)
     end
+
     unless current_user.otp_grace_period_started_at && two_factor_grace_period
       current_user.otp_grace_period_started_at = Time.current
     end
+
     current_user.save! if current_user.changed?
 
     if two_factor_grace_period_expired?
diff --git a/doc/security/README.md b/doc/security/README.md
index fba6013d9c1..384df570394 100644
--- a/doc/security/README.md
+++ b/doc/security/README.md
@@ -6,3 +6,4 @@
 - [Information exclusivity](information_exclusivity.md)
 - [Reset your root password](reset_root_password.md)
 - [User File Uploads](user_file_uploads.md)
+- [Enforce Two-Factor authentication](two_factor_authentication.md)
diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md
new file mode 100644
index 00000000000..4e25a1fdc3f
--- /dev/null
+++ b/doc/security/two_factor_authentication.md
@@ -0,0 +1,38 @@
+# Enforce Two-factor Authentication (2FA)
+
+Two-factor Authentication (2FA) provides an additional level of security to your
+users' GitLab account. Once enabled, in addition to supplying their username and
+password to login, they'll be prompted for a code generated by an application on
+their phone.
+
+You can read more about it here:
+[Two-factor Authentication (2FA)](doc/profile/two_factor_authentication.md)
+
+## Enabling 2FA
+
+Users on GitLab, can enable it without any admin's intervention. If you want to
+enforce everyone to setup 2FA, you can choose from two different ways:
+
+ 1. Enforce on next login
+ 2. Suggest on next login, but allow a grace period before enforcing.
+
+In the Admin area under **Settings** (`/admin/application_settings`), look for
+the "Sign-in Restrictions" area, where you can configure both.
+
+If you want 2FA enforcement to take effect on next login, change the grace
+period to `0`
+
+## Disabling 2FA for everyone
+
+There may be some special situations where you want to disable 2FA for everyone
+even when forced 2FA is disabled. There is a rake task for that:
+
+```
+# use this command if you've installed GitLab with the Omnibus package
+sudo gitlab-rake gitlab:two_factor:disable_for_all_users
+
+# if you've installed GitLab from source
+sudo -u git -H bundle exec rake gitlab:two_factor:disable_for_all_users RAILS_ENV=production
+```
+
+**IMPORTANT: this is a permanent and irreversible action. Users will have to reactivate 2FA from scratch if they want to use it again.**
-- 
cgit v1.2.3