thepaperpilot/forgejo
1
0
Fork 0
Code Issues Pull requests Releases Activity Actions

add mfa doc (#26654) (#26674)

Browse source 
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>
(cherry picked from commit 2f4de240c1)
This commit is contained in:
Giteabot 2023-08-23 09:57:01 +08:00 committed by Earl Warren
parent a98cb4d806
commit c1efe5b104
No known key found for this signature in database
GPG key ID: 0579CB2928A78A00
1 changed files with 35 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

35
docs/content/usage/multi-factor-authentication.en-us.md Normal file
View file

@ -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.