From 3b91b2d6b12b9c9c18406f484775925bbd557618 Mon Sep 17 00:00:00 2001 From: Lunny Xiao <xiaolunwen@gmail.com> Date: Wed, 23 Aug 2023 09:56:11 +0800 Subject: [PATCH] add mfa doc (#26654) 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: techknowlogick <techknowlogick@gitea.io> Co-authored-by: silverwind <me@silverwind.io> --- .../multi-factor-authentication.en-us.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 docs/content/usage/multi-factor-authentication.en-us.md 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 index 000000000000..16b57b7bdca7 --- /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.