From d8b55db77177e317665e37b49e47518b2d8b4238 Mon Sep 17 00:00:00 2001 From: Lunny Xiao Date: Tue, 22 Aug 2023 14:26:33 +0800 Subject: [PATCH 1/2] add mfa doc --- .../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 0000000000000..242ffafaae90f --- /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, Gitea would still not allow a successful login and the account would remain secure. +Gitea supports both TOTP (Time-based One-Time Password) tokens and FIDO-based hardware keys. + +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. From 39b11afea4dcdcbcc4f4d433d4f63bf36affd5f4 Mon Sep 17 00:00:00 2001 From: techknowlogick Date: Tue, 22 Aug 2023 21:32:16 -0400 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: silverwind --- docs/content/usage/multi-factor-authentication.en-us.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/usage/multi-factor-authentication.en-us.md b/docs/content/usage/multi-factor-authentication.en-us.md index 242ffafaae90f..16b57b7bdca74 100644 --- a/docs/content/usage/multi-factor-authentication.en-us.md +++ b/docs/content/usage/multi-factor-authentication.en-us.md @@ -16,8 +16,8 @@ menu: # 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, Gitea would still not allow a successful login and the account would remain secure. -Gitea supports both TOTP (Time-based One-Time Password) tokens and FIDO-based hardware keys. +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.