add mfa doc (#26654) (#26674)

Backport #26654 by @lunny

copy and modified from #14572

> Whilst debating enforcing MFA within our team, I realised there isn't
a lot of context to the side effects of enabling it. Most of us use Git
over HTTP and would need to add a token.

I plan to add another PR that adds a sentence to the UI about needing to
generate a token when enabling MFA if HTTP is to be used.

Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: techknowlogick <techknowlogick@gitea.io>
Co-authored-by: silverwind <me@silverwind.io>

diff --git a/docs/content/usage/multi-factor-authentication.en-us.md b/docs/content/usage/multi-factor-authentication.en-us.md
new file mode 100644 (file)
index 0000000..16b57b7
--- /dev/null
+++ b/docs/content/usage/multi-factor-authentication.en-us.md
@@ -0,0 +1,35 @@
+---
+date: "2023-08-22T14:21:00+08:00"
+title: "Usage: Multi-factor Authentication (MFA)"
+slug: "multi-factor-authentication"
+weight: 15
+toc: false
+draft: false
+menu:
+  sidebar:
+    parent: "usage"
+    name: "Multi-factor Authentication (MFA)"
+    weight: 15
+    identifier: "multi-factor-authentication"
+---
+
+# Multi-factor Authentication (MFA)
+
+Multi-factor Authentication (also referred to as MFA or 2FA) enhances security by requiring a time-sensitive set of credentials in addition to a password.
+If a password were later to be compromised, logging into Gitea will not be possible without the additional credentials and the account would remain secure.
+Gitea supports both TOTP (Time-based One-Time Password) tokens and FIDO-based hardware keys using the Webauthn API.
+
+MFA can be configured within the "Security" tab of the user settings page.
+
+## MFA Considerations
+
+Enabling MFA on a user does affect how the Git HTTP protocol can be used with the Git CLI.
+This interface does not support MFA, and trying to use a password normally will no longer be possible whilst MFA is enabled.
+If SSH is not an option for Git operations, an access token can be generated within the "Applications" tab of the user settings page.
+This access token can be used as if it were a password in order to allow the Git CLI to function over HTTP.
+
+> **Warning** - By its very nature, an access token sidesteps the security benefits of MFA.
+> It must be kept secure and should only be used as a last resort.
+
+The Gitea API supports providing the relevant TOTP password in the `X-Gitea-OTP` header, as described in [API Usage](development/api-usage.md).
+This should be used instead of an access token where possible.