Documentation
¶
Overview ¶
Package mfa 提供了多因素认证(MFA)的功能支持。
MFA是一种安全认证方法,要求用户提供不同类型的身份验证因素进行身份验证,以提高安全性。 本包提供了一个灵活的MFA框架,支持多种MFA方法,包括TOTP(基于时间的一次性密码)。
主要组件:
- MFAProvider: MFA提供者接口,定义了MFA方法的基本操作。
- TOTPProvider: 实现了基于时间的一次性密码(TOTP)的MFA提供者。
- MFARepository: MFA存储接口,用于存储用户的MFA配置。
- InMemoryMFARepository: 内存实现的MFA存储,适用于开发和测试环境。
- RedisMFARepository: 基于Redis的MFA存储实现,适用于生产环境。
- MFAAuthenticator: 多因素认证器,整合基础认证和MFA认证。
使用示例:
// 创建TOTP提供者
totpProvider := mfa.NewTOTPProvider(repository, "MyApp", 1)
// 创建MFA认证器
mfaAuth := mfa.NewMFAAuthenticator(mfa.MFAAuthenticatorConfig{
BaseAuthenticator: baseAuth,
Providers: []mfa.MFAProvider{totpProvider},
Repository: repository,
ForceMFA: false,
})
// 第一阶段认证
result, err := mfaAuth.PreAuthenticate(ctx, credential)
if err != nil {
// 处理错误
}
// 检查是否需要MFA
if result.RequireMFA {
// 第二阶段认证
valid, err := mfaAuth.CompleteMFA(ctx, userID, mfa.MFATypeTOTP, code)
// ...
}
Redis存储示例:
// 创建Redis MFA仓库
mfaRepo, err := mfa.NewRedisMFARepository(mfa.RedisMFARepositoryConfig{
Client: redisClient, // 实现了RedisMFAClient接口的客户端
KeyPrefix: "mfa:", // 键前缀
Expiration: time.Hour * 24 * 365, // 数据过期时间
})
TOTP支持: 本包提供了完整的TOTP实现,符合RFC 6238标准,支持:
- 生成随机密钥
- 生成和验证TOTP码
- 生成二维码URI
- 可配置的算法、位数、周期等参数
MFA设置流程: 1. 调用SetupMFA获取初始设置信息 2. 用户配置认证器应用(如Google Authenticator) 3. 用户输入验证码,调用SetupMFA进行验证 4. 验证成功,MFA设置完成
MFA认证流程: 1. 调用PreAuthenticate进行基础认证 2. 如果RequireMFA为true,引导用户使用认证器生成验证码 3. 调用CompleteMFA验证用户提供的验证码 4. 验证成功,认证完成
持久化存储: 框架支持两种MFA数据存储方式:
- InMemoryMFARepository: 内存存储,适用于开发和测试环境
- RedisMFARepository: Redis存储,适用于生产环境,提供持久化和集群支持
Index ¶
- Constants
- Variables
- func GenerateSecret(length int) (string, error)
- type AuthenticationResult
- type InMemoryMFARepository
- func (r *InMemoryMFARepository) DisableUserMFA(ctx context.Context, userID string, mfaType MFAType) error
- func (r *InMemoryMFARepository) GetUserMFA(ctx context.Context, userID string, mfaType MFAType) (map[string]string, error)
- func (r *InMemoryMFARepository) ListUserMFA(ctx context.Context, userID string) ([]MFAType, error)
- func (r *InMemoryMFARepository) SetUserMFA(ctx context.Context, userID string, mfaType MFAType, data map[string]string) error
- type MFAAuthenticator
- func (a *MFAAuthenticator) Authenticate(ctx context.Context, credential auth.Credential) (*auth.User, error)
- func (a *MFAAuthenticator) CompleteMFA(ctx context.Context, userID string, mfaType MFAType, code string) (bool, error)
- func (a *MFAAuthenticator) DisableMFA(ctx context.Context, userID string, mfaType MFAType) error
- func (a *MFAAuthenticator) PreAuthenticate(ctx context.Context, credential auth.Credential) (*AuthenticationResult, error)
- func (a *MFAAuthenticator) SetupMFA(ctx context.Context, userID string, mfaType MFAType, params map[string]string) (map[string]string, error)
- type MFAAuthenticatorConfig
- type MFAProvider
- type MFARepository
- type MFAType
- type QRCodeGenerator
- type RedisMFARepository
- func (r *RedisMFARepository) DisableUserMFA(ctx context.Context, userID string, mfaType MFAType) error
- func (r *RedisMFARepository) GetUserMFA(ctx context.Context, userID string, mfaType MFAType) (map[string]string, error)
- func (r *RedisMFARepository) ListUserMFA(ctx context.Context, userID string) ([]MFAType, error)
- func (r *RedisMFARepository) SetUserMFA(ctx context.Context, userID string, mfaType MFAType, data map[string]string) error
- type RedisMFARepositoryConfig
- type TOTP
- func (t *TOTP) GenerateCode() (string, error)
- func (t *TOTP) GenerateCodeAt(at time.Time) (string, error)
- func (t *TOTP) GenerateWithOffset(offset int) (string, error)
- func (t *TOTP) GetSecret() string
- func (t *TOTP) GetURI() string
- func (t *TOTP) ValidateCode(code string) bool
- func (t *TOTP) ValidateCodeWithWindow(code string, window int) bool
- type TOTPConfig
- type TOTPProvider
- func (p *TOTPProvider) Disable(ctx context.Context, userID string) error
- func (p *TOTPProvider) GenerateChallenge(ctx context.Context, userID string) (string, error)
- func (p *TOTPProvider) ProviderType() MFAType
- func (p *TOTPProvider) Setup(ctx context.Context, userID string, params map[string]string) (map[string]string, error)
- func (p *TOTPProvider) VerifyChallenge(ctx context.Context, userID string, response string) (bool, error)
Constants ¶
const ( // DefaultPeriod 默认时间步长(秒) DefaultPeriod = 30 // DefaultDigits 默认OTP位数 DefaultDigits = 6 // DefaultAlgorithm 默认算法 DefaultAlgorithm = "SHA1" )
Variables ¶
Functions ¶
Types ¶
type AuthenticationResult ¶
type AuthenticationResult struct {
// 用户信息
User *auth.User
// 是否需要MFA
RequireMFA bool
// 可用的MFA类型
AvailableMFATypes []MFAType
}
AuthenticationResult 认证结果
type InMemoryMFARepository ¶
type InMemoryMFARepository struct {
// contains filtered or unexported fields
}
InMemoryMFARepository 内存MFA仓库实现
func NewInMemoryMFARepository ¶
func NewInMemoryMFARepository() *InMemoryMFARepository
NewInMemoryMFARepository 创建内存MFA仓库
func (*InMemoryMFARepository) DisableUserMFA ¶
func (r *InMemoryMFARepository) DisableUserMFA(ctx context.Context, userID string, mfaType MFAType) error
DisableUserMFA 实现MFARepository.DisableUserMFA
func (*InMemoryMFARepository) GetUserMFA ¶
func (r *InMemoryMFARepository) GetUserMFA(ctx context.Context, userID string, mfaType MFAType) (map[string]string, error)
GetUserMFA 实现MFARepository.GetUserMFA
func (*InMemoryMFARepository) ListUserMFA ¶
ListUserMFA 实现MFARepository.ListUserMFA
func (*InMemoryMFARepository) SetUserMFA ¶
func (r *InMemoryMFARepository) SetUserMFA(ctx context.Context, userID string, mfaType MFAType, data map[string]string) error
SetUserMFA 实现MFARepository.SetUserMFA
type MFAAuthenticator ¶
type MFAAuthenticator struct {
// contains filtered or unexported fields
}
MFAAuthenticator 多因素认证器
func NewMFAAuthenticator ¶
func NewMFAAuthenticator(config MFAAuthenticatorConfig) *MFAAuthenticator
NewMFAAuthenticator 创建多因素认证器
func (*MFAAuthenticator) Authenticate ¶
func (a *MFAAuthenticator) Authenticate(ctx context.Context, credential auth.Credential) (*auth.User, error)
Authenticate 实现auth.Authenticator接口 注意:这个方法只会执行基础认证,不会进行MFA验证 对于需要MFA的场景,应该先调用PreAuthenticate,然后调用CompleteMFA
func (*MFAAuthenticator) CompleteMFA ¶
func (a *MFAAuthenticator) CompleteMFA(ctx context.Context, userID string, mfaType MFAType, code string) (bool, error)
CompleteMFA 完成MFA认证(第二因素)
func (*MFAAuthenticator) DisableMFA ¶
DisableMFA 禁用MFA
func (*MFAAuthenticator) PreAuthenticate ¶
func (a *MFAAuthenticator) PreAuthenticate(ctx context.Context, credential auth.Credential) (*AuthenticationResult, error)
PreAuthenticate 预认证(第一因素)
type MFAAuthenticatorConfig ¶
type MFAAuthenticatorConfig struct {
// 基础认证器
BaseAuthenticator auth.Authenticator
// MFA提供者列表
Providers []MFAProvider
// MFA仓库
Repository MFARepository
// 是否强制MFA
ForceMFA bool
}
MFAAuthenticatorConfig 多因素认证器配置
type MFAProvider ¶
type MFAProvider interface {
// ProviderType 提供者类型
ProviderType() MFAType
// GenerateChallenge 生成挑战
GenerateChallenge(ctx context.Context, userID string) (string, error)
// VerifyChallenge 验证挑战
VerifyChallenge(ctx context.Context, userID string, response string) (bool, error)
// Setup 设置MFA
Setup(ctx context.Context, userID string, params map[string]string) (map[string]string, error)
// Disable 禁用MFA
Disable(ctx context.Context, userID string) error
}
MFAProvider 多因素认证提供者
type MFARepository ¶
type MFARepository interface {
// GetUserMFA 获取用户MFA设置
GetUserMFA(ctx context.Context, userID string, mfaType MFAType) (map[string]string, error)
// SetUserMFA 设置用户MFA
SetUserMFA(ctx context.Context, userID string, mfaType MFAType, data map[string]string) error
// DisableUserMFA 禁用用户MFA
DisableUserMFA(ctx context.Context, userID string, mfaType MFAType) error
// ListUserMFA 列出用户启用的MFA类型
ListUserMFA(ctx context.Context, userID string) ([]MFAType, error)
}
MFARepository 多因素认证仓库
type QRCodeGenerator ¶
type QRCodeGenerator interface {
// GenerateQRCode 生成二维码图像
GenerateQRCode(uri string, size int) ([]byte, error)
}
QRCodeGenerator 接口定义二维码生成器
type RedisMFARepository ¶
type RedisMFARepository struct {
// contains filtered or unexported fields
}
RedisMFARepository Redis MFA仓库实现
func NewRedisMFARepository ¶
func NewRedisMFARepository(config RedisMFARepositoryConfig) (*RedisMFARepository, error)
NewRedisMFARepository 创建Redis MFA仓库
func (*RedisMFARepository) DisableUserMFA ¶
func (r *RedisMFARepository) DisableUserMFA(ctx context.Context, userID string, mfaType MFAType) error
DisableUserMFA 实现MFARepository.DisableUserMFA
func (*RedisMFARepository) GetUserMFA ¶
func (r *RedisMFARepository) GetUserMFA(ctx context.Context, userID string, mfaType MFAType) (map[string]string, error)
GetUserMFA 实现MFARepository.GetUserMFA
func (*RedisMFARepository) ListUserMFA ¶
ListUserMFA 实现MFARepository.ListUserMFA
func (*RedisMFARepository) SetUserMFA ¶
func (r *RedisMFARepository) SetUserMFA(ctx context.Context, userID string, mfaType MFAType, data map[string]string) error
SetUserMFA 实现MFARepository.SetUserMFA
type RedisMFARepositoryConfig ¶
type RedisMFARepositoryConfig struct {
// Redis客户端
Client redis.Client
// 键前缀
KeyPrefix string
// 数据有效期
Expiration time.Duration
}
RedisMFARepositoryConfig Redis MFA仓库配置
type TOTP ¶
type TOTP struct {
// contains filtered or unexported fields
}
TOTP 实现基于时间的一次性密码
func (*TOTP) GenerateCodeAt ¶
GenerateCodeAt 在指定时间生成OTP码
func (*TOTP) GenerateWithOffset ¶
GenerateWithOffset 生成包含时间偏移的OTP码
type TOTPConfig ¶
type TOTPConfig struct {
// Secret 密钥
Secret string
// Digits OTP位数
Digits int
// Period 时间步长(秒)
Period int
// Algorithm 算法
Algorithm string
// Issuer 颁发者
Issuer string
// AccountName 账户名
AccountName string
}
TOTPConfig TOTP配置
func NewDefaultTOTPConfig ¶
func NewDefaultTOTPConfig(issuer, accountName string) *TOTPConfig
NewDefaultTOTPConfig 创建默认TOTP配置
type TOTPProvider ¶
type TOTPProvider struct {
// contains filtered or unexported fields
}
TOTPProvider TOTP提供者
func NewTOTPProvider ¶
func NewTOTPProvider(repository MFARepository, issuer string, window int) *TOTPProvider
NewTOTPProvider 创建TOTP提供者
func (*TOTPProvider) Disable ¶
func (p *TOTPProvider) Disable(ctx context.Context, userID string) error
Disable 实现MFAProvider.Disable
func (*TOTPProvider) GenerateChallenge ¶
GenerateChallenge 实现MFAProvider.GenerateChallenge 对于TOTP不需要生成挑战,用户使用自己的认证器生成
func (*TOTPProvider) ProviderType ¶
func (p *TOTPProvider) ProviderType() MFAType
ProviderType 实现MFAProvider.ProviderType
func (*TOTPProvider) Setup ¶
func (p *TOTPProvider) Setup(ctx context.Context, userID string, params map[string]string) (map[string]string, error)
Setup 实现MFAProvider.Setup
func (*TOTPProvider) VerifyChallenge ¶
func (p *TOTPProvider) VerifyChallenge(ctx context.Context, userID string, response string) (bool, error)
VerifyChallenge 实现MFAProvider.VerifyChallenge