feat(auth): add disable-2fa command (#38275)

This PR adds the `gitea admin user disable-2fa` command to disable 2FA for a user When the only admin in the instance loses their 2FA credentials, this command can be used to disable 2FA, allowing them to log in and reset it. --------- Co-authored-by: Giteabot <teabot@gitea.io>
2026-08-02 11:27:06 +02:00 · 2026-07-01 12:33:16 +02:00
parent 77e221ffaf
commit 67a6bd7fc0
6 changed files with 244 additions and 20 deletions
@@ -18,6 +18,7 @@ func newUserCommand() *cli.Command {
 			microcmdUserDelete(),
 			newUserGenerateAccessTokenCommand(),
 			microcmdUserMustChangePassword(),
+			microcmdUserDisableTwoFactor(),
 		},
 	}
 }
@@ -0,0 +1,72 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	auth_model "gitea.dev/models/auth"
+	user_model "gitea.dev/models/user"
+	"gitea.dev/modules/setting"
+
+	"github.com/urfave/cli/v3"
+)
+
+func microcmdUserDisableTwoFactor() *cli.Command {
+	return &cli.Command{
+		Name:  "disable-2fa",
+		Usage: "Disable two-factor authentication for a user",
+		Flags: []cli.Flag{
+			&cli.StringFlag{
+				Name:    "username",
+				Aliases: []string{"u"},
+				Usage:   "Username of the user to disable 2FA for",
+			},
+			&cli.Int64Flag{
+				Name:  "id",
+				Usage: "ID of the user to disable 2FA for",
+			},
+		},
+		Action: runDisableTwoFactor,
+	}
+}
+
+func runDisableTwoFactor(ctx context.Context, c *cli.Command) error {
+	if !c.IsSet("id") && !c.IsSet("username") {
+		return errors.New("either --id or --username must be provided")
+	}
+
+	if !setting.IsInTesting {
+		if err := initDB(ctx); err != nil {
+			return err
+		}
+	}
+
+	var user *user_model.User
+	var err error
+	if c.IsSet("id") {
+		user, err = user_model.GetUserByID(ctx, c.Int64("id"))
+	} else {
+		user, err = user_model.GetUserByName(ctx, c.String("username"))
+	}
+	if err != nil {
+		return err
+	}
+
+	// When both selectors are given, make sure they refer to the same user.
+	if c.IsSet("id") && c.IsSet("username") && user.LowerName != strings.ToLower(strings.TrimSpace(c.String("username"))) {
+		return fmt.Errorf("the user with id %d is %q, which does not match the provided username %q", user.ID, user.Name, c.String("username"))
+	}
+
+	totp, webAuthn, err := auth_model.DisableTwoFactor(ctx, user.ID)
+	if err != nil {
+		return err
+	}
+
+	fmt.Printf("Disabled 2FA for user %q (removed %d TOTP and %d WebAuthn credential(s))\n", user.Name, totp, webAuthn)
+	return nil
+}
@@ -0,0 +1,119 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"io"
+	"strconv"
+	"testing"
+
+	auth_model "gitea.dev/models/auth"
+	"gitea.dev/models/db"
+	"gitea.dev/models/unittest"
+	user_model "gitea.dev/models/user"
+
+	"github.com/go-webauthn/webauthn/webauthn"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestDisableTwoFactorCommand(t *testing.T) {
+	ctx := t.Context()
+
+	defer func() {
+		require.NoError(t, db.TruncateBeans(t.Context(), &user_model.User{}, &auth_model.TwoFactor{}, &auth_model.WebAuthnCredential{}))
+	}()
+
+	t.Run("disable TOTP and WebAuthn", func(t *testing.T) {
+		require.NoError(t, microcmdUserCreate().Run(ctx, []string{"create", "--username", "tfuser", "--email", "tfuser@gitea.local", "--random-password"}))
+		user := unittest.AssertExistsAndLoadBean(t, &user_model.User{LowerName: "tfuser"})
+
+		// Enroll TOTP.
+		tf := &auth_model.TwoFactor{UID: user.ID}
+		require.NoError(t, tf.SetSecret("test-secret"))
+		_, err := tf.GenerateScratchToken()
+		require.NoError(t, err)
+		require.NoError(t, auth_model.NewTwoFactor(ctx, tf))
+
+		// Register a WebAuthn credential.
+		_, err = auth_model.CreateCredential(ctx, user.ID, "test-key", &webauthn.Credential{ID: []byte("test-cred-id")})
+		require.NoError(t, err)
+
+		has, err := auth_model.HasTwoFactorOrWebAuthn(ctx, user.ID)
+		require.NoError(t, err)
+		require.True(t, has)
+
+		require.NoError(t, microcmdUserDisableTwoFactor().Run(ctx, []string{"disable-2fa", "--username", "tfuser"}))
+
+		// Both factors must be gone afterwards.
+		has, err = auth_model.HasTwoFactorOrWebAuthn(ctx, user.ID)
+		require.NoError(t, err)
+		assert.False(t, has)
+	})
+
+	t.Run("disable by id", func(t *testing.T) {
+		require.NoError(t, microcmdUserCreate().Run(ctx, []string{"create", "--username", "iduser", "--email", "iduser@gitea.local", "--random-password"}))
+		user := unittest.AssertExistsAndLoadBean(t, &user_model.User{LowerName: "iduser"})
+
+		tf := &auth_model.TwoFactor{UID: user.ID}
+		require.NoError(t, tf.SetSecret("test-secret"))
+		require.NoError(t, auth_model.NewTwoFactor(ctx, tf))
+
+		require.NoError(t, microcmdUserDisableTwoFactor().Run(ctx, []string{"disable-2fa", "--id", strconv.FormatInt(user.ID, 10)}))
+
+		has, err := auth_model.HasTwoFactorOrWebAuthn(ctx, user.ID)
+		require.NoError(t, err)
+		assert.False(t, has)
+	})
+
+	t.Run("no enrollment is a no-op", func(t *testing.T) {
+		require.NoError(t, microcmdUserCreate().Run(ctx, []string{"create", "--username", "plainuser", "--email", "plainuser@gitea.local", "--random-password"}))
+		require.NoError(t, microcmdUserDisableTwoFactor().Run(ctx, []string{"disable-2fa", "--username", "plainuser"}))
+	})
+
+	t.Run("id and username must match when both given", func(t *testing.T) {
+		require.NoError(t, microcmdUserCreate().Run(ctx, []string{"create", "--username", "matchuser", "--email", "matchuser@gitea.local", "--random-password"}))
+		user := unittest.AssertExistsAndLoadBean(t, &user_model.User{LowerName: "matchuser"})
+		id := strconv.FormatInt(user.ID, 10)
+
+		// Matching id + username is accepted.
+		require.NoError(t, microcmdUserDisableTwoFactor().Run(ctx, []string{"disable-2fa", "--id", id, "--username", "matchuser"}))
+
+		// Mismatched id + username is rejected.
+		cmd := microcmdUserDisableTwoFactor()
+		cmd.Writer, cmd.ErrWriter = io.Discard, io.Discard
+		err := cmd.Run(ctx, []string{"disable-2fa", "--id", id, "--username", "someotheruser"})
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "does not match the provided username")
+	})
+
+	t.Run("failure cases", func(t *testing.T) {
+		testCases := []struct {
+			name        string
+			args        []string
+			expectedErr string
+		}{
+			{
+				name:        "user does not exist",
+				args:        []string{"disable-2fa", "--username", "nonexistentuser"},
+				expectedErr: "user does not exist",
+			},
+			{
+				name:        "neither id nor username",
+				args:        []string{"disable-2fa"},
+				expectedErr: "either --id or --username must be provided",
+			},
+		}
+
+		for _, tc := range testCases {
+			t.Run(tc.name, func(t *testing.T) {
+				cmd := microcmdUserDisableTwoFactor()
+				cmd.Writer, cmd.ErrWriter = io.Discard, io.Discard
+				err := cmd.Run(ctx, tc.args)
+				require.Error(t, err)
+				require.Contains(t, err.Error(), tc.expectedErr)
+			})
+		}
+	})
+}