oidc

package
v1.24.0 Latest Latest
Warning

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

Go to latest
Published: Oct 25, 2026 License: Apache-2.0 Imports: 55 Imported by: 0

Documentation

Index

Constants

View Source
const ThirdAuthcodeRedisPrefix = "thirdlogin:authcode:"

ThirdAuthcodeRedisPrefix 与 user 模块 ThirdAuthcodePrefix 一致, 复用前端短码轮询取登录态的现有约定。注意:不能改名,前端协议公开。

Variables

View Source
var (
	// ErrBearerJWTNoUserID payload.userId 缺失或为 0(可能是未认证/默认值哨兵)。
	ErrBearerJWTNoUserID = errors.New("bearer-jwt: userId is required and must be non-zero")
	// ErrJWTTooOld token 的 iat 距今超过调用方传入的 maxAge。
	//
	// 生产路径当前两个调用方都传 0(不设上限)—— 新鲜度改由兑换台账按**兑换
	// 行为**判定,见 redemption_ledger.go。这里保留能力与哨兵:它是纯函数的一个
	// 通用参数,将来若要给某条路径重新加 iat 上限,不必再实现一遍。
	ErrJWTTooOld = errors.New("bearer-jwt: token was issued too long ago")
	// ErrJWTMissingIat payload 无 iat,无法判断新鲜度。
	ErrJWTMissingIat = errors.New("bearer-jwt: iat claim is required")
	// ErrJWTIatInFuture iat 超出时钟偏移容忍范围地位于未来。
	ErrJWTIatInFuture = errors.New("bearer-jwt: iat is too far in the future")
	// ErrBearerJWTSecretTooShort HS256 密钥强度不足。
	ErrBearerJWTSecretTooShort = errors.New("bearer-jwt: shared secret is too short")
)

客户端侧特有的 claims 校验错误。通用的 malformed/alg/sig/exp 错误走 jwt_hs256.go 的哨兵。

View Source
var (
	ErrBindNotFound       = errors.New("oidc: bind session not found or expired")
	ErrBindStatusConflict = errors.New("oidc: bind status transition conflict")
	ErrBindRateLimited    = errors.New("oidc: bind rate limit exceeded")
	// ErrBindNoPhone claims 里没有可信手机号(空 / phone_verified=false),
	// 短信路径(SendSMS / VerifySMS)不可用 —— FR-3.3。
	// 与"SMSService 内部失败"区分,让 handler 把前者翻 400(业务前提不满足,
	// 客户端不应当 retry),后者翻 500(基础设施异常,可重试)。
	ErrBindNoPhone = errors.New("oidc: bind claims has no verified phone")
	// ErrBindConflictNeedManual claims 命中多条 dmwork user(同 phone 多账号),
	// 自助流程无法判定,走 P1 Admin 人工兜底。
	ErrBindConflictNeedManual = errors.New("oidc: bind claims match multiple dmwork users")
	// ErrBindAlreadyBound 同 (issuer, sub) 已绑到别的 uid;或同 (uid, issuer)
	// 已存在另一 sub。两种都触发 DB 唯一约束 → 1062,confirm 路径需要分别
	// 翻成对用户更友好的 409。
	ErrBindAlreadyBound = errors.New("oidc: bind identity already exists")
	// ErrBindAuthRejected 用户输入(密码/OTP)在底层校验被拒绝。与"内部错误"
	// 区分,让 metric label 能正确归到 unauthorized 而非 internal_error。
	// service 层用它包装 auth.* 的 matched=false / VerifyOIDCBindSMS 拒绝。
	ErrBindAuthRejected = errors.New("oidc: bind auth rejected")
	// ErrBindMethodDisabled 调用方请求的方法被运维通过 OCTO_OIDC_BIND_METHODS
	// 关闭了。Methods 必须是真实策略,不仅 UI 过滤 —— 否则攻击者可以硬调
	// 端点绕过运维"禁用密码"的安全开关。handler 翻 400,与"参数非法"同档,
	// 不属于身份凭据拒绝,因此与 ErrBindAuthRejected 区分。
	ErrBindMethodDisabled = errors.New("oidc: bind method disabled by configuration")

	// ErrBindCreateClaimsIncomplete claims 既无 verified email 也无 verified phone:
	// /bind/create 拒绝建号,因为后续客服 / 找回流程没有可信账号锚点。
	// handler 翻 422,metric label claims_incomplete。
	ErrBindCreateClaimsIncomplete = errors.New("oidc bind: claims missing required fields")

	// ErrBindCreateConflictNeedManual bind_token 是从 manual-conflict 来源签发的
	// (claims 命中多条 dmwork 账号);Create 路径拒绝建号,只能走 P1 Admin 人工合并。
	// handler 翻 409,metric label conflict_need_manual。与 ErrBindConflictNeedManual
	// (verify 路径短信多匹配)语义平行,但 token 维度的拒绝在 Create 入口落地,
	// 与 Issue 阶段固化的 IssueReason 字段联动。
	ErrBindCreateConflictNeedManual = errors.New("oidc bind: create rejected: claims conflict needs manual resolution")
)

哨兵错误。调用方按类型而非字符串判断,避免文案改动影响业务路径。

View Source
var (
	// ErrJWTMalformed token 不是 "a.b.c" 三段、base64 解码失败、header/payload 不是合法 JSON。
	ErrJWTMalformed = errors.New("jwt: malformed token")
	// ErrJWTBadAlg header.alg 不是 "HS256" 或 header.typ 异常(拒绝 none/RS256/ES256 等混淆攻击)。
	ErrJWTBadAlg = errors.New("jwt: alg must be HS256")
	// ErrJWTInvalidSig HMAC-SHA256 签名不匹配。
	ErrJWTInvalidSig = errors.New("jwt: invalid signature")
	// ErrJWTExpired payload.exp 存在且早于 now。
	ErrJWTExpired = errors.New("jwt: token expired")
	// ErrJWTMissingExp payload 不含 exp 字段或类型异常。强制要求 exp 是为了
	// 让"永久有效 token"不可能被签发出来。
	ErrJWTMissingExp = errors.New("jwt: exp claim is required")
	// ErrJWTForeign 标注"该失败发生在验签通过之前(含验签本身)",因此无法断定
	// 这张 token 与我方密钥有关。见 IsForeignToken。
	ErrJWTForeign = errors.New("jwt: token cannot be attributed to our key")
)

错误哨兵。调用方用 errors.Is 判类,不要比较错误字符串。

View Source
var (
	// ErrUnknownUser claims 未命中任何已存在的 dmwork 账号,且 AllowNewUser=false。
	ErrUnknownUser = errors.New("oidc: claims do not match any existing dmwork user")
	// ErrConflictNeedManual 同邮箱/手机号在 dmwork 端命中多条用户,需人工合并。
	ErrConflictNeedManual = errors.New("oidc: multiple dmwork users matched, manual link required")
	// ErrEmailNotVerified IdP 返回的邮箱未验证,且配置要求验证后才能自动绑定/创建。
	ErrEmailNotVerified = errors.New("oidc: email not verified by IdP")
)

业务错误。callback handler 会把这些错误翻成不同的 HTTP 状态/前端提示。

View Source
var ErrAlreadyRevoked = errors.New("oidc: refresh token already revoked")

ErrAlreadyRevoked 旧 RT 已被吊销;RotateRefresh 检测到并发竞争(另一 worker 抢先轮换)时返回

View Source
var ErrCallbackBlocked = errors.New("oidc callback rate limit exceeded")

ErrCallbackBlocked /callback 同 IP 失败次数过多,临时锁定。

View Source
var ErrIdentityCaseCollision = errors.New(
	"oidc: identity row differs only by case folding; refusing rather than merging identities")

ErrIdentityCaseCollision 报告"ci 查询命中了一行,但它与查询值不是逐字节相等"。

为什么必须是一个**可区分的结果**,而不是复用"没查到"(nil, nil):

逐字节复核把"静默合并两个人"换成了"响亮拒绝",那个取舍是对的。但"没查到"会让 ResolveOrLink 回 IsNew=true,而调用方拿到它就去 IssueSession(CreateUser=true) —— 用户行**先建出来**,随后的 identity Insert 才撞上 ci 唯一键报 1062,竞态恢复又 走同一个逐字节查询、同样看不见那行,于是返回 nil、登录被拒。

净效果:每一次登录尝试留下一个孤立 user 行,然后永久失败,且可无限重复 (callback 只有全局 IP 底)。把它变成一个错误,拒绝就落在 ResolveOrLink 里, 在任何副作用之前。

View Source
var ErrIdentityUntrusted = errors.New("oidc: identity could not be established")

ErrIdentityUntrusted provider 无法确立可信身份。

Identity 的所有失败都 wrap 它,让 handler 用 errors.Is 归成同一处理分支: 记 IP 失败计数 + 返回统一的通用错误。具体原因只进日志 —— 反枚举要求 认证失败对外只有一种表现,不能按原因分出可区分的响应。

View Source
var ErrReturnToRejected = errors.New("oidc: return_to rejected")

ErrReturnToRejected return_to 校验失败(空、非法 URL、host 不在白名单)

View Source
var ErrStateNotFound = errors.New("oidc: state not found or already consumed")

ErrStateNotFound state 已过期、被消费或从未存在

Functions

func IsForeignToken added in v1.18.0

func IsForeignToken(err error) bool

IsForeignToken 报告一个 Verify 错误是否意味着"这张 token 不是我们签的"。

判定依据是 **ErrJWTForeign 标记**,而不是错误哨兵的身份。

曾经这里按哨兵身份判:ErrJWTMalformed / ErrJWTBadAlg / ErrJWTInvalidSig 三者 视为"不是我们的"。**那个前提是假的** —— ErrJWTMalformed 横跨 hmac.Equal 两侧: 段数/base64 不对是验签前(确实无法归属),而 "payload json"、"exp 不是整数"、 "payload decode to out" 三处出现在验签**通过之后**,却报同一个哨兵。于是一张 带着我方合法 HMAC、只是 payload 字段类型写错的 token(JS 后端写 `iat: Date.now()/1000` 不取整就是这个形态)会被判成"别人的",回落转发给上游 —— 而上游那条路径把凭据放在 URL query 上,于是载荷里的 PII 加一份在我方密钥下 合法的签名一起落进第三方访问日志。后者是可离线爆破密钥的材料,正是本模块给 密钥设 32 字节下限时所防的东西。

所以判定必须由**产生错误的位置**显式标注,并且方向要反过来 —— 白名单:

  • 只有验签前/验签本身的失败被标 ErrJWTForeign,只有它们算"不是我们的";
  • 其余一切(含将来新增的 claims 约束、含忘了标注的新错误)默认算"是我们的", 调用方就地拒绝、不转发。

黑名单会让"忘记标注"fail-open(转发),白名单让它 fail-closed(401)。 这个区分放在这里而不是让每个调用方拼错误列表,是因为漏一个的后果是泄漏凭据。

func JWTShapedCredentialMustNotBeForwarded added in v1.18.0

func JWTShapedCredentialMustNotBeForwarded(caps ProviderCapabilities, raw string) bool

JWTShapedCredentialMustNotBeForwarded 判断"这张凭据是否绝不能被外发"。

条件只有两个,**都与我方是否配置了密钥无关**:

  • provider 声明 OpaqueClientCredential —— 它的 access_token 是不透明串;
  • 值是 JWT 形态。

上一版还多一个 `!verifierConfigured` 门控,那是个错误:论证是"JWT 不可能是这个 上游的合法凭据",这件事无条件成立,门控让它只覆盖了一半。漏掉的那半最现实的 触发是**密钥轮换** —— 窗口期里客户端手上还有用旧密钥签的 token,它们确确实实 是我方签发的,HMAC 对不上新密钥就被判 foreign、然后外发。于是"我方签发的凭据 绝不外发"这条不变量每次轮换都破一次。

**调用顺序:必须排在 HMAC 验签之后。** 一张有效的业务 JWT 也是 JWT 形态。

两扇门上这条的后果不同,值得说清:

  • modules/integration 是**常驻认证器**,有效的业务 JWT 必须**通过**。顺序写反 就把桌面端整条路拒掉 —— 那里用 `claims == nil &&` 做前置条件, 并由 TestBearerJWT_SpacesAndExchangeWork 钉住(去掉前置条件即红)。
  • /exchange 上业务 JWT 两种顺序都会被拒(该发 /exchange-jwt),所以顺序只影响 上报的原因:own_business_jwt(认出是我们的)还是 unverifiable_jwt(只知道是 JWT 形态)。对客户端不可分,但排障时是两回事。

func NewPKCEPair

func NewPKCEPair() (verifier, challenge string, err error)

NewPKCEPair 按 RFC 7636 S256 生成 (code_verifier, code_challenge)

func NewRandomString

func NewRandomString(byteLen int) (string, error)

NewRandomString 生成 URL-safe Base64 编码的随机字符串(byteLen 字节熵)

func ValidateReturnTo

func ValidateReturnTo(raw string, allowedHosts []string) (string, error)

ValidateReturnTo 校验 callback 完成后跳转地址是否合法。

规则(防开放重定向):

  1. 空字符串 -> 视为合法,调用方应回退到默认页(返 "" 表示无跳转)
  2. 相对路径(以 / 开头,不含 //)-> 合法,host 由前端域名决定
  3. 绝对 URL -> 必须是 http/https,且 host 命中白名单

任何其他形态(scheme-less // 形式、javascript:、data: 等)一律拒绝。

func VerifyHS256JWT added in v1.18.0

func VerifyHS256JWT(token string, secret []byte, now time.Time, out any) error

VerifyHS256JWT 解析并校验一个 HS256 JWT,验签通过后把 payload 反序列化到 out。

行为(全部是安全默认,调用方无法关闭):

  • token 必须正好三段 (header.payload.signature);
  • header.alg 必须是 "HS256"(大小写敏感),header.typ 若存在必须是 "JWT";
  • 签名用 HMAC-SHA256 计算,比较用 hmac.Equal 防时序侧信道;
  • payload.exp 必须存在,必须是 JSON 数字(Unix 秒),且必须 > now(零宽);
  • payload 通过 json.Unmarshal 填充到 out(out 必须是非 nil 指针)。

本函数不校验 iss/aud/sub:这些语义是调用方(IdP 适配器)的责任。它只保证 "这个 token 是持有 secret 的一方签的、还没过期、是 HS256、结构合法"。

Types

type AuditEvent

type AuditEvent string

AuditEvent 审计事件类型

const (
	EventAuthorize    AuditEvent = "authorize"
	EventCallbackOK   AuditEvent = "callback_ok"
	EventCallbackFail AuditEvent = "callback_fail"
	EventRefreshOK    AuditEvent = "refresh_ok"
	EventRefreshFail  AuditEvent = "refresh_fail"
	EventLogout       AuditEvent = "logout"

	// 自助绑定流程事件(P0,SR-6 审计完整性)。
	// 不改 oidc_audit_log schema —— 仍写同一张表,通过 event 列区分场景。
	EventBindIssued      AuditEvent = "bind_issued"
	EventBindVerifyOK    AuditEvent = "bind_verify_ok"
	EventBindVerifyFail  AuditEvent = "bind_verify_fail"
	EventBindOTPSend     AuditEvent = "bind_otp_send"
	EventBindOTPSendFail AuditEvent = "bind_otp_send_fail"
	EventBindConfirmOK   AuditEvent = "bind_confirm_ok"
	EventBindConfirmFail AuditEvent = "bind_confirm_fail"
	EventBindRefused     AuditEvent = "bind_refused"
	EventBindCreated     AuditEvent = "bind_created"
	EventBindCreateFail  AuditEvent = "bind_create_fail"

	// token exchange 事件(原生客户端直连用)。
	EventExchangeOK   AuditEvent = "exchange_ok"
	EventExchangeFail AuditEvent = "exchange_fail"

	// bearer JWT exchange 事件(原生客户端持自签 bearer JWT 直连)。
	EventBearerExchangeOK   AuditEvent = "exchange_jwt_ok"
	EventBearerExchangeFail AuditEvent = "exchange_jwt_fail"
)

type AuditModel

type AuditModel struct {
	UID       string
	Event     AuditEvent
	IP        string
	UserAgent string
	Reason    string
	TraceID   string
	db.BaseModel
}

AuditModel 登录与状态同步审计

Event 用 AuditEvent 字符串别名,提供编译期类型安全防止误用任意字符串; dbr 通过反射读取底层 string,落库行为与裸 string 字段完全一致。

type AuthCodeParams added in v1.18.0

type AuthCodeParams struct {
	// State CSRF 绑定,任何 provider 都必须提供。
	State string
	// Nonce 仅 Capabilities.Nonce=true 时有意义。
	Nonce string
	// CodeChallenge 仅 Capabilities.PKCE=true 时有意义。
	CodeChallenge string
}

AuthCodeParams 构造 authorize URL 所需的请求级一次性参数。

标准 OIDC 会填满三个字段;plain-OAuth2 只用 State,其余由实现忽略 —— 调用方无需按 kind 分别构造。

type AuthProvider added in v1.18.0

type AuthProvider interface {
	Kind() ProviderKind
	Capabilities() ProviderCapabilities

	// EndSessionEndpoint 上游可跳转的 RP-Initiated Logout 端点;不可用时返回空串。
	//
	// 契约:Capabilities().IDToken 为 false 的实现**必须**返回空串 —— 没有
	// id_token 就没有 id_token_hint,那个端点结束不了任何会话。
	//
	// 为什么要放进接口而不是让上层对具体类型做断言:上层用它决定"要不要装
	// id_token 缓存",而对 *oidcProvider 做断言会被任何一层包装(装饰器、将来
	// 的第三个 IdP)悄悄打掉,RP-Initiated Logout 于是静默消失。本文件开头
	// 那条规则("业务分支一律读 Capabilities,不读 Kind")就是为这类判断立的。
	EndSessionEndpoint() string

	// Issuer 写入 user_oidc_identity.issuer 的稳定身份命名空间。
	//
	// 标准 OIDC 下它是经 Discovery 校验过的 issuer;plain-OAuth2 下它是运维
	// 配置的常量,不具备密码学意义。该值一旦上线不可更改:改了会让全部存量
	// 绑定在登录第一步 miss,等于全员按新账号重建。
	Issuer() string

	AuthCodeURL(p AuthCodeParams) (string, error)

	// Exchange 用授权码换 token。codeVerifier 仅 Capabilities.PKCE 时有意义。
	Exchange(ctx context.Context, code, codeVerifier string) (*TokenSet, error)

	// Identity 返回本次登录的权威身份 claims。
	//
	// OIDC 实现:验签 id_token → 按需拉 /userinfo → 交叉校验 sub → 合并。
	// plain-OAuth2 实现:GET /userinfo → 解私有信封 → 映射到 claims。
	Identity(ctx context.Context, tok *TokenSet) (*IdentityClaims, error)

	// IdentityFromClientCredential 把**客户端直接出示的**上游凭据映射为 claims。
	//
	// 与 Identity 的区别不在实现,而在凭据的来源:Identity 处理的是我方用
	// authorization code 换回来的 TokenSet(我方知道里面有什么);这个方法处理的是
	// 客户端自己完成 SSO 后带过来的一个字符串(我方只知道它是个 Bearer)。
	//
	// 为什么必须由 provider 决定怎么解释这个字符串:
	//
	//   - 标准 OIDC 下客户端手上的可验证凭据是 id_token(有签名,能独立验);
	//   - plain-OAuth2 下是不透明的 access_token(没有签名,只能拿去问 /userinfo)。
	//
	// 上层拿不到这个区别就只能猜,而**按 token 长得像不像 JWT 来猜是不可接受的**:
	// 一个不透明 access_token 完全可能恰好是 JWT 形态,那时会被送进错误的验证路径
	// 并可能通过。所以由 provider 按自己的协议事实解释,上层保持 kind 无关。
	//
	// 失败一律返回 error;调用方对客户端只回一个笼统的 401(反枚举)。
	IdentityFromClientCredential(ctx context.Context, raw string) (*IdentityClaims, error)

	// LogoutURL 返回上游登出跳转地址;不支持或材料不全时返回 ("", false)。
	//
	// 返回值必须由**浏览器顶层导航**访问。服务端代理该请求不会携带用户在 IdP
	// 域下的 cookie,等于谁也没登出。
	LogoutURL(ctx context.Context, hint LogoutHint) (string, bool)
}

AuthProvider 一个上游身份提供方的协议适配器。

实现契约(两个实现都必须满足,由 provider_conformance_test.go 共同钉住):

  • Identity 返回的 claims 必须 Issuer != "" 且 Subject != ""。 user_oidc_identity.subject 是 NOT NULL DEFAULT ” 且带 UNIQUE(issuer,subject), 放进空串会让所有空 sub 用户塌成同一行、互相登进对方账号 —— 这是账号接管, 不只是脏数据,因此必须在 provider 层就拦住。
  • Identity 内部完成本协议一切可做的完整性校验(验签 / sub 交叉校验 / 私有信封的 success+code 判定),对上层只暴露"可信"或 error。
  • 任何返回给上层的 error 都不得包含带凭据的 URL —— 见 sanitizeTransportErr。

type AuthProviderResult added in v1.18.0

type AuthProviderResult struct {
	Provider AuthProvider
	Client   *Client
}

AuthProviderResult 构造结果。

Client 只在标准 OIDC kind 下非 nil。把它单独返回而不是藏进 provider,是因为 SyncWorker 仍直接依赖 *Client 的刷新能力(那部分尚未迁到抽象后面);plain-OAuth2 kind 下它恒为 nil,调用方必须按 nil 处理而不能假设总有一个 client。

func NewAuthProvider added in v1.18.0

func NewAuthProvider(ctx context.Context, cfg ProviderConfig, onWarn func(msg string, err error)) (*AuthProviderResult, error)

NewAuthProvider 按 cfg.Kind 构造 AuthProvider。

onWarn 可为 nil;非 nil 时用于上报那些"能继续但值得知道"的情况(例如标准 OIDC 下 /userinfo 拉取失败但 id_token 已足够确立身份)。

失败即返回 error,调用方必须让相关端点 fail-closed —— 一个构造失败的 provider 意味着我方无法确立任何身份,此时放行任何请求都是无认证放行。

type BearerJWTVerifier added in v1.18.0

type BearerJWTVerifier struct {
	// contains filtered or unexported fields
}

BearerJWTVerifier 验证业务后端自签的 HS256 JWT 并映射为 IdentityClaims。

零值不可用;必须经 NewBearerJWTVerifier 构造。

func NewBearerJWTVerifier added in v1.18.0

func NewBearerJWTVerifier(cfg ProviderConfig) (*BearerJWTVerifier, error)

NewBearerJWTVerifier 从环境装配验签器。

未配置密钥时返回 (nil, nil) —— 这是合法部署形态("上游 OIDC 开、业务 JWT 不接"), 调用方按 nil 表示"这条凭据路径未启用"处理。

密钥不达标或 issuer 派生失败时返回 error:两者都是运维配置错误,不能静默降级成 "这条路径不可用",否则桌面端会以一个笼统的 401 表现出来,而真实原因只在启动 日志里一闪而过。

func (*BearerJWTVerifier) Issuer added in v1.18.0

func (v *BearerJWTVerifier) Issuer() string

Issuer 这条路径的身份命名空间(上游 issuer + "#bearer-jwt")。

与上游 issuer 隔离是必须的:业务 JWT 的 userId 与上游 subject 是两套 ID 空间, 共用命名空间会让 (issuer, subject) 把两个不同的人合成一个账号。

func (*BearerJWTVerifier) SecretLen added in v1.18.0

func (v *BearerJWTVerifier) SecretLen() int

SecretLen 供启动日志用,不回显密钥本身。

func (*BearerJWTVerifier) VerifyForAuthentication added in v1.18.0

func (v *BearerJWTVerifier) VerifyForAuthentication(raw string, now time.Time) (*IdentityClaims, error)

VerifyForAuthentication 用于**每次请求都出示同一张 token** 的常驻认证器 (modules/integration 的两个端点)。

生命周期用 token 自己的 exp,**不进兑换台账**:桌面客户端登录后把这张 JWT 存进 本地并长期复用,并不会每次重签,而这条路径每次请求都要验它。台账判的是"这次 兑换该不该发生",一次只读请求去刷新兑换窗口没有意义;反过来,把兑换那侧的上限 (曾经是 iat 起算的 10 分钟,已删除;现在是 F/T)套到认证器上,结果是登录若干 分钟后端点永久返回 401,而且与"凭据无效"不可区分。

换来的代价是这条路径的可重放窗口等于 exp(约 15 天)。这不是本方法引入的问题, 而是"上游 JWT 没有 aud/jti"这条已记在 Pending 的约束的直接后果;用一个会弄坏 功能的上限去掩盖它,并不会让凭据更安全。

func (*BearerJWTVerifier) VerifyForRedemption added in v1.18.0

func (v *BearerJWTVerifier) VerifyForRedemption(raw string, now time.Time) (*RedeemedBearerJWT, error)

VerifyForRedemption 用于"出示一次、换成我方会话"的场景(/exchange-jwt)。

**这里不再套 iat 起算的新鲜度上限。** 曾经套的是一个 10 分钟的常量, 锚点是上游签发时刻 —— 与"用户什么时候真的来兑换"无关,于是登录后隔半小时才 兑换的合法客户端被拒,而 10 分钟内抓到 token 的攻击者照样能兑。新鲜度改由 redemption_ledger.go 按兑换行为判定(首次兑换上限 F + 空闲窗口 T)。

本方法因此只回答"这张 token 是不是我们签的、有没有过期、claims 合不合法", 且**无副作用** —— api_exchange.go 用它做凭据归属分类(判断一张 token 是不是 发错端点的业务 JWT),那条路径不是兑换,不能在台账上留下痕迹。

type BindAuthenticator added in v1.4.0

type BindAuthenticator interface {
	VerifyPasswordByUID(ctx context.Context, uid, password string) (matched bool, reason string, err error)
	SendOIDCBindSMS(ctx context.Context, zone, phone string) error
	VerifyOIDCBindSMS(ctx context.Context, zone, phone, code string) error
	// IsBindable Confirm 路径在 identity.Insert 前对 CandidateUID 做最后一次
	// 状态复核。详见 user.IService.IsBindable godoc。
	IsBindable(ctx context.Context, uid string) (bool, error)
}

BindAuthenticator OIDC 自助绑定流程对 user 模块的最小依赖接口。

生产路径下由 user.IService 直接实现(同 verificationUpserter 模式); 测试用 fake 注入断言入参。三方法签名与 user.IService 完全一致,这里 在 oidc 包内重新声明是为了:

  • 遵循 "Accept interfaces, return structs":小接口在使用方包内定义;
  • 让 bind_service_test.go 不必拉起整个 user.Service 就能跑契约测试。

type BindConfig added in v1.4.0

type BindConfig struct {
	Enabled         bool
	IssuerAllowlist []string
	TokenTTL        time.Duration
	VerifyMax       int64
	OTPSendMax      int64
	ConfirmMax      int64
	UIDFailPerDay   int64
	Methods         []BindMethod
	SupportContact  string
	RedirectBase    string
	AllowCreate     bool
}

BindConfig 自助绑定相关配置(NFR-4 全部走 env,不硬编码)。

**Enabled=false 时其余字段无效**:LoadConfig 不校验任何依赖关系, PR3 仅起骨架作用,callback 接管在 PR4 才打开。PR4 会加 "Enabled && RedirectBase==”" 这类硬校验。

keyspace 命名:OCTO_OIDC_BIND_* 与已有 DM_OIDC_* 并列,语义上 BindConfig 是 OIDC 模块的子配置块,但运行期可独立灰度(NFR-5)。

type BindConfirmResp added in v1.4.0

type BindConfirmResp struct {
	IssueResp *IssueSessionResp
	SD        *StateData
	UID       string
	Issuer    string
}

BindConfirmResp Confirm 返回给 handler 的完整快照。 handler 拿 IssueResp.LoginRespJSON 写 ThirdAuthcode,SD 用来回填原发起设备 的 authcode key(FR-6.3 跨设备流转)。

type BindCreateResp added in v1.4.0

type BindCreateResp struct {
	IssueResp *IssueSessionResp
	SD        *StateData
	UID       string
	Issuer    string
}

BindCreateResp Create 返给 handler 的完整快照,与 BindConfirmResp 对齐。

type BindInfoResp added in v1.4.0

type BindInfoResp struct {
	// MaskedEmail / MaskedPhone 协议约定恒在(无 omitempty):空字符串 "" 表示
	// 该 claim 不存在,前端按 truthy 分支隐藏对应行。omitempty 会让"无 email"
	// 路径整字段消失,迫使前端把"字段缺失"与"字段为空"当两种状态处理,
	// 也会触发前端 schema validator 抛出 "masked_email must be string"
	// 被通用错误处理误报为"网络异常"(GH#148)。
	MaskedEmail    string       `json:"masked_email"`
	MaskedPhone    string       `json:"masked_phone"`
	Name           string       `json:"name,omitempty"`
	Methods        []BindMethod `json:"methods"`
	SupportContact string       `json:"support_contact,omitempty"`
	AllowCreate    bool         `json:"allow_create"`
	// CreateBlocked 始终序列化(无 omitempty):/bind/info 协议约定该字段恒在,
	// 前端按字符串值分支("" / "disabled" / "claims_incomplete" /
	// "manual_conflict" / "consumed");omitempty 会让 "" 路径整字段消失,
	// 等价于前端要给"字段缺失"和"字段为空字符串"两种状态都写分支。
	CreateBlocked string `json:"create_blocked"`
}

BindInfoResp /info 端点返回给前端的脱敏身份信息(FR-2)。

不含 sub / issuer / claims 原值,避免社工攻击(SR-7)。

type BindLocator added in v1.4.0

type BindLocator interface {
	UIDByUsername(username string) (string, error)
	UIDsByPhone(zone, phone string) ([]string, error)
}

BindLocator 把用户输入(username)或 claims phone 解析到 dmwork uid。

多匹配场景按需扩展(P0 假定 username 全局唯一);UIDsByPhone 返回切片是因为 dmwork user 表的 (zone, phone) 不是强唯一约束 —— 历史脏数据可能有重复。 VerifySMS 路径多匹配 → ErrBindConflictNeedManual,走 P1 Admin 兜底。

type BindMethod added in v1.4.0

type BindMethod string

BindMethod 自助绑定流程允许的二次验证手段(需求 FR-3.1)。

类型化字符串便于:

  • 配置文件解析时做 allowlist 过滤(SR-3 禁用 email_otp)
  • 审计日志按手段维度聚合
  • 前端 /info 接口直接展示可用方法列表
const (
	// BindMethodPassword 账号密码二次验证。
	BindMethodPassword BindMethod = "password"
	// BindMethodSMSOTP 短信 OTP 二次验证。OTP 必须发到 OIDC claims 中
	// phone_number_verified=true 的手机号,不接受用户输入(FR-3.3)。
	BindMethodSMSOTP BindMethod = "sms_otp"
	// BindMethodEmailOTP **明确禁用**(SR-3)。若 IdP 返回的 email 与 dmwork
	// user.email 同值,邮箱 OTP 等价于"用 OIDC claim 自证身份",退化为单
	// 因子。常量保留是为了让"非法手段过滤"的代码路径可读 —— 见
	// loadBindMethods 中的显式 drop。
	BindMethodEmailOTP BindMethod = "email_otp"
)

type BindService added in v1.4.0

type BindService struct {
	// contains filtered or unexported fields
}

BindService 自助绑定状态机的业务逻辑层。

不持有 HTTP 上下文 / *wkhttp.Context;handler 层负责 HTTP 解析、CallbackGuard IP 限流、审计写入(events 在 model.go 已就位)。

identity / users 仅 Confirm 路径用到,在 Init() 检测到 Bind.Enabled=true 时统一注入(见 api.go:202-203)。其他 5 个方法(Issue/Info/Verify*/SendSMS) 不依赖这两个字段,单测可以不注入。

func (*BindService) Confirm added in v1.4.0

func (s *BindService) Confirm(ctx context.Context, jti string) (*BindConfirmResp, error)

Confirm 自助绑定终态写入。串行步骤(与下方代码一一对应):

  1. Get session(不消费)
  2. ConfirmMax counter +1(SR-2.1)—— 故意放在 status 检查之前 (asymmetry note,与 VerifyPassword/VerifySMS 顺序相反)
  3. 校验 Status == verified;否则拒绝
  4. 解出 claims/sd snapshot
  5. identity.Insert((uid, issuer, sub)) —— DB uk_issuer_subject + uk_uid_issuer 兜底 SR-5;duplicate-key → ErrBindAlreadyBound
  6. users.IssueSession 签发 dmwork 会话
  7. Consume session(SR-1 单次消费;Insert 已成功 + IssueSession 失败时**不** Consume,留给客户端重试,二次 Insert 撞唯一约束 → 409 引导走 OIDC 登录)

并发防护(AC-6):多个并发 confirm 同 jti,只有一个能拿到 status=verified 并写入 identity;其他要么撞 status conflict,要么撞 DB unique constraint。 都会返回明确错误,不会重复写。

计数器顺序的 asymmetry 说明:VerifyPassword/VerifySMS 是 status→counter (合法用户的 status 已经被推进就不该被攻击者再消耗 verify 配额);Confirm 是 counter→status(任何形式的"反复 confirm"都该烧 budget,包括 status 不对 的探测,否则攻击者可以零成本探测状态机位置)。

func (*BindService) Create added in v1.4.0

func (s *BindService) Create(ctx context.Context, jti string) (*BindCreateResp, error)

Create 在 status=issued 时用 bind_token 里的 claims 建号 + 写 identity + 签发会话。

顺序很关键(防 ghost user):

  1. Get session
  2. IncrAndCheck("bind:create:"+jti, bindCreateMax) — counter→status 与 Confirm 对齐, 任何对 create 的探测都消耗配额
  3. decode claims + 校验(纯只读,无副作用,失败保持 token 在 issued 让用户重试)
  4. CASSave issued→creating — 唯一的"锁":只有拿到锁的 goroutine 才能进入 产生副作用的 #5/#6/#7。并发 verify/create 都会撞 CAS 失败 → ErrBindStatusConflict, 不会出现"副作用已发生但终态锁不上"的 ghost-user 窗口。
  5. IssueSession({CreateUser:true, ...}) — 副作用 #1:dmwork user 入库
  6. identity.Insert((uid, issuer, sub)) — 副作用 #2:user_oidc_identity 入库
  7. Consume(token) — 终态:token 整条删除,后续 Get 返 ErrBindNotFound

中途失败语义:

  • #5/#6 失败:token 卡在 creating,5min TTL 后自然消失。**不会**被同一 token 的二次 create 重复触发(CAS issued→creating 第二次必败)—— 避免重试产生 第二个 ghost user。用户体感:需要重走 OIDC 登录拿新 bind_token。
  • #6 撞 uk_issuer_subject(并发不同 token 同 issuer+sub):返 ErrBindAlreadyBound, handler 引导用户重发起 OIDC 登录拾取赢家会话(与 plan §4 一致)。
  • #7 失败:用户已建,会话已发,token 5min TTL 自清,只 log warn。

func (*BindService) Info added in v1.4.0

func (s *BindService) Info(ctx context.Context, jti string) (*BindInfoResp, error)

Info 返回脱敏 claims + 可用方法 + create 能力状态。 可用方法 = 配置 Methods ∩ 当前 claims 支持的手段(claims 无 verified phone → 屏蔽 sms_otp,FR-3.3)。

func (*BindService) Issue added in v1.4.0

func (s *BindService) Issue(ctx context.Context, claims *IDTokenClaims, sd *StateData) (string, error)

Issue 在 callback ResolveOrLink 失败分支调用:签发 bind_token,持久化 claims + state_data 快照,返回 jti 供 handler 拼前端跳转 URL。

等价于 IssueWithReason(ctx, claims, sd, BindReasonUnknownUser) —— 历史调用方 (单元测试 + ShouldHandle 早期路径)在没有明确区分原因时保留旧签名,语义即 "claims 未命中已有账号"(可走 /bind/create)。生产 callback 路径应该走 IssueWithReason 明确传 reason,与 manual_conflict 拒建号路径协同。

不在此处写 audit —— handler 在拿到 jti 后统一写 EventBindIssued (handler 持 HTTP 上下文,IP/UA/trace_id 都齐)。

func (*BindService) IssueWithReason added in v1.4.0

func (s *BindService) IssueWithReason(ctx context.Context, claims *IDTokenClaims, sd *StateData, reason IssueReason) (string, error)

IssueWithReason 同 Issue,但额外把 reason 固化到 BindSession.IssueReason 字段。 callback 按 ResolveOrLink 返回的 err 类型选择 reason:ErrUnknownUser → BindReasonUnknownUser(可建号);ErrConflictNeedManual → BindReasonManualConflict (Create 路径拒绝)。详见 IssueReason godoc。

func (*BindService) SendSMS added in v1.4.0

func (s *BindService) SendSMS(ctx context.Context, jti string) error

SendSMS 走短信路径,zone/phone 从 claims snapshot 取(FR-3.3)。

限流:每 jti 维度的"OTP 发送"counter +1(SR-2.1, OTPSendMax 阈值,默认 3 次), 与底层 commonapi.SMSService 的 1min/手机号全局节流互补 —— 后者不带 codeType 跨流程串扰(详见 user.SendOIDCBindSMS godoc),所以 这里的 counter 是 bind_token 维度的真正反爆破。

func (*BindService) ShouldHandle added in v1.4.0

func (s *BindService) ShouldHandle(err error, claims *IDTokenClaims) bool

ShouldHandle 给 callback 失败分支用的接管判定。任何一条不满足就走旧路径, 行为完全保留(NFR-6 可回滚)。

func (*BindService) VerifyPassword added in v1.4.0

func (s *BindService) VerifyPassword(ctx context.Context, jti, identifier, password string) error

VerifyPassword 用户输入 (jti, identifier, password) → locator 解析 uid → auth.VerifyPasswordByUID → 推进状态机到 verified。

限流:每 jti 维度的"verify 尝试"counter +1(SR-2.1, VerifyMax 阈值),超返 ErrBindRateLimited。密码 / 短信共用同一 counter —— 需求文档 SR-2.1 说 "验证尝试 ≤ 5 次",不区分手段。

func (*BindService) VerifySMS added in v1.4.0

func (s *BindService) VerifySMS(ctx context.Context, jti, code string) error

VerifySMS 与 VerifyPassword 共用 verify counter。短信验证通过后推进到 verified, VerifiedMethod=sms_otp。CandidateUID 在短信路径上**留空** —— 短信不 直接确认 uid,confirm 阶段由 claims.phone → user 查询定位(P0 用 phone-only 路径时由 service.UIDsByPhone 走);多匹配场景走 P1 Admin。

type BindSession added in v1.4.0

type BindSession struct {
	JTI            string     `json:"jti"`
	Issuer         string     `json:"issuer"`
	Subject        string     `json:"sub"`
	CandidateUID   string     `json:"candidate_uid,omitempty"`
	ClaimsSnapshot []byte     `json:"claims"`
	SDSnapshot     []byte     `json:"sd"`
	Status         BindStatus `json:"status"`
	VerifiedMethod BindMethod `json:"verified_method,omitempty"`
	OriginIP       string     `json:"origin_ip,omitempty"`
	OriginUA       string     `json:"origin_ua,omitempty"`
	CreatedAt      int64      `json:"created_at"`
	// IssueReason 见 IssueReason godoc。Create 路径在 manual_conflict 时拒绝;
	// Info 路径用它回填 create_blocked 让前端展示对应的引导文案。
	// 旧 token(本字段引入前签发的)会落空字符串,Create 视同 unknown_user 放行,
	// 保持 5min TTL 窗口内的灰度兼容。
	IssueReason IssueReason `json:"issue_reason,omitempty"`
}

BindSession bind_token 在 Redis 里的完整快照。

字段说明:

  • JTI: bind_token 自身,32 字节 base64,Redis key 后缀(SR-7)
  • Issuer/Subject: OIDC claims 原值,confirm 时直接写 user_oidc_identity —— 用户在 5min TTL 内可能换 IdP session,这里固化避免漂移
  • CandidateUID: email/phone 多匹配场景下用户选定的 uid(M1 暂不支持选择, 字段预留)。当前实现下用户走密码路径需先输入 username/uid 定位
  • ClaimsSnapshot: 完整 IDTokenClaims JSON,confirm 时透传给 IssueSession
  • SDSnapshot: 原 StateData JSON 关键字段(authcode/return_to/device_flag), confirm 后回填到原发起设备的 ThirdAuthcode(FR-6.3)
  • Status: 状态机字段(见 BindStatus)
  • VerifiedMethod: 记录哪种手段通过的(audit 维度)
  • OriginIP/UA: 审计 + FR-6.2 设备差异提示
  • CreatedAt: 签发时 Unix 秒,前端展示 + TTL 兜底计算

JSON 序列化:tag 显式写小写,与 oidc 模块其他 *_redis 实现一致。

type BindStatus added in v1.4.0

type BindStatus string

BindStatus 自助绑定 bind_token 状态机。Redis 持久化,TTL 由 BindConfig.TokenTTL 控制。

合法迁移路径:

issued ─── verify ok ───▶ verified ─── confirm ok ───▶ Consume(token 消失)
  │                          │
  │                          └── confirm fail ──▶ verified (允许重试,直到 ConfirmMax)
  │
  ├── create CAS lock ───▶ creating ─── IssueSession+Insert+Consume ──▶ (token 消失)
  │                          │
  │                          └── 中途失败 ──▶ creating (stuck,TTL 自然清理)
  │
  └── 超限/手动放弃 ──▶ refused

CAS 由 BindStore.CASSave 保证。creating/refused 是中间或终止状态,任何对它们 的进一步推进都返 ErrBindStatusConflict。confirmed/created 不入 Redis —— 成功路径由 Consume 把 session 整条删除,后续 Get 拿到 ErrBindNotFound。

creating 引入的目的:把"建号副作用"(IssueSession 落库 + identity.Insert) 包在 CAS 锁后面,防止并发 verify/create 把已经在写真实用户的 token 推到其他 状态后再 saveCreated 撞 conflict —— 那种顺序会留下"ghost user"。

const (
	BindStatusIssued    BindStatus = "issued"
	BindStatusVerified  BindStatus = "verified"
	BindStatusConfirmed BindStatus = "confirmed"
	BindStatusRefused   BindStatus = "refused"
	// BindStatusCreating 介于 issued 与 Consume 之间的中间锁:CAS issued→creating
	// 成功后才允许进入 IssueSession / identity.Insert 等副作用阶段。失败留 creating,
	// 由 5min TTL 自然清理(用户需重走 OIDC 登录获取新 bind_token)。
	BindStatusCreating BindStatus = "creating"
)

type BindStore added in v1.4.0

type BindStore interface {
	// Save 写入新 session,TTL 由 cfg 控制(NFR-2 默认 5min)。
	// session.JTI 非空,Status 调用方指定(通常 BindStatusIssued)。
	//
	// **不做 CAS** —— Save 只在 Issue 阶段(首次写入)使用。状态机后续
	// 迁移必须走 CASSave,否则两个并发 verify 可同时观察到 status=issued,
	// 双 Save 后第二个覆盖第一个的 CandidateUID(身份接管)。
	Save(ctx context.Context, s *BindSession, ttl time.Duration) error

	// Get 读快照不消费。verify / info 路径用,允许多次读。
	// key 不存在返 ErrBindNotFound。
	Get(ctx context.Context, jti string) (*BindSession, error)

	// CASSave 原子地校验 Redis 里当前 sess.Status 与 expected 一致后,
	// 写入入参 sess 的完整 payload 并刷新 TTL。
	//
	// 与朴素 Save 的区别:在 Redis 单线程里完成 "check status → write payload",
	// 两个并发调用即便在客户端侧都读到了相同的旧快照,只有一个能成功 ——
	// 第二个会因 status 已被推进到新值而返 ErrBindStatusConflict。
	//
	// 调用方:bind_service.saveVerified(expected=issued),将来 verified→
	// confirmed 也走这条路径。key 不存在返 ErrBindNotFound。
	CASSave(ctx context.Context, sess *BindSession, expected BindStatus, ttl time.Duration) error

	// Consume 取出并立即删除,confirm 成功路径调(SR-1 单次消费)。
	// key 不存在返 ErrBindNotFound。
	Consume(ctx context.Context, jti string) (*BindSession, error)

	// IncrAndCheck 通用计数器 +1 → 与 limit 比较 → 超返 ErrBindRateLimited。
	// key 由调用方按维度拼装(如 "bind:verify:"+jti / "bind:uidfail:"+uid),
	// 避免 BindStore 持有维度知识。ttl 是首次 +1 设的窗口长度,后续 +1 沿用。
	//
	// 返回的 int64 是 +1 后的当前计数,供审计/告警按值定级。
	IncrAndCheck(ctx context.Context, key string, limit int64, ttl time.Duration) (int64, error)
}

BindStore bind_token 状态 + 限流计数器的 Redis 抽象。

与 StateStore 平行设计:生产用 Redis,测试用 memory 实现。两条实现必须 在 bind_store_test.go 的同一组表驱动测试下通过。

接口职责拆分(每个方法只做一件事):

  • Save / Get / Consume:bind_token 整体生命周期(签发 → 读取 → 终态消费)
  • CASSave:状态机 CAS 迁移 —— 期望 Status 匹配时原子写入整段 sess
  • IncrAndCheck:任意维度的限流计数器(SR-2.1 bind_token 维度 + SR-2.2 uid 维度)

一次性消费(SR-1)由 Consume 保证 —— 取出立即 DEL,即便后续 confirm 失败 也不可重放。状态机 CAS 是次要防护层(防 verified→confirmed 并发重入, 以及 issued→verified 并发 verify 覆盖 CandidateUID 的身份接管)。

type CallbackGuard

type CallbackGuard struct {
	// contains filtered or unexported fields
}

CallbackGuard 按客户端 IP 给 OIDC /callback 限流。

与 user.LoginGuard 同形:Redis INCR + EXPIRE 滑动窗口。

维度选 IP 而非 account/uid,因为 callback 阶段尚未拿到 IdP claims;state 32 字节 随机不可猜,合法用户失败率 ≈ 0,失败计数低门槛(默认 10 / 5min)对正常用户 极宽松,对扫描类攻击足够紧。Redis 不可用 fail-open。

一致性:INCR + EXPIRE 非原子,首次 Incr 成功而 Expire 失败会让 key 永不过期 → IP 永久锁定。RecordFailure 每次都重设 TTL,后续失败修复缺失的 TTL。代价是 滑动窗口语义(攻击者持续尝试时窗口续期),对防扫描更严格,符合安全预期。

func NewCallbackGuard

func NewCallbackGuard(r *redis.Conn, threshold int64, window time.Duration) *CallbackGuard

NewCallbackGuard 构造 CallbackGuard。threshold/window <=0 时回落默认值。

func (*CallbackGuard) Check

func (g *CallbackGuard) Check(ip string) error

Check 失败计数已达阈值返回 ErrCallbackBlocked,否则放行。空 IP 归入共享的 unknown-IP 桶,避免畸形代理头绕过保护。

fail-open:Redis 抖动时不锁,与 LoginGuard 一致。基础设施层网关 cap 兜底 DoS。

nil receiver 安全:测试/配置 disabled 时直接放行,避免 callee 各自加 nil 判断。

func (*CallbackGuard) RecordFailure

func (g *CallbackGuard) RecordFailure(ip string) error

RecordFailure 失败 +1,每次重设 TTL(滑动窗口;详见 CallbackGuard 文档)。 nil receiver 安全。

func (*CallbackGuard) RecordFailureLogged

func (g *CallbackGuard) RecordFailureLogged(ip string)

RecordFailureLogged 包装 RecordFailure,失败仅 warn 不向上扩散。

func (*CallbackGuard) Reset

func (g *CallbackGuard) Reset(ip string) error

Reset 删除 IP 的失败计数(成功路径调用,清场避免长尾误锁)。 nil receiver 安全(测试 / disabled 路径)。

func (*CallbackGuard) ResetLogged

func (g *CallbackGuard) ResetLogged(ip string)

ResetLogged 包装 Reset,失败仅 warn。

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client 封装 go-oidc Provider + oauth2.Config。

接口设计:Client 不持任何请求级状态(state / nonce / verifier),由 service 层管理; Client 只做 Discovery / 构造授权 URL / 换 token / 验签 / 拉 userinfo / 刷新这几件事。

func NewClient

func NewClient(ctx context.Context, cfg ClientConfig) (*Client, error)

NewClient 走 Discovery 拉 issuer metadata,构造 Client。

func (*Client) AuthCodeURL

func (c *Client) AuthCodeURL(state, nonce, codeChallenge string) (string, error)

AuthCodeURL 构造带 PKCE(S256) + state + nonce 的授权 URL。

调用方负责生成并持久化 state / nonce / code_verifier(写 StateStore), 这里只把 code_challenge 透传给 IdP。verifier 永远不上 URL。

func (*Client) EndSessionEndpoint added in v1.5.1

func (c *Client) EndSessionEndpoint() string

EndSessionEndpoint 返回 Discovery 暴露的 RP-Initiated Logout 端点; IdP 未声明时返回空字符串。

func (*Client) Exchange

func (c *Client) Exchange(ctx context.Context, code, codeVerifier string) (*oauth2.Token, error)

Exchange 用 authorization_code + code_verifier 换 token。

PKCE 的 code_verifier 通过 oauth2 的 SetAuthURLParam 传给 IdP;调用方需 确保和 AuthCodeURL 阶段的 challenge 是同一对(从 StateStore 取出)。

func (*Client) Issuer

func (c *Client) Issuer() string

Issuer 返回 issuer URL(便于断言/审计)。

func (*Client) Refresh

func (c *Client) Refresh(ctx context.Context, refreshToken string) (*oauth2.Token, error)

Refresh 用 refresh_token 换新 token。RT 轮换语义由 IdP 决定, 调用方拿到新 token 后应替换 DB 中的密文 RT(rotate)。

失败语义:

  • "invalid_grant" 等价于 RT 失效(被吊销 / 用户登出 / 自然过期), 调用方应把对应 identity 标记吊销,前端引导重新登录。
  • 其他错误(网络 / 5xx)调用方可重试。

func (*Client) UserInfo

func (c *Client) UserInfo(ctx context.Context, tok *oauth2.Token) (*UserInfoClaims, error)

UserInfo 用 oauth2.Token 拉 /userinfo claims。

go-oidc 的 UserInfo 内部会校验 sub 与 ID Token 的 sub 一致性(若 token 含 ID Token); 这里只暴露 claims,sub 校验由调用方决定信不信任。

func (*Client) VerifyIDToken

func (c *Client) VerifyIDToken(ctx context.Context, rawIDToken string) (*IDTokenClaims, error)

VerifyIDToken 用 issuer JWKS 验签 ID Token,并把 claims 解码到 IDTokenClaims。

不在此处校验 nonce(由 service 层对 StateStore 中的 nonce 比较), 这里只做 RFC 7519 / OIDC Core §3.1.3.7 的签名 + iss + aud + exp 校验(go-oidc 默认行为)。

type ClientConfig

type ClientConfig struct {
	Issuer       string
	ClientID     string
	ClientSecret string
	RedirectURI  string
	Scopes       []string

	HTTPTimeout time.Duration
	ClockSkew   time.Duration
}

ClientConfig OIDC Client 构造参数。从 ProviderConfig 派生,只保留 Client 自身需要的字段。

type Config

type Config struct {
	// ExchangeEnabled 是否挂载 /exchange 与 /exchange-jwt。
	//
	// 默认 **false**:main 上本模块只有 authorize/callback/logout 三条路由,
	// 让这两个端点跟着 DM_OIDC_ENABLED 顺带挂上,等于给每个存量部署白加两个
	// 未认证的会话签发端点,而且没法单独关掉。
	//
	// kind=oidc 下 /exchange 的语义是"出示 id_token 换完整会话",没有 nonce 绑定、
	// 没有重放记录。id_token 是前端信道产物(浏览器历史/前端 JS/Referer 里出现是
	// 它的正常用途),泄漏后的影响原本是"一个会过期作废的断言";挂上这个端点之后
	// 它在 exp 之前等价于该用户的账号。所以必须是显式选择。
	ExchangeEnabled bool

	Enabled  bool
	Provider ProviderConfig
	// Bind 自助绑定子配置(P0)。Bind.Enabled 独立于 Config.Enabled,允许
	// "OIDC 主流程开但 bind 灰度未开" 的中间态(NFR-5)。
	Bind BindConfig
}

Config OIDC 模块完整配置

func LoadConfig

func LoadConfig() (*Config, error)

LoadConfig 从环境变量加载 OIDC 配置

Enabled=false 时不校验 provider 字段,允许编译期配置但运行期关闭。 dmwork-lib 暂未支持 OIDC 配置块,因此走环境变量;后续 dmwork-lib 加完字段 再迁移到 YAML,接口签名保持稳定即可。

type DB

type DB struct {
	// contains filtered or unexported fields
}

DB OIDC 模块数据访问层

func NewDB

func NewDB(ctx *config.Context) *DB

NewDB 构造 DB

func (*DB) DueRefreshes

func (d *DB) DueRefreshes(limit int) ([]*DueRefresh, error)

DueRefreshes 拉一批待刷新 RT,JOIN identity 把 uid 一并取出 —— invalid_grant 时 worker 直接拿 uid 调踢线,不需要再查一次 identity 表。

排序:最久未刷新的优先(`COALESCE(last_refreshed_at, created_at)`)。

索引提示:`COALESCE(...)` 上无 B-tree 索引,filesort 在小数据量(P0 上线初期 预计 < 1k active RT)可接受。RT 量明显增长(>10k)后,按需:

  1. 加复合索引 `(revoked_at, last_refreshed_at, created_at)` 让 WHERE + ORDER BY 局部覆盖;或
  2. 改成应用层维护"下次该刷新时间"列(避免 COALESCE),用单列索引兜住。

JOIN 到 identity 走主键,负担可忽略。

func (*DB) InsertAudit

func (d *DB) InsertAudit(m *AuditModel) error

InsertAudit 写入审计日志

func (*DB) InsertIdentity

func (d *DB) InsertIdentity(m *IdentityModel) error

InsertIdentity 新增绑定关系

LinkedAt 为零值时主动填上当前时间。util.AttrToUnderscore 会把所有字段塞进 Columns,Go 的 time.Time 零值是 0001-01-01,会覆盖 SQL 的 CURRENT_TIMESTAMP 默认值 — 这里显式补齐才能拿到有意义的时间戳。

func (*DB) InsertRefresh

func (d *DB) InsertRefresh(m *RefreshModel) error

InsertRefresh 新增 RT

func (*DB) MarkRefreshRevoked

func (d *DB) MarkRefreshRevoked(id int64) (int64, error)

MarkRefreshRevoked 标记吊销,返回真正改动的行数(0 表示已被其他 worker 抢先吊销)。

幂等语义保留:对已吊销的 id 再次调用不报错。返回 rowsAffected 是为了让多实例 SyncWorker 区分"我刚把 RT 吊销了"(=1)与"别人抢先一步"(=0)—— 后者表示 当前 invalid_grant 只是 IdP 端 RT 旋转后的副产品(其他实例已成功 rotate), 不应踢用户,否则会出现"两实例同时跑就乱踢"的假阳性。

func (*DB) QueryIdentitiesByEmail

func (d *DB) QueryIdentitiesByEmail(issuer, email string) ([]*IdentityModel, error)

QueryIdentitiesByEmail 通过邮箱查询(用于自动绑定时检测冲突)

func (*DB) QueryIdentitiesByUID

func (d *DB) QueryIdentitiesByUID(uid string) ([]*IdentityModel, error)

QueryIdentitiesByUID 查询某个 UID 已绑定的所有第三方身份

func (*DB) QueryIdentityExact added in v1.18.0

func (d *DB) QueryIdentityExact(issuer, subject string) (*IdentityModel, error)

QueryIdentityExact 通过 (issuer, subject) 查询绑定关系,并对返回行做**逐字节复核**。

这是包外唯一可用的入口,原始查询刻意不导出 —— 因为原始查询单独用是不安全的: 本表 COLLATE 是 utf8mb4_general_ci,`WHERE subject='ABC'` 会命中一行 subject='abc' 的记录,于是两个只差大小写的上游主体落到同一个 uid。在登录路径 上那是账号接管;在 modules/integration 的认证中间件上更重 —— 它据此签发 API key。

曾经复核只装在 modules/oidc 的 adapter 里,而 modules/integration 直连了原始 查询,把这个口子开了一半。改成"包外只能拿到复核版"之后,这类绕过是**编译期** 挡住的,不依赖谁记得加守卫。

三种结果必须区分:

  • 逐字节命中 → 返回该行;
  • 确实没有行 → (nil, nil),即"首次登录";
  • ci 命中但不是逐字节相等 → ErrIdentityCaseCollision。

第三种曾经也报 (nil, nil)。那样 ResolveOrLink 会回 IsNew=true,调用方随即 IssueSession(CreateUser=true) 把用户行建出来,之后 Insert 才撞 1062,竞态恢复 走同一个逐字节查询、同样看不见 —— 每次登录尝试留一个孤立 user 行然后永久失败。 现在拒绝落在 ResolveOrLink 里,在任何副作用之前。 也就是把静默合并换成响亮拒绝。

func (*DB) QueryRefreshByHash

func (d *DB) QueryRefreshByHash(hash string) (*RefreshModel, error)

QueryRefreshByHash 通过 token_hash 查询(命中即代表本条 RT 仍有效)

未命中返回 (nil, nil),调用方通过 m == nil && err == nil 判定"记录不存在"。

func (*DB) QueryUIDsByEmail

func (d *DB) QueryUIDsByEmail(email string) ([]string, error)

QueryUIDsByEmail 按邮箱查 dmwork user 表的 uid 列表(用于自动绑定时检测多匹配冲突)。

过滤条件:

  • is_destroy=0:排除冷静期(1)和已注销(2),与 user.VerifyPasswordByUID 的 IsDestroyDone 检查同源
  • status<>0:排除被运维封禁/停用的账号。autolink 命中停用 uid 会让 IssueSession 在终态拒绝,但 OIDC bind 路径会在 confirm 时已经写完 user_oidc_identity, 残留脏数据让该用户后续 OIDC 登录持续失败

TODO: user.IService 后续应暴露 QueryUIDsByEmail,届时本方法迁移到 user 模块, oidc 改走接口避免跨模块 SQL 耦合。

func (*DB) QueryUIDsByPhone

func (d *DB) QueryUIDsByPhone(zone, phone string) ([]string, error)

QueryUIDsByPhone 按手机号查 dmwork user 表的 uid 列表(同 QueryUIDsByEmail)。 同样过滤 is_destroy=0 AND status<>0 —— 见 QueryUIDsByEmail godoc。

过渡期必须**合并**盲索引与明文两路结果再去重,不能"盲索引命中就提前返回": 手机号加密第一阶的存量回填是渐进的,(zone, phone) 又不是强唯一约束(历史脏数据可能 有重复行,见 bind_service.go 的注释)。若一个重复账号已回填、另一个未回填, 提前返回会只给出一个 uid —— 调用方 (BindLocator) 靠 len(uids) 判唯一性, 于是"多账号冲突"被误判成"唯一账号",SMS 绑定会把 OIDC 身份挂到其中一个账号上。 回填收敛后(remaining 归零)可以去掉明文那一路。

func (*DB) RevokeRefreshByUID

func (d *DB) RevokeRefreshByUID(uid string) (int64, error)

RevokeRefreshByUID 把 uid 名下所有未吊销 RT 标记吊销(logout 用)。

两步走是因为 dbr 的 Update builder 不支持 JOIN;先查 identity_id 再批量 IN。 没有 identity 行时直接返回 0,不触发空 IN(...) 子句。

func (*DB) RotateRefresh

func (d *DB) RotateRefresh(oldID int64, newRT *RefreshModel) error

RotateRefresh 用新 RT 替换旧 RT(成功刷新后调用)

旧 RT 的 revoke 走 "WHERE id=? AND revoked_at IS NULL" + RowsAffected 检查, 在并发场景下另一 worker 已轮换过该 RT 时返回 ErrAlreadyRevoked,避免重复轮换。

func (*DB) UpdateIdentityLogin

func (d *DB) UpdateIdentityLogin(id int64, email string, emailVerified int, phone string, phoneVerified int) error

UpdateIdentityLogin 更新最近登录时间与最新 claims 字段

type DueRefresh

type DueRefresh struct {
	ID              int64
	IdentityID      int64
	UID             string
	Subject         string
	TokenCiphertext []byte
	ExpiresAt       time.Time
}

DueRefresh 待刷新 RT 与所属 identity 的 uid 联合查询结果。

uid 必须随 RT 一起取出,否则 invalid_grant 时无法定位要踢谁。

Subject(YUJ-409 Round 2):identity 持有的 OIDC sub,用于 rotate 后调 /userinfo 时做 ownership 校验 —— 防 RT 串台 / IdP 返回错 subject 把别人 的实名 claims 写到本 uid。callback 路径已有同类校验(modules/oidc/api.go:479)。

type Encryptor

type Encryptor struct {
	// contains filtered or unexported fields
}

Encryptor 提供 refresh_token 的对称加密 + 抗预映射哈希

加密:AES-256-GCM,密文格式 nonce(12B) || ciphertext || tag(16B) 哈希:HMAC-SHA256,密钥从主密钥派生(域分离),输出 64 字符小写 hex

func NewEncryptor

func NewEncryptor(key []byte) (*Encryptor, error)

NewEncryptor 用 32 字节主密钥构造 Encryptor

func (*Encryptor) Decrypt

func (e *Encryptor) Decrypt(ciphertext []byte) ([]byte, error)

Decrypt 解密 Encrypt 产生的密文,认证失败返回错误

显式拒绝 < nonce + GCM tag 的密文(payload 至少 0 字节,但 tag 占 16B 不能少), 避免对 GCM 内部行为的隐式依赖,错误信息也更明确。

func (*Encryptor) Encrypt

func (e *Encryptor) Encrypt(plaintext []byte) ([]byte, error)

Encrypt 加密明文,每次返回带随机 nonce 的密文

func (*Encryptor) HashToken

func (e *Encryptor) HashToken(token string) string

HashToken 用派生密钥对 token 做 HMAC-SHA256,作为 user_oidc_refresh.token_hash

相比裸 SHA256,HMAC 让 DB 行单独泄漏时无法离线穷举 token —— 攻击者还需要拿到主密钥。

type IDTokenClaims

type IDTokenClaims struct {
	Issuer  string `json:"iss"`
	Subject string `json:"sub"`
	// 不解 aud:OIDC Core §2 允许 aud 是 string 或 []string,go-oidc 的 Verify
	// 已经做了完整 aud 校验,业务层不需要这个字段。曾经写成 `string` 接,Keycloak /
	// Auth0 多 audience 场景返回 ["client-id"] 时 json.Unmarshal 会 TypeError
	// 直接挂掉所有登录 — 删字段比加自定义 unmarshal 简单。
	Email         string `json:"email"`
	EmailVerified bool   `json:"email_verified"`
	PhoneNumber   string `json:"phone_number"`
	PhoneVerified bool   `json:"phone_number_verified"`
	Name          string `json:"name"`
	Nonce         string `json:"nonce"`
	IssuedAt      int64  `json:"iat"`
	Expiry        int64  `json:"exp"`

	// Aegis identity_verification scope claims(YUJ-382 / Aegis OIDC Phase 1)。
	//
	// 类型按 POC 实测 + wire-format 兜底:Aegis 对接文档把 is_verified / verified_at 写成 string,
	// 实际 token payload 里 is_verified 是 JSON bool、verified_at 是 Unix 秒(number)。
	// 任何一端改了 wire 类型(比如切 Keycloak/Auth0,或 Aegis 管理后台把字段重落 string)
	// 就直接全站登录失败(json.Unmarshal TypeError),aud 字段历史已经踩过一次坑。
	// 这里用 IsVerifiedClaim / VerifiedAtClaim 自定义 UnmarshalJSON 兜底 bool/number/string。
	//
	// 语义:
	//   - IsVerified=true + LegalName != "" 视为"该 IdP 返回了一次有效实名结果",
	//     dmworkim 侧据此 upsert user_verification 表。
	//   - VerifiedProvider 是具体来源域名(如 "cas.example.com"),strip 到一级
	//     (cas/wecom/feishu)再写库 + allowlist 校验,防 Aegis 返回意外值污染 source。
	//   - LegalEmail 允许空,LegalName 必填(空字符串视为未实名,不写库)。
	IsVerified       IsVerifiedClaim `json:"is_verified"`
	VerifiedAt       VerifiedAtClaim `json:"verified_at"`
	VerifiedProvider string          `json:"verified_provider"`
	LegalName        string          `json:"legal_name"`
	LegalEmail       string          `json:"legal_email"`
}

IDTokenClaims 解析后的 ID Token 标准 claims + 业务关心字段。

不暴露原始 Token 对象,避免上层耦合 go-oidc 类型。

type IdentityClaims added in v1.18.0

type IdentityClaims = IDTokenClaims

IdentityClaims 归一化身份。

刻意做成 IDTokenClaims 的**别名**而非新结构体:bind_store 在 Redis 里存的是 该结构体的 JSON 快照,decodeClaimsSnapshot 负责读回。改名或改 tag 会让存量 的在途绑定会话全部解不出来。别名让新代码用中性名字,同时保持 wire 兼容。

type IdentityModel

type IdentityModel struct {
	UID           string
	Issuer        string
	Subject       string
	Email         string
	EmailVerified int
	Phone         string
	PhoneVerified int
	LinkedAt      time.Time
	LastLoginAt   *time.Time
	db.BaseModel
}

IdentityModel 第三方 OIDC 身份与本地 UID 的绑定关系

type IsVerifiedClaim

type IsVerifiedClaim bool

IsVerifiedClaim 兜底 is_verified 的 bool / number / string 三种序列化形态。

背景:Aegis 当前实测把 is_verified 返成 JSON bool,但对接文档又写成 string ("true" / "false")。Keycloak / Auth0 / Okta 等 IdP 的自定义 claim 写法也普遍 按厂商管控面下发成 string(管理后台手动填值,UI 落 JSON 时加了引号)。

aud 字段历史踩过一次类似坑(Verify 阶段 json.Unmarshal TypeError 直接挂掉所有登录, 见 IDTokenClaims 的 aud 注释)。为防下次 IdP 把 wire 类型改了就全站登录失败, is_verified 用 Custom Unmarshal 接 bool / number / string / null。

语义映射:

  • JSON bool true / false → true / false
  • JSON number 0/1 及其他 → 非零为 true
  • JSON string "true" / "1" / "yes"(大小写/空白不敏感) → true
  • 其他字符串 / null / 缺字段 → false(保守,等价于 "未实名")
  • 类型完全无法识别时保留 error,落到 decode 阶段 → 登录失败但会带可读错误, 而不是整个 Unmarshal 静默吞掉其他字段

func (IsVerifiedClaim) Bool

func (c IsVerifiedClaim) Bool() bool

Bool 返回内部 bool 值,用于和 Go 原生 bool 互转(比如写 user 模块时)。

func (*IsVerifiedClaim) UnmarshalJSON

func (c *IsVerifiedClaim) UnmarshalJSON(data []byte) error

type IssueReason added in v1.4.0

type IssueReason string

IssueReason 描述 bind_token 是从哪种 callback 失败分支签发出来的。 Create 路径依赖此字段决定是否允许走"自助建号":多账号脏数据(manual_conflict) 来源的 token 不应当被允许凭 claims 建号 —— 用户在 dmwork 已经有(多个)账号, 走 /bind/create 会再造出新账号加剧数据混乱;只能走 P1 Admin 人工合并。

字段在 BindSession 中持久化,Info 路径用来回填 create_blocked,Create 路径 用来拒绝建号。两个 Issue 入口(callback 的 ResolveOrLink 失败分支)按 err 类型显式置位,避免 oidc 模块的状态隐式扩散。

const (
	// BindReasonUnknownUser claims 未命中已有 dmwork 账号(AllowNewUser=false
	// 或 autolink 未命中)。这是"可以走 /bind/create 自助建号"的合法来源。
	BindReasonUnknownUser IssueReason = "unknown_user"
	// BindReasonManualConflict claims email/phone 命中**多条** dmwork 账号(脏数据)。
	// 不允许走 /bind/create:重复建号会加剧数据混乱;只能走 Admin 人工合并(P1)。
	BindReasonManualConflict IssueReason = "manual_conflict"
)

type IssueSessionReq

type IssueSessionReq struct {
	UID        string
	CreateUser bool
	Name       string
	Email      string
	Phone      string
	Zone       string
	DeviceFlag uint8
	DeviceID   string
	DeviceName string
	DeviceMod  string
	PublicIP   string

	// TrustedSSOCreate 透传到 user.ExternalLoginReq.TrustedSSOCreate,
	// 让可信 IdP 触发的新建用户路径绕过 user 模块的 register.off 全局开关。
	//
	// 仅在 CreateUser=true 时有意义。callback `res.IsNew=true` 与 /bind/create
	// 两条入口显式置 true(代表 IssuerAllowlist 已经过),其他路径(verify→confirm
	// 绑定老用户)留 false —— 与 CreateUser 本身的语义对齐:不建用户的请求不该
	// 表达"信任创建"语义。
	TrustedSSOCreate bool
}

IssueSessionReq 把 ResolveOrLink 的输出 + 请求级设备信息透给 IssueSession。

字段命名与 user.ExternalLoginReq 平行,但保持独立类型避免 oidc 直接依赖 user 类型。

type IssueSessionResp

type IssueSessionResp struct {
	UID           string
	IsNewUser     bool
	LoginRespJSON string
}

IssueSessionResp 会话签发结果。LoginRespJSON 直接塞 ThirdAuthcode Redis, 前端短码轮询取走;调用方不解析其内容。

type LogoutHint added in v1.18.0

type LogoutHint struct {
	UID string
	// RawIDToken 供 OIDC 的 id_token_hint 使用;plain-OAuth2 实现忽略它。
	RawIDToken string
}

LogoutHint 构造上游登出 URL 所需的请求级材料。

type MockOAuth2Provider added in v1.18.0

type MockOAuth2Provider struct {
	// contains filtered or unexported fields
}

MockOAuth2Provider 是 mockOAuth2Provider 的导出门面,供**其他模块**的测试使用。

为什么需要:modules/integration 的两个端点要在 plain-OAuth2 kind 下被端到端 驱动,而这个 kind 的身份来源是上游 /userinfo —— 那必须有一个会返回厂商私有 信封的服务在跑。让 integration 自己起一个 httptest server 就等于把信封形状 抄第二份,而信封解析正是本模块的信任边界:抄错一个字段,那边的测试就在验证 一个我们并不接受的形态。

只暴露测试真正需要的四件事,内部那些故障注入开关不外泄 —— 它们是本包用来 测信任边界的,跨模块使用会把别人的测试绑在本包的实现细节上。

func NewMockOAuth2Provider added in v1.18.0

func NewMockOAuth2Provider(t *testing.T) *MockOAuth2Provider

NewMockOAuth2Provider 起一个返回厂商信封的 /userinfo 与 /token 的 mock IdP。 生命周期绑定 t,测试结束自动关闭。

func (*MockOAuth2Provider) AccessToken added in v1.18.0

func (m *MockOAuth2Provider) AccessToken() string

AccessToken mock 唯一认可的不透明 access_token。

刻意是不透明串而非 JWT:这个协议下 access_token 没有可本地验证的结构, 用 JWT 形态当 fixture 会让"按形态猜"的实现意外通过。

func (*MockOAuth2Provider) BaseURL added in v1.18.0

func (m *MockOAuth2Provider) BaseURL() string

BaseURL 站点根,填给 OCTO_OIDC_PROVIDER_BASE_URL。

func (*MockOAuth2Provider) LastUserInfoQuery added in v1.18.0

func (m *MockOAuth2Provider) LastUserInfoQuery() string

LastUserInfoQuery 返回最近一次 /userinfo 请求的 query 原文;从未被请求时返回空串。

用途是断言**没有**发生外呼:一张本地验签已经认定"是我们自己的、但被拒绝"的 token 绝不能被转发到第三方 IdP —— 那条路径把凭据放在 query string 里 (该 IdP 的形态),于是它会落进对方的访问日志。

func (*MockOAuth2Provider) ResetRequestLog added in v1.18.0

func (m *MockOAuth2Provider) ResetRequestLog()

ResetRequestLog 清掉记录,便于在一次用例里分段断言。

func (*MockOAuth2Provider) SetSubject added in v1.18.0

func (m *MockOAuth2Provider) SetSubject(sub string)

SetSubject 改变 /userinfo 返回的 sub。

取值需满足 checkSubjectShape(纯数字时至少 10 位),否则会在信任边界被拒 —— 那是有意的守卫,不是 mock 的限制。

func (*MockOAuth2Provider) Subject added in v1.18.0

func (m *MockOAuth2Provider) Subject() string

Subject mock 在 /userinfo 里返回的 sub。

type MockProvider

type MockProvider struct {
	Server   *httptest.Server
	Issuer   string
	ClientID string
	// contains filtered or unexported fields
}

MockProvider 自签 RSA 的 httptest OIDC server。

端点按测试需要增量挂载。字段全部线程安全,测试可在多 goroutine 中 PrepXxx。

设计原则:mock 只覆盖被测代码路径会触达的最小协议子集,不追求 RFC 完备。

func NewMockProvider

func NewMockProvider(t *testing.T) *MockProvider

NewMockProvider 启动 httptest server,t.Cleanup 自动 Close。

默认 ClientID="test-client" / ClientSecret="test-secret",与 newTestClient 对齐。

func (*MockProvider) ForceUserInfoStatus

func (m *MockProvider) ForceUserInfoStatus(code int)

ForceUserInfoStatus 让 /userinfo 直接返指定 HTTP 状态(>=400),用于测试 IdP 抖动。 设为 0 恢复正常行为。

func (*MockProvider) PrepCode

func (m *MockProvider) PrepCode(code, sub, nonce string)

PrepCode 预置 authorization_code → sub + nonce(可空)。

nonce 模拟 IdP 在 /authorize 阶段记录的 nonce,后续签 ID Token 时回填。

func (*MockProvider) PrepUser

func (m *MockProvider) PrepUser(sub string, claims map[string]interface{})

PrepUser 预置 sub → claims 映射。重复 sub 后写覆盖前写。

func (*MockProvider) PrepUserInfoOnly

func (m *MockProvider) PrepUserInfoOnly(sub string, claims map[string]interface{})

PrepUserInfoOnly 预置仅在 /userinfo 暴露的 claims(不入 ID Token)。 模拟 Aegis 等 IdP 把 email/phone 放 /userinfo 而非 ID Token 的行为。

func (*MockProvider) ResetUserInfoCalls added in v1.18.0

func (m *MockProvider) ResetUserInfoCalls()

ResetUserInfoCalls 清零计数,便于在一次用例里分段断言。

func (*MockProvider) UserInfoCalls added in v1.18.0

func (m *MockProvider) UserInfoCalls() int

UserInfoCalls /userinfo 至今被请求的次数。

type OIDC

type OIDC struct {
	log.Log
	// contains filtered or unexported fields
}

OIDC OIDC 登录模块。

字段全部包内可见:测试在 New 后可替换 stateStore / authcode 为内存实现。

func New

func New(ctx *config.Context) *OIDC

New 构造 OIDC 模块(生产路径)。

Enabled=false 时只挂 Route 占位,handler 一律返回 404,避免漏配置时静默通过。 Discovery 失败不阻塞启动,handler 自检后返回 500,跟进运维告警即可。

func (*OIDC) Close

func (o *OIDC) Close() error

Close 释放 OIDC 模块持有的资源(redisStateStore 连接池 + SyncWorker goroutine)。

注册到 register.Module.Stop,框架优雅退出时调用。可被多次调用(幂等):

  • New() 内 Discovery 失败会调一次清理 stateStore
  • 之后 framework shutdown 又会调一次,此时 stateStore 已 nil,早返回

func (*OIDC) Init

func (o *OIDC) Init() error

Init 在所有模块初始化完成后调用(register.Module.Start), 此时 user 模块的 IService 已通过 register.GetService 可用。

func (*OIDC) Route

func (o *OIDC) Route(r *wkhttp.WKHttp)

Route 路由注册。Enabled=false 时所有端点返回 404,避免漏配置静默通过。

路径段从 cfg.Provider.ID 取,默认 "oidc";老前端硬编码的 "/aegis" 路径在 ID 不为 "aegis" 时同时挂载作为兼容入口,迁移完成后删除 legacyProviderPathID 即可。

authorize/callback 是公开端点(IdP 重定向到 callback 时不带 dmwork token); logout 必须 AuthMiddleware 校验后拿 uid 才能踢线 + 吊销 RT,所以单独分组。

type OwnCredentialDetector added in v1.18.0

type OwnCredentialDetector struct {
	// contains filtered or unexported fields
}

OwnCredentialDetector 本地判定凭据归属。零值不可用,必须经构造函数。

func NewOwnCredentialDetector added in v1.18.0

func NewOwnCredentialDetector(ctx *config.Context) *OwnCredentialDetector

NewOwnCredentialDetector 装配 detector。

会话查询复用 auth.SessionStoreForContext —— 与 AuthMiddleware 读的是同一份存储, 所以"能不能解析成会话"这个判断在两处必然一致。自己另开一个 Redis 连接或另拼一套 key 规则,就又是一份会漂移的副本,而这里漂移的后果是凭据泄漏。

func (*OwnCredentialDetector) Classify added in v1.18.0

Classify 判定 raw 属于哪一类我方凭据。

返回 (OwnCredentialNone, nil) 表示"确定不是我方凭据",调用方可以走上游路径。 返回 error 表示**判定不出来**(会话存储不可用)—— 调用方必须按"可能是我们的" 处理并就地拒绝,不能回落上游:判不出归属时转发,等于把这道守卫的失败方向 设成了泄漏。

前缀判定是纯本地的、不会失败;只有会话查询会返回 error。

type OwnCredentialKind added in v1.18.0

type OwnCredentialKind string

OwnCredentialKind 本服务签发的凭据类别。空值表示"不是我方凭据"。

const (
	// OwnCredentialNone 判定为非我方凭据(可以走上游路径)。
	OwnCredentialNone OwnCredentialKind = ""
	// OwnCredentialUserAPIKey uk_ 用户 API key。
	OwnCredentialUserAPIKey OwnCredentialKind = "user_api_key"
	// OwnCredentialBotToken bf_ 机器人 token。
	OwnCredentialBotToken OwnCredentialKind = "bot_token"
	// OwnCredentialAppBotToken app_ App Bot token。存 app_bot 表,不在会话存储里,
	// 所以只能靠前缀认出来 —— 长期有效且 DB 背书,泄漏后果比 bf_ 更重。
	OwnCredentialAppBotToken OwnCredentialKind = "app_bot_token"
	// OwnCredentialSessionToken 我方登录会话 token。
	OwnCredentialSessionToken OwnCredentialKind = "session_token"
)

type ProviderCapabilities added in v1.18.0

type ProviderCapabilities struct {
	// PKCE authorize 端点接受 code_challenge/S256。
	PKCE bool
	// Nonce authorize 接受 nonce,且回程有可验证的载荷能把它带回来。
	Nonce bool
	// IDToken token 响应含可验签的 id_token。为 false 时上层不得缓存
	// id_token、不得构造 RP-Initiated Logout。
	IDToken bool
	// RefreshToken 存在**文档化且可用**的刷新端点。仅返回 refresh_token
	// 但没有换取端点时必须为 false,否则 sync worker 会空转。
	RefreshToken bool
	// CrossCheckSub 身份有两个独立来源(id_token 与 /userinfo)可交叉校验。
	CrossCheckSub bool
	// UpstreamLogout IdP 提供可跳转的登出端点。
	UpstreamLogout bool

	// SubjectMayBeReusedPersonnelID 该上游的 subject **可能**是人事系统分配、
	// 会在离职/入职之间复用的标识(工号)。为 true 时上层拒绝"短纯数字"形态的
	// subject —— (issuer, subject) 是不可变主键,复用的工号迟早把新人指到
	// 前任的账号上。
	//
	// 诚实说明这一位的性质:它其实是**按部署**的事实(取决于运维接的是哪家 IdP
	// 的哪套人事系统),现在用 kind 近似 —— plain-OAuth2 只对接了一家,而那家的
	// 文档正是这条论证的来源;标准 OIDC 是存量部署对着任意 IdP 用的通用客户端,
	// 无从知道对方的 sub 从哪来。
	//
	// 所以默认必须是 false:声明这个危险等于对一个 sub 是数据库小主键(1001、42)
	// 的自建 IdP **全量拒登**,而那类 IdP 什么都不复用。接第二家 plain-OAuth2
	// IdP 时,这一位要变成按部署可配,不能继续跟着 kind 走。
	//
	// 长度上限不由这一位控制:那是存储性质,对所有来源统一施加
	// (identity_bounds.go)。
	SubjectMayBeReusedPersonnelID bool

	// OpaqueClientCredential 表示"客户端在这个 provider 上出示的凭据是不透明串,
	// 不可能是 JWT"。
	//
	// 用途只有一个:当我方的业务 JWT 验签器未配置(密钥缺失)时,一张 JWT 形态的
	// 凭据无法被归属判定认出来,会被回落转发给上游 —— 而上游那条路把凭据放在
	// URL query 上。为 true 时上层可以据此**就地拒绝** JWT 形态的输入:该 provider
	// 的 access_token 是不透明 UUID,JWT 在这条路上不可能是合法凭据,转发不可能
	// 成功、只可能把载荷 PII 和一份在客户端密钥下合法的签名送进第三方日志。
	//
	// 为什么是能力位而不是无条件:这是**厂商事实,不是协议事实**。标准 OIDC 下
	// 客户端出示的凭据本身就是 JWT(id_token),无条件拒绝会把 /exchange 在那个
	// kind 上整条掐断。同一个教训见 SubjectMayBeReusedPersonnelID。
	//
	// 这条判定只在"验签器未配置"时才需要 —— 配置正常时 HMAC 是决定性判据,
	// 不需要看形态。
	OpaqueClientCredential bool
}

ProviderCapabilities 声明上游协议**实际具备**的能力。

每个字段都对应一处上层必须跳过的步骤。诚实声明缺失能力比默默降级重要: 例如 CrossCheckSub=false 明确表示"少了一道校验",而不是让那道校验悄悄消失。

type ProviderConfig

type ProviderConfig struct {
	// ID/Name 标识本 provider, 用于路由路径段、审计日志、appconfig 下发给前端做按钮文案与跳转。
	// 未配置时分别默认 "oidc" / "SSO", 保证基础部署不强制运维填这两个字段。
	ID   string
	Name string

	// Kind 上游协议种类,决定用哪个 AuthProvider 实现(OCTO_OIDC_PROVIDER_KIND)。
	// 缺省 KindOIDC —— 存量部署没有这个 env,不能因为引入它而改变行为。
	//
	// 注意:业务分支一律读 ProviderCapabilities,不读 Kind。Kind 只用于选实现、
	// 打 metric label 和启动期配置分叉校验。
	Kind ProviderKind

	// BaseURL 仅 KindOAuth2 使用:IdP 站点根,authorize / token / userinfo /
	// 登出路径都拼在其后(OCTO_OIDC_PROVIDER_BASE_URL)。
	// 留空时回落 Issuer 值 —— 这样接入新 kind 不需要新增必填 env(见 loadProvider
	// 里 required 列表的镜像副本说明)。
	BaseURL string

	// AppID 仅 KindOAuth2 使用:单点登出的应用标识(OCTO_OIDC_PROVIDER_APP_ID)。
	//
	// 它**不是** ClientID —— IdP 侧是两个独立的注册值,由同一批管理员分别下发,
	// 且可能每环境不同。申请凭据时只要了 client id/secret/redirect uri 的话,
	// 登出功能会做不出来。
	AppID string

	Issuer       string
	ClientID     string
	ClientSecret string
	RedirectURI  string
	Scopes       []string

	RequireEmailVerified bool
	RequirePKCE          bool
	AutoLinkByEmail      bool
	// AutoLinkByPhone phone_number_verified=true 时按手机号自动绑历史账号。
	// 单独开关因为部分场景里"邮箱可信"但"手机号未必",分开控制更精细。
	AutoLinkByPhone bool
	AllowNewUser    bool

	ClockSkew   time.Duration
	HTTPTimeout time.Duration

	SyncInterval    time.Duration
	SyncConcurrency int

	// AES-256-GCM 主密钥,用于加密 refresh_token,从 base64 字符串解码
	RefreshTokenEncryptionKey []byte

	// ReturnToHosts callback 完成后允许的 return_to 跳转 host 白名单
	// (DM_OIDC_RETURN_TO_HOSTS,逗号分隔)。空列表表示禁用 return_to,
	// 防开放重定向是 P1.2 必须做的硬约束。
	ReturnToHosts []string

	// PostLogoutRedirectURI logout 成功后让 IdP 回跳的地址(写死的登录页)。
	// 空时 logout 不生成 end_session_url,前端退回"仅清本地"。安全考量:此值由
	// 运维写死、不接受前端传入,因此无需在服务端再做 redirect 白名单 —— 单值即白名单。
	// 上线前需在 IdP 侧注册该回跳地址。
	PostLogoutRedirectURI string

	// EndSessionURL 覆盖/兜底 IdP 的 end_session 端点。优先级高于 Discovery 解析值,
	// 仅在 Discovery 未暴露 end_session_endpoint 时才需要配置。
	EndSessionURL string

	// IDTokenTTL callback 成功后缓存 id_token(供 logout 当 id_token_hint)的 TTL。
	// 默认对齐 RT 生命周期(7 天 = 168h),覆盖用户登录后较长时间才登出的场景。
	// 注意 env 值用 time.ParseDuration 解析,只认 h/m/s —— 写 "7d" 会解析失败并静默
	// 回落默认,要 7 天请填 "168h"。
	IDTokenTTL time.Duration
}

ProviderConfig 单个 OIDC Provider 配置

type ProviderKind added in v1.18.0

type ProviderKind string

ProviderKind 协议种类。取值进 env(OCTO_OIDC_PROVIDER_KIND)与 metric label, 因此用稳定的小写标识,不带厂商名。

const (
	// KindOIDC 标准 OpenID Connect(Discovery + id_token + JWKS)。
	KindOIDC ProviderKind = "oidc"
	// KindOAuth2 只有 OAuth2 authorization_code 的 IdP:无 Discovery、无
	// id_token、无 JWKS,access_token 为不透明串,/userinfo 为厂商私有信封。
	KindOAuth2 ProviderKind = "oauth2"
)

type RedeemedBearerJWT added in v1.18.0

type RedeemedBearerJWT struct {
	Claims    *IdentityClaims
	IssuedAt  time.Time
	ExpiresAt time.Time
}

RedeemedBearerJWT 一张通过验签的兑换凭据:身份,加上判定新鲜度所需的两个时间戳。

为什么要把 iat/exp 一起带出来:新鲜度不再由验签器判定(见 VerifyForRedemption), 判定方是 redemption_ledger.go,它需要 iat 算首次兑换上限、需要 exp 定台账记录的 寿命。让调用方为此再解一次 payload,等于第二处 JWT 解析 —— 两处对同一张 token 得出不同的 iat,判定就无从谈起。

type RedisTickLock

type RedisTickLock struct {
	// contains filtered or unexported fields
}

RedisTickLock 用 Redis SET NX EX + Lua CAS-DEL 实现 tickLock。

持有独立 *redis.Client 与 redisStateStore 同样的理由(详见该文件): dmwork-lib 的 Redis wrapper 不暴露 Eval/SETNX 等高级原语。

func (*RedisTickLock) Acquire

func (l *RedisTickLock) Acquire(_ context.Context, key, token string, ttl time.Duration) (bool, error)

Acquire 用 SET NX EX 原子抢锁。token 后续 Release 校验用,必须每次新生成。

返回 (true, nil)=抢到, (false, nil)=别人持锁(正常竞争), (_, err)=Redis 故障。

func (*RedisTickLock) Close

func (l *RedisTickLock) Close() error

Close 释放底层连接池。

func (*RedisTickLock) Release

func (l *RedisTickLock) Release(_ context.Context, key, token string) (bool, error)

Release 走 Lua CAS-DEL,只在 token 匹配时释放。

返回 (true, nil)=成功释放, (false, nil)=token 不匹配 / key 已过期(都视为 正常,不报错), (_, err)=Redis 故障。

type RefreshModel

type RefreshModel struct {
	IdentityID      int64
	TokenHash       string
	TokenCiphertext []byte
	ExpiresAt       time.Time
	LastRefreshedAt *time.Time
	RevokedAt       *time.Time
	db.BaseModel
}

RefreshModel OIDC refresh_token 的加密存储,用于后台状态同步轮询

type RefreshResult

type RefreshResult struct {
	AccessToken  string
	RefreshToken string
	ExpiresAt    time.Time
}

RefreshResult Refresh 成功返回的最小子集。

AccessToken 用于 YUJ-405:rotate 成功后立刻用新 access_token 调 /userinfo 同步实名 claims。旧调用路径(单纯 RT 轮转)忽略 AccessToken 即可。

type ResolveResult

type ResolveResult struct {
	UID   string
	IsNew bool
}

ResolveResult ResolveOrLink 的结果(UID + 是否新创建)。

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service OIDC 业务编排层。

职责:

  1. ResolveOrLink — 把 IdP claims 解析为 dmwork uid(必要时建账或绑定历史账号)
  2. IssueSession — 调 user.IService.LoginByExternalIdentity 签发会话

func (*Service) IssueSession

func (s *Service) IssueSession(ctx context.Context, req IssueSessionReq) (*IssueSessionResp, error)

IssueSession 委托给 user.IService.LoginByExternalIdentity 签发会话。

只是个薄壳:负责把 oidc IssueSessionReq 透传到 userLookup,真正逻辑(token / IM token / 创建用户)在 user 模块。返回的 LoginRespJSON 由 callback 直接落 ThirdAuthcode Redis,前端短码轮询取走。

func (s *Service) ResolveOrLink(ctx context.Context, claims *IDTokenClaims) (*ResolveResult, error)

ResolveOrLink Issue #1120 的历史账号绑定矩阵。

规则(按顺序短路):

  • 1. (issuer, sub) 命中已绑定 identity 行 → 返回原 UID(场景 3:重复登录)

  • 2. AutoLinkByEmail=true && claims.email_verified: a. user.email 命中 1 条 → 写绑定 → 返回该 UID(场景 3:首次绑历史账号) b. user.email 命中多条 → ErrConflictNeedManual(场景 4:脏数据冲突) c. 未命中 → 走 step 3

  • 3. user.phone 同上(命中 1 / 多条 / 未命中)

  • 4. AllowNewUser=true → 不写本地 user 表,只返回 IsNew=true 让 IssueSession 创建 (避免 service 层直接持 user.IService 写权限,职责更清)

  • 5. AllowNewUser=false → ErrUnknownUser

返回 IsNew=true 时 UID 为空,由 IssueSession 通过 user.IService 创建并回填。

type StateData

type StateData struct {
	Provider     string    `json:"provider"`
	CodeVerifier string    `json:"code_verifier"`
	Nonce        string    `json:"nonce"`
	IP           string    `json:"ip"`
	UserAgent    string    `json:"user_agent"`
	ReturnTo     string    `json:"return_to"`
	CreatedAt    time.Time `json:"created_at"`

	// ClientAuthcode 前端在 /authorize 阶段传入的短码,callback 完成后用作 ThirdAuthcode
	// Redis key 的后半段,前端按 GitHub 模式短码轮询取 LoginRespJSON。
	ClientAuthcode string `json:"client_authcode,omitempty"`
	// DeviceFlag 调用方期望的设备类型,透传给 IssueSession。
	// 取值与 octo-lib config.DeviceFlag 一致(iota 顺序):0=APP / 1=Web / 2=PC。
	DeviceFlag uint8 `json:"device_flag,omitempty"`
}

StateData OIDC authorize → callback 之间的临时状态(/authorize 时写入,/callback 时一次性消费)

type StateStore

type StateStore interface {
	Save(ctx context.Context, state string, data *StateData, ttl time.Duration) error
	// Consume 取出并删除,实现 CSRF 防护的一次性语义
	Consume(ctx context.Context, state string) (*StateData, error)
}

StateStore 状态存储抽象,生产用 Redis,测试用内存

type SyncWorker

type SyncWorker struct {
	log.Log
	// contains filtered or unexported fields
}

SyncWorker 周期性 refresh active RT,失败即吊销 + 踢线 + 审计。

func NewSyncWorker

func NewSyncWorker(cfg SyncWorkerConfig, store syncStore, enc *Encryptor,
	rfsh refresher, killer sessionKiller, audit auditWriter, lock tickLock) *SyncWorker

NewSyncWorker 构造 worker,并发 / 批大小 / 锁 TTL 有兜底默认值。

lock 传 nil 时退化为"每实例独立 tick" —— rowsAffected 竞态检测仍能保证 不出假阳性踢线,只是 IdP 流量翻 N 倍。生产部署建议注入 RedisTickLock。

ui / verif 可选(nil 时 sync_worker 跳过实名同步,保持 YUJ-405 前的原行为)。

func (*SyncWorker) RunOnce

func (w *SyncWorker) RunOnce(ctx context.Context) error

RunOnce 执行一次同步:拉一批 → 受 Concurrency 限的并发处理。

多实例部署:抢到 tick lock 才跑,抢不到直接返回 nil(本 tick 由别人跑)。 lock 不可用时降级为"每实例独立跑",依赖 rowsAffected 竞态检测兜底。

ctx 取消时已派发的 goroutine 仍会跑完当前 RT(processOne 内部 best-effort), 但不再派发新任务。返回 ctx.Err() 让上层日志可识别 "正常停机" vs "异常失败"。

func (*SyncWorker) Start

func (w *SyncWorker) Start(ctx context.Context)

Start 启动后台 ticker goroutine。Interval ≤ 0 视为禁用。

真幂等:重复调用会先 Stop 旧 goroutine 再启动新的,避免泄漏。 生产路径只在模块 Init 中调一次,这里的幂等是防误用(测试 / 配置热更等)。

func (*SyncWorker) Stop

func (w *SyncWorker) Stop()

Stop 通知 worker 退出并等待所有进行中的刷新完成。

func (*SyncWorker) WithVerificationSync

func (w *SyncWorker) WithVerificationSync(ui userInfoFetcher, verif verificationUpserter) *SyncWorker

WithVerificationSync 注入 /userinfo + upsert 依赖,启用 YUJ-405 的实名 sync 路径。 生产路径在 OIDC.Init 中调用;传 nil 保持原行为(不做实名同步)。

type SyncWorkerConfig

type SyncWorkerConfig struct {
	Interval    time.Duration // ≤ 0 视为禁用,Start 直接返回
	Concurrency int           // 单批内并发刷新数量上限
	BatchSize   int           // 单 tick 拉取条数

	// LockKey / LockTTL 控制多实例 tick 级互斥(详见 sync_lock.go)。
	// 仅当 worker 注入了非 nil 的 tickLock 时生效。
	// LockTTL 默认 = Interval:lock 持有期不超过一个 tick 周期,
	// 实例崩溃 → TTL 自动到期 → 下个 tick 自然恢复。
	LockKey string
	LockTTL time.Duration
}

SyncWorkerConfig SyncWorker 调度参数。

type TokenSet added in v1.18.0

type TokenSet struct {
	AccessToken  string
	TokenType    string
	RefreshToken string
	Expiry       time.Time
	// RawIDToken 为空即该 provider 不下发 id_token。
	RawIDToken string
}

TokenSet 换码结果的协议中立表示。

存在的意义是不让 *oauth2.Token 穿透到 handler:一旦穿透,api.go 就会通过 tok.Extra("id_token") 之类的调用与 oauth2 库形成隐式耦合。

type UserInfoClaims

type UserInfoClaims struct {
	Subject       string `json:"sub"`
	Email         string `json:"email"`
	EmailVerified bool   `json:"email_verified"`
	PhoneNumber   string `json:"phone_number"`
	PhoneVerified bool   `json:"phone_number_verified"`
	Name          string `json:"name"`

	// identity_verification scope 字段。类型与 IDTokenClaims 一致(POC 实测 + bool/number/string 兜底)。
	IsVerified       IsVerifiedClaim `json:"is_verified"`
	VerifiedAt       VerifiedAtClaim `json:"verified_at"`
	VerifiedProvider string          `json:"verified_provider"`
	LegalName        string          `json:"legal_name"`
	LegalEmail       string          `json:"legal_email"`
}

UserInfoClaims /userinfo 端点返回的 claims(子集,与 IDTokenClaims 交集字段)。

/userinfo 比 ID Token 通常更新(IdP 侧后台变更可立即反映), 是登录后做"账户信息同步"的权威源。

identity_verification scope 下的 5 个字段也从 /userinfo 解出:部分 Aegis 部署把它们放 ID Token,另一些只在 /userinfo 暴露,拉完 /userinfo 后由 callback 合并到 IDTokenClaims(YUJ-382 codex review 点)。

type VerifiedAtClaim

type VerifiedAtClaim int64

VerifiedAtClaim 兜底 verified_at 的 number / string 两种序列化形态(Unix 秒)。

背景:Aegis 当前实测返 JSON number(Unix 秒),但:

  • 部分 IdP 管理后台把数字类型 claim 落成 string("1778331902")
  • 某些前置网关把大数用 JSON number 下发时会变成 JS float(1.778e9), Go 直接 Unmarshal 成 int64 会 TypeError(float64 不能收 int64)

处理:接 int64 / float64 / string("123")/ null / 缺字段。非法值返回 0, 下游 hasCompleteVerificationClaims / UpsertVerificationFromOIDC 已在 VerifiedAt<=0 分支拒写库,不会污染 user_verification 表。

func (VerifiedAtClaim) Int64

func (c VerifiedAtClaim) Int64() int64

Int64 返回内部 Unix 秒(与 time.Unix(sec, 0) 对齐)。

func (*VerifiedAtClaim) UnmarshalJSON

func (c *VerifiedAtClaim) UnmarshalJSON(data []byte) error

Jump to

Keyboard shortcuts

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