mfa

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 2, 2025 License: MIT Imports: 15 Imported by: 0

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

View Source
const (
	// DefaultPeriod 默认时间步长(秒)
	DefaultPeriod = 30
	// DefaultDigits 默认OTP位数
	DefaultDigits = 6
	// DefaultAlgorithm 默认算法
	DefaultAlgorithm = "SHA1"
)

Variables

View Source
var (
	// ErrMFARequired 表示需要MFA认证
	ErrMFARequired = errors.New("需要进行多因素认证")
	// ErrMFAInvalid 表示MFA验证失败
	ErrMFAInvalid = errors.New("多因素认证验证失败")
	// ErrMFANotEnabled 表示未启用MFA
	ErrMFANotEnabled = errors.New("未启用多因素认证")
	// ErrUserNotFound 表示用户未找到
	ErrUserNotFound = errors.New("用户未找到")
)

Functions

func GenerateSecret

func GenerateSecret(length int) (string, error)

GenerateSecret 生成随机密钥

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

func (r *InMemoryMFARepository) ListUserMFA(ctx context.Context, userID string) ([]MFAType, error)

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

func (a *MFAAuthenticator) DisableMFA(ctx context.Context, userID string, mfaType MFAType) error

DisableMFA 禁用MFA

func (*MFAAuthenticator) PreAuthenticate

func (a *MFAAuthenticator) PreAuthenticate(ctx context.Context, credential auth.Credential) (*AuthenticationResult, error)

PreAuthenticate 预认证(第一因素)

func (*MFAAuthenticator) SetupMFA

func (a *MFAAuthenticator) SetupMFA(ctx context.Context, userID string, mfaType MFAType, params map[string]string) (map[string]string, error)

SetupMFA 设置MFA

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 MFAType

type MFAType string

MFAType 多因素认证类型

const (
	// MFATypeNone 无MFA
	MFATypeNone MFAType = "none"
	// MFATypeTOTP 基于时间的一次性密码
	MFATypeTOTP MFAType = "totp"
	// MFATypeSMS 短信验证码
	MFATypeSMS MFAType = "sms"
	// MFATypeEmail 邮件验证码
	MFATypeEmail MFAType = "email"
)

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

func (r *RedisMFARepository) ListUserMFA(ctx context.Context, userID string) ([]MFAType, error)

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 NewTOTP

func NewTOTP(config *TOTPConfig) (*TOTP, error)

NewTOTP 创建TOTP

func (*TOTP) GenerateCode

func (t *TOTP) GenerateCode() (string, error)

GenerateCode 生成当前OTP码

func (*TOTP) GenerateCodeAt

func (t *TOTP) GenerateCodeAt(at time.Time) (string, error)

GenerateCodeAt 在指定时间生成OTP码

func (*TOTP) GenerateWithOffset

func (t *TOTP) GenerateWithOffset(offset int) (string, error)

GenerateWithOffset 生成包含时间偏移的OTP码

func (*TOTP) GetSecret

func (t *TOTP) GetSecret() string

GetSecret 获取密钥

func (*TOTP) GetURI

func (t *TOTP) GetURI() string

GetURI 获取OTP URI(用于生成二维码)

func (*TOTP) ValidateCode

func (t *TOTP) ValidateCode(code string) bool

ValidateCode 验证OTP码

func (*TOTP) ValidateCodeWithWindow

func (t *TOTP) ValidateCodeWithWindow(code string, window int) bool

ValidateCodeWithWindow 使用时间窗口验证OTP码 window是正向和反向的时间窗口数(例如,window=1表示检查前一个、当前和后一个时间步长)

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

func (p *TOTPProvider) GenerateChallenge(ctx context.Context, userID string) (string, error)

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL