Nginx UI安全特性与权限管理
【免费下载链接】nginx-ui 
项目地址: https://gitcode.com/gh_mirrors/ngi/nginx-ui
Nginx UI提供了全面的安全特性和完善的权限管理系统，包括双因素认证(2FA)、WebAuthn与Passkey支持、基于角色的访问控制(RBAC)以及安全审计与日志监控功能。系统采用模块化设计，支持TOTP、Passkey和恢复码等多种认证方式，确保用户登录安全。权限管理系统通过精细的用户角色划分和数据加密存储，为多用户环境提供可靠的访问控制。安全审计功能则通过实时日志分析和事件监控，帮助管理员及时发现和响应安全威胁。
双因素认证(2FA)实现机制
Nginx UI提供了全面的双因素认证(2FA)解决方案，支持基于时间的一次性密码(TOTP)和Passkey两种认证方式，为用户登录提供额外的安全层。该实现遵循行业最佳实践，确保系统安全性和用户体验的平衡。
核心架构设计
Nginx UI的2FA系统采用模块化设计，主要包含以下核心组件：
TOTP认证实现
密钥生成与存储
TOTP密钥生成采用RFC 6238标准，使用SHA1算法和30秒时间窗口：
func GenerateTOTP(c *gin.Context) {
issuer := fmt.Sprintf("Nginx UI %s", settings.NodeSettings.Name)
otpOpts := totp.GenerateOpts{
Issuer: issuer,
AccountName: u.Name,
Period: 30, // 30秒时间窗口
Digits: otp.DigitsSix, // 6位数字
Algorithm: otp.AlgorithmSHA1, // SHA1算法
}
otpKey, _ := totp.Generate(otpOpts)
// 返回密钥和二维码URL
}
生成的TOTP密钥使用AES加密后存储在数据库中：
ciphertext, err := crypto.AesEncrypt([]byte(twoFA.Secret))
_, err = u.Where(u.ID.Eq(cUser.ID)).Update(u.OTPSecret, ciphertext)
验证流程
TOTP验证过程包含严格的错误处理和安全性检查：
func VerifyOTP(user *model.User, otp, recoveryCode string) error {
if otp != "" {
// 解密存储的密钥
decrypted, err := crypto.AesDecrypt(user.OTPSecret)
if err != nil {
return err
}
// 验证TOTP代码
if ok := totp.Validate(otp, string(decrypted)); !ok {
return ErrOTPCode
}
} else {
// 恢复码验证逻辑
// ...
}
return nil
}
恢复码系统
恢复码生成机制
Nginx UI为每个启用2FA的用户生成16个唯一的恢复码，格式为xxxxx-xxxxx：
func generateRecoveryCode() string {
return fmt.Sprintf("%05x-%05x", rand.Intn(0x100000), rand.Intn(0x100000))
}
func generateRecoveryCodes(count int) []*model.RecoveryCode {
recoveryCodes := make([]*model.RecoveryCode, count)
for i := 0; i < count; i++ {
recoveryCodes[i] = &model.RecoveryCode{
Code: generateRecoveryCode(),
}
}
return recoveryCodes
}
恢复码使用跟踪
系统会跟踪恢复码的使用状态，当所有恢复码都被使用时发出警告：
usedCount := 0
verified := false
for _, code := range user.RecoveryCodes.Codes {
if code.Code == recoveryCode && code.UsedTime == nil {
t := time.Now().Unix()
code.UsedTime = &t
verified = true
}
if code.UsedTime != nil {
usedCount++
}
}
if verified && usedCount == len(user.RecoveryCodes.Codes) {
notification.Warning("All Recovery Codes Have Been Used",
"Please generate new recovery codes immediately to prevent lockout.", nil)
}
安全会话管理
会话ID生成与验证
安全会话使用UUID生成唯一的会话标识符，并设置5分钟的有效期：
func SetSecureSessionID(userId uint64) (sessionId string) {
sessionId = uuid.NewString()
cache.Set(secureSessionIDCacheKey(sessionId), userId, 5*time.Minute)
return
}
func VerifySecureSessionID(sessionId string, userId uint64) bool {
if v, ok := cache.Get(secureSessionIDCacheKey(sessionId)); ok {
if v.(uint64) == userId {
return true
}
}
return false
}
缓存键设计
缓存键采用前缀加会话ID的模式，防止键冲突：
func secureSessionIDCacheKey(sessionId string) string {
return fmt.Sprintf("2fa_secure_session:_%s", sessionId)
}
API端点设计
Nginx UI提供了完整的2FA RESTful API接口：
| 端点 | 方法 | 功能描述 | 认证要求 |
|---|---|---|---|
/2fa_status | GET | 获取2FA状态信息 | 无 |
/2fa_secure_session/status | GET | 检查安全会话状态 | 无 |
/2fa_secure_session/otp | POST | 通过OTP启动安全会话 | 无 |
/otp_secret | GET | 生成TOTP密钥 | 无 |
/otp_enroll | POST | 启用TOTP认证 | 无 |
/otp_reset | GET | 重置TOTP设置 | 安全会话 |
/recovery_codes | GET | 查看恢复码 | 安全会话 |
/recovery_codes_generate | GET | 生成新恢复码 | 安全会话 |
错误处理机制
系统定义了详细的错误代码和消息：
| 错误代码 | 错误消息 | 描述 |
|---|---|---|
| 40304 | Invalid otp code | TOTP验证码错误 |
| 40305 | Invalid recovery code | 恢复码错误 |
| 40306 | Legacy recovery code not allowed | 传统恢复码不允许 |
| 50001 | User not enabled otp as 2fa | 用户未启用OTP |
| 50002 | OTP or recovery code empty | 验证码或恢复码为空 |
前端集成
前端通过统一的API接口与后端交互，提供流畅的用户体验：
// 2FA状态检查
const status = await twoFA.status()
// 启动安全会话
const session = await twoFA.start_secure_session_by_otp(passcode, recovery_code)
// 生成TOTP密钥
const secret = await otp.generate_secret()
// 启用TOTP
const recoveryCodes = await otp.enroll_otp(secret, passcode)
安全性特性
- 密钥加密存储：所有TOTP密钥使用AES加密存储在数据库中
- 会话超时：安全会话5分钟自动过期，防止会话劫持
- 恢复码保护：恢复码使用JSON AES序列化器加密存储
- 使用跟踪：记录恢复码使用时间和次数，提供安全审计
- 防暴力攻击：集成IP封禁机制，防止认证暴力尝试
Nginx UI的双因素认证实现不仅提供了强大的安全保障，还确保了良好的用户体验，支持多种认证方式和灵活的恢复机制，是现代Web应用安全认证的典范实现。
WebAuthn与Passkey支持
Nginx UI从v2.0.0-beta.34版本开始全面支持WebAuthn标准和Passkey无密码认证技术，为用户提供了更加安全、便捷的身份验证方式。WebAuthn是一种现代化的Web认证标准，允许用户使用生物识别技术（如指纹、面部识别）、移动设备或FIDO安全密钥进行登录，彻底摆脱传统密码的束缚。
WebAuthn技术架构与实现原理
Nginx UI采用Go语言的go-webauthn库实现WebAuthn协议支持，后端架构基于标准的WebAuthn注册和认证流程：
Passkey数据模型与存储结构
Nginx UI使用专门的数据模型来存储Passkey凭证信息：
type Passkey struct {
Model
Name string `json:"name"`
UserID uint64 `json:"user_id"`
RawID string `json:"raw_id"`
Credential *webauthn.Credential `json:"-" gorm:"serializer:json"`
LastUsedAt int64 `json:"last_used_at" gorm:"default:0"`
}
每个Passkey包含以下关键信息：
- Name: 用户自定义的Passkey名称，用于识别不同的认证设备
- UserID: 关联的用户ID，确保凭证与用户绑定
- RawID: 凭证的唯一标识符
- Credential: WebAuthn凭证对象，包含公钥和认证器信息
- LastUsedAt: 最后使用时间戳，用于审计和安全监控
WebAuthn配置要求与安全设置
为确保最高级别的安全性，Nginx UI要求必须通过配置文件手动设置WebAuthn参数，禁止通过Web界面配置：
配置文件示例 (app.ini):
[webauthn]
RPDisplayName = Nginx UI Management
RPID = your-domain.com
RPOrigins = https://your-domain.com,https://admin.your-domain.com
配置参数说明：
| 参数 | 类型 | 必需 | 描述 | 示例值 |
|---|---|---|---|---|
| RPDisplayName | string | 是 | 依赖方显示名称，在用户注册时显示 | Nginx UI |
| RPID | string | 是 | 依赖方ID，通常使用域名 | localhost 或 your-domain.com |
| RPOrigins | []string | 是 | 允许的源地址列表，支持多个URL | http://localhost:3002,https://your-domain.com |
环境变量配置方式：
export NGINX_UI_WEBAUTHN_RP_DISPLAY_NAME="Nginx UI"
export NGINX_UI_WEBAUTHN_RPID="localhost"
export NGINX_UI_WEBAUTHN_RP_ORIGINS="http://localhost:3002"
Passkey注册与认证流程
1. Passkey注册流程
用户可以通过以下步骤注册新的Passkey：
- 进入"设置 > 认证"页面
- 点击"添加Passkey"按钮
- 输入Passkey名称（如"MacBook Touch ID"）
- 浏览器弹出WebAuthn对话框
- 选择认证方式（指纹、面部识别、安全密钥等）
- 完成生物识别验证
- 系统保存Passkey凭证
2. Passkey登录流程
双因素认证(2FA)集成
Nginx UI的Passkey支持与现有的双因素认证系统完美集成：
自动2FA机制：
- 当用户使用Passkey登录时，所有后续需要2FA的操作将自动使用Passkey
- 无需在2FA对话框中手动选择认证方式
- 系统自动识别并优先使用Passkey进行验证
2FA优先级逻辑：
安全特性与最佳实践
1. 会话管理安全
- Passkey会话使用30秒超时机制，防止重放攻击
- 每个认证请求生成唯一的Session ID
- 支持多因素认证回退机制
2. 浏览器兼容性要求
由于安全策略限制，Passkey在使用时需注意：
- HTTPS要求: 生产环境必须使用HTTPS，localhost除外
- 现代浏览器: 需要支持WebAuthn标准的浏览器
- 平台认证器: 支持Windows Hello、Touch ID、Face ID等
3. 凭证管理功能
用户可以在认证设置页面：
- 查看所有已注册的Passkey设备
- 重命名Passkey以便识别
- 删除不再使用的Passkey凭证
- 监控最后使用时间
故障排除与常见问题
配置验证检查
在启用WebAuthn前，系统会验证以下配置：
func Enabled() bool {
options := settings.WebAuthnSettings
if options.RPDisplayName == "" || options.RPID == "" || len(options.RPOrigins) == 0 {
return false
}
return true
}
常见错误处理
| 错误代码 | 错误信息 | 解决方案 |
|---|---|---|
| 50000 | WebAuthn settings are not configured | 检查app.ini配置文件中的webauthn章节 |
| - | 浏览器不支持WebAuthn | 升级浏览器或使用支持的设备 |
| - | 非HTTPS环境限制 | 生产环境必须配置SSL证书 |
性能优化与扩展性
Nginx UI的WebAuthn实现经过优化：
- 内存缓存: 使用高效的会话缓存机制，减少数据库压力
- 并发处理: 支持高并发认证请求，适合企业级部署
- 可扩展性: 架构设计支持未来添加更多认证器类型
通过WebAuthn和Passkey支持，Nginx UI为用户提供了现代化、无密码的安全认证体验，同时保持了与传统认证方式的兼容性，确保平滑的迁移路径和灵活的安全策略配置。
用户权限与角色管理系统
Nginx UI的用户权限与角色管理系统采用了基于角色的访问控制（RBAC）模型，通过精心设计的用户管理架构和安全机制，为多用户环境提供了完善的权限管理解决方案。系统支持用户账户管理、身份验证、双因素认证以及细粒度的权限控制，确保只有授权用户才能访问和操作Nginx配置。
用户模型与数据结构
Nginx UI的用户系统基于GORM ORM框架构建，用户模型定义了完整的用户属性和安全特性：
type User struct {
Model
Name string `json:"name" cosy:"add:max=20;update:omitempty,max=20;list:fussy;db_unique"`
Password string `json:"-" cosy:"json:password;add:required,max=20;update:omitempty,max=20"`
Status bool `json:"status" gorm:"default:1"`
OTPSecret []byte `json:"-" gorm:"type:blob"`
RecoveryCodes RecoveryCodes `json:"-" gorm:"serializer:json[aes]"`
EnabledTwoFA bool `json:"enabled_2fa" gorm:"-"`
Language string `json:"language" gorm:"default:en"`
}
用户数据表结构包含以下关键字段：
| 字段名 | 类型 | 描述 | 约束 |
|---|---|---|---|
| id | uint64 | 用户唯一标识符 | 主键，自增 |
| name | varchar(20) | 用户名 | 唯一，最大20字符 |
| password | text | 加密密码 | bcrypt加密存储 |
| status | boolean | 用户状态 | 默认启用(true) |
| otp_secret | blob | OTP密钥 | 二进制存储 |
| recovery_codes | text | 恢复代码 | AES加密JSON序列化 |
| language | varchar(10) | 用户语言偏好 | 默认 |
【免费下载链接】nginx-ui 项目地址: https://gitcode.com/gh_mirrors/ngi/nginx-ui
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
