feat: admin impersonates a user (#38614)

* fix #3631
* fix #21599

by the way, refactored the "profile avatar card" to simplify the code.

services/auth/auth.go

@@ -48,19 +48,8 @@ func handleSignIn(resp http.ResponseWriter, req *http.Request, sess SessionStore
 		sess = newSess
 	}
 
-	_ = sess.Delete("openid_verified_uri")
-	_ = sess.Delete("openid_signin_remember")
-	_ = sess.Delete("openid_determined_email")
-	_ = sess.Delete("openid_determined_username")
-	_ = sess.Delete("twofaUid")
-	_ = sess.Delete("twofaRemember")
-	_ = sess.Delete("webauthnAssertion")
-	_ = sess.Delete("linkAccount")
-	err = sess.Set("uid", user.ID)
-	if err != nil {
-		log.Error(fmt.Sprintf("Error setting session: %v", err))
-	}
-	err = sess.Set("uname", user.Name)
+	ClearSessionKeysForSignIn(sess)
+	err = sess.Set(session.KeyUID, user.ID)
 	if err != nil {
 		log.Error(fmt.Sprintf("Error setting session: %v", err))
 	}

services/auth/impersonate.go

@@ -0,0 +1,62 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+import (
+	"errors"
+	"fmt"
+
+	user_model "gitea.dev/models/user"
+	"gitea.dev/modules/session"
+)
+
+func ImpersonateUser(sess SessionStore, u *user_model.User) error {
+	if sess.Get(session.KeyImpersonatorData) != nil {
+		return errors.New("already impersonating a user")
+	}
+	// TODO: in the future, we need to process all sessions keys, but the session store doesn't have the ability to list keys
+	// So we need to refactor all "Session.Get" to use consts, then we can enumerate the pre-defined keys.
+	backupKeys := []string{session.KeyUID, session.KeyUserHasTwoFactorAuth}
+	backup := map[string]any{}
+	for _, key := range backupKeys {
+		v := sess.Get(key)
+		if v != nil {
+			backup[key] = v
+		}
+	}
+	err := sess.Set(session.KeyImpersonatorData, backup)
+	if err != nil {
+		return fmt.Errorf("set impersonator data: %w", err)
+	}
+
+	ClearSessionKeysForSignIn(sess)
+	data := map[string]any{}
+	data[session.KeyUID] = u.ID
+	data[session.KeyUserHasTwoFactorAuth] = true // since we are impersonating, we don't want to require 2FA for the impersonated user
+	for k, v := range data {
+		if err = sess.Set(k, v); err != nil {
+			return fmt.Errorf("set session data: %w", err)
+		}
+	}
+	return sess.Release()
+}
+
+func ExitImpersonatedUser(sess SessionStore) (bool, error) {
+	impersonatorData, ok := sess.Get(session.KeyImpersonatorData).(map[string]any)
+	if !ok {
+		return false, nil
+	}
+	err := sess.Delete(session.KeyImpersonatorData)
+	if err != nil {
+		return false, fmt.Errorf("delete impersonator data: %w", err)
+	}
+
+	ClearSessionKeysForSignIn(sess)
+	for k, v := range impersonatorData {
+		if err = sess.Set(k, v); err != nil {
+			return false, fmt.Errorf("set impersonator data: %w", err)
+		}
+	}
+	return true, sess.Release()
+}

services/auth/reverseproxy.go

@@ -11,6 +11,7 @@ import (
 	user_model "gitea.dev/models/user"
 	"gitea.dev/modules/log"
 	"gitea.dev/modules/optional"
+	"gitea.dev/modules/session"
 	"gitea.dev/modules/setting"
 
 	gouuid "github.com/google/uuid"
@@ -117,8 +118,9 @@ func (r *ReverseProxy) Verify(req *http.Request, w http.ResponseWriter, store Da
 		}
 	}
 
-	if r.CreateSession {
-		if sess != nil && (sess.Get("uid") == nil || sess.Get("uid").(int64) != user.ID) {
+	if r.CreateSession && sess != nil {
+		sessionUID, ok := sess.Get(session.KeyUID).(int64)
+		if !ok || sessionUID != user.ID {
 			handleSignIn(w, req, sess, user)
 		}
 	}

services/auth/session.go

@@ -8,6 +8,7 @@ import (
 
 	user_model "gitea.dev/models/user"
 	"gitea.dev/modules/log"
+	"gitea.dev/modules/session"
 )
 
 // Ensure the struct implements the interface.
@@ -32,20 +33,14 @@ func (s *Session) Verify(req *http.Request, w http.ResponseWriter, store DataSto
 		return nil, nil //nolint:nilnil // the auth method is not applicable
 	}
 
-	// Get user ID
-	uid := sess.Get("uid")
-	if uid == nil {
-		return nil, nil //nolint:nilnil // the auth method is not applicable
-	}
-	log.Trace("Session Authorization: Found user[%d]", uid)
-
-	id, ok := uid.(int64)
+	// Get session user ID
+	uid, ok := sess.Get(session.KeyUID).(int64)
 	if !ok {
 		return nil, nil //nolint:nilnil // the auth method is not applicable
 	}
 
 	// Get user object
-	user, err := user_model.GetUserByID(req.Context(), id)
+	user, err := user_model.GetUserByID(req.Context(), uid)
 	if err != nil {
 		if !user_model.IsErrUserNotExist(err) {
 			log.Error("GetUserByID: %v", err)
@@ -58,3 +53,15 @@ func (s *Session) Verify(req *http.Request, w http.ResponseWriter, store DataSto
 	log.Trace("Session Authorization: Logged in user %-v", user)
 	return user, nil
 }
+
+func ClearSessionKeysForSignIn(sess SessionStore) {
+	_ = sess.Delete("openid_verified_uri")
+	_ = sess.Delete("openid_signin_remember")
+	_ = sess.Delete("openid_determined_email")
+	_ = sess.Delete("openid_determined_username")
+	_ = sess.Delete("twofaUid")
+	_ = sess.Delete("twofaRemember")
+	_ = sess.Delete("webauthnAssertion")
+	_ = sess.Delete("linkAccount")
+	_ = sess.Delete("linkAccountData")
+}