认证 on 姚玉亮的网络日志

微信、企业微信、飞书 OAuth 一键登录与账号绑定

Thu, 15 Aug 2024 10:30:00 +0800

三套流程，三种脾气

统一认证中心除了账号密码，还要接微信、企业微信、飞书的一键登录，而且得让同一个真人能把好几个第三方身份绑到同一个账号上。

麻烦在于，三家的 OAuth 流程看着相似，细节脾气完全不同：微信网页授权是 code 换 access_token，再拿 unionid；企业微信要 corpid + agentid，userid 只在企业内唯一；飞书走标准 OIDC 风格，还有个独立的 user_info 端点。

要是一个平台写一套独立 callback，维护成本扛不住。所以先定目标：抽象出统一的 Provider 接口，新增平台只实现接口，业务层不感知差异。

一个接口收编三个平台

接口就两个方法：AuthURL 生成跳转地址，Exchange 拿 code 换身份信息，返回统一的 Identity，平台类型、OpenID、UnionID、昵称、头像，都在里面。

账号绑定关系落在 user_identities 表，user_id + provider + provider_uid 联合唯一。登录时按 provider + uid 查这张表：查到，直接签发 JWT；查不到但当前已登录，走绑定流程；完全没账号，自动注册再绑上。

state 用 Redis 存 5 分钟，key 是随机 state，value 里带 redirect_uri 和操作类型（login 还是 bind）。既防 CSRF，回调时又能把上下文捞回来。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75


type Identity struct {
 Provider string
 OpenID string
 UnionID string
 Nickname string
 AvatarURL string
}

type IdentityProvider interface {
 AuthURL(state string) string
 Exchange(ctx context.Context, code string) (*Identity, error)
}

type OAuthHandler struct {
 db *gorm.DB
 rdb *redis.Client
 providers map[string]IdentityProvider
 sf *Snowflake
}

func (h *OAuthHandler) Callback(c *gin.Context) {
 state := c.Query("state")
 code := c.Query("code")

 metaStr, err := h.rdb.Get(c.Request.Context(), "oauth:state:"+state).Result()
 if err != nil {
 c.JSON(400, gin.H{"msg": "invalid or expired state"})
 return
 }
 h.rdb.Del(c.Request.Context(), "oauth:state:"+state)

 var meta struct {
 Provider string `json:"provider"`
 Redirect string `json:"redirect"`
 Action string `json:"action"`
 BindUserID int64 `json:"bind_user_id"`
 }
 json.Unmarshal([]byte(metaStr), &meta)

 p := h.providers[meta.Provider]
 ident, err := p.Exchange(c.Request.Context(), code)
 if err != nil {
 c.JSON(502, gin.H{"msg": "exchange failed"})
 return
 }

 var bind UserIdentity
 err = h.db.Where("provider = ? AND provider_uid = ?",
 ident.Provider, ident.OpenID).First(&bind).Error

 switch meta.Action {
 case "login":
 if errors.Is(err, gorm.ErrRecordNotFound) {
 uid, err := h.sf.NextID()
 if err != nil {
 c.JSON(500, gin.H{"msg": "id gen failed"})
 return
 }
 h.db.Create(&User{ID: uid, Nickname: ident.Nickname, Avatar: ident.AvatarURL})
 h.db.Create(&UserIdentity{
 UserID: uid, Provider: ident.Provider,
 ProviderUID: ident.OpenID, UnionID: ident.UnionID,
 })
 issueJWTAndRedirect(c, uid, meta.Redirect)
 return
 }
 issueJWTAndRedirect(c, bind.UserID, meta.Redirect)
 case "bind":
 h.db.Create(&UserIdentity{
 UserID: meta.BindUserID, Provider: ident.Provider,
 ProviderUID: ident.OpenID, UnionID: ident.UnionID,
 })
 c.Redirect(302, meta.Redirect)
 }
}

飞书 Provider 的 Exchange 大致是：

1
2
3
4
5
6
7
8


func (p *FeishuProvider) Exchange(ctx context.Context, code string) (*Identity, error) {
 resp, err := http.PostForm(p.TokenURL, url.Values{
 "app_id": {p.AppID}, "app_secret": {p.AppSecret},
 "grant_type": {"authorization_code"}, "code": {code},
 })
 // 解析 access_token，再请求 /open-apis/authen/v1/user_info
 // 略
}

各平台的坑

微信的 unionid 只有在开放平台绑定同主体应用后才会返回，网页授权单独拿不到。我们最初以为 openid 够用，结果同一个人在公众号和小程序之间对不上，后来补了 unionid 机制。

企业微信的 userid 是企业管理员导入的，OAuth 拿到的 userid 未必等于统一认证中心里的手机号，手动绑定入口省不掉。

自动注册体验好，副作用是一堆空壳账号。后来加了条策略：同一手机号已有账号的，提示登录后绑定，不直接新建。

state 必须一次性消费，回调里立刻 Del，防重放；只存 Redis 不写库，5 分钟过期自动清。

最后是 token 的琐碎账：飞书的 app_access_token 和 user_access_token 是两个东西，别拿错；企业微信的 access_token 有有效期和频次限制，得做缓存。

后来

三个平台收进一个 Provider 接口之后，再接钉钉或者自定义 OIDC 应用，实现两个方法就能上。账号绑定的核心就是 user_identities 这张关系表加 state 机制，剩下的活，是对各家文档细节的耐心。

封面图：Franck Michel / Flickr · CC BY 2.0

腾讯云 SMS/SES/Captcha 多租户通道按需切换实践

Sat, 29 Jun 2024 10:30:00 +0800

每家的通道配置都不一样

统一认证中心服务着多家客户和内部业务线：有的客户用自己报备的腾讯云账号，签名和模板都得单独申请；有的直接用平台统一账号。国内走短信，海外走 SES 邮件，不同应用的验证码模板也不一样。

所有租户挤在同一套腾讯云配置上，签名和模板就没法隔离，客户自己报备的签名也用不上。所以要在 Provider 抽象之上再加一层多租户通道，这件事没有绕开的余地。

一份配置对应一条通道

核心是一张 ChannelConfig 表：team_id + app_id + channel 三元组对应一份通道配置，存供应商类型、加密后的凭证、模板 ID、签名这些。发送时按请求上下文查到配置，从缓存里拿对应的 Provider 实例，没有就创建一个再缓存住，之后一直复用。

凭证安全是底线：AES-GCM 加密落库，主密钥从 KMS 或环境变量读取，明文不落盘。腾讯云 SDK 的 client 是并发安全的，按配置维度缓存复用就行，不必每个请求都新建。

发一次短信背后的查找

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


type ChannelConfig struct {
 ID int64 `gorm:"primaryKey"`
 TeamID int64 `gorm:"uniqueIndex:idx_ch"`
 AppID string `gorm:"uniqueIndex:idx_ch"`
 Channel string `gorm:"uniqueIndex:idx_ch"` // sms/email/captcha
 Provider string `gorm:"size:32"` // tencent_sms / tencent_ses
 ConfigEnc []byte // AES-GCM 加密的 JSON
 Status int8
}

type TencentSMSProvider struct {
 client *sms.Client
 appID string
 sign string
}

func strPtr(s string) *string { return &s }

func (p *TencentSMSProvider) Send(ctx context.Context,
 phone, tplID string, params map[string]string) error {

 req := sms.NewSendSmsRequest()
 req.SmsSdkAppId = strPtr(p.appID)
 req.SignName = strPtr(p.sign)
 req.TemplateId = strPtr(tplID)
 req.PhoneNumberSet = []*string{strPtr(phone)}
 // 腾讯云模板参数为有序数组，需按模板顺序传
 arr := make([]*string, 0, len(params))
 for _, v := range params {
 arr = append(arr, strPtr(v))
 }
 req.TemplateParamSet = arr
 _, err := p.client.SendSms(ctx, req)
 return err
}

Provider 缓存用 sync.Map，key 取配置内容的 hash。配置变更时更新数据库、删掉对应缓存 key，下一个请求自动重建。没有自定义配置的租户，回退到平台默认配置。

验证码这条链路前面还加了一道人机校验：接了腾讯云验证码，前端先拿到 ticket，后端调用腾讯云接口校验通过，才允许发验证码。人机验证之外，还配了频率限制。

三个教训

第一个是凭证加密，这条没得商量。最初 SecretKey 明文存数据库，安全评审直接打回来。改成 AES-GCM 加密之后，主密钥通过环境变量注入 Secret，代码里不出现任何硬编码。

第二个坑藏在腾讯云 SMS 的模板参数里：它是有序数组，不是 map。我们按 map 遍历传参，顺序不稳定，结果验证码和过期时间填反了。后来改成按模板定义的参数顺序显式构造数组，才算踏实。

第三个是频率限制。多租户共用默认账号时容易触发腾讯云限流，我们给默认通道加了令牌桶限流和告警，量大的客户引导他们换用自有账号。

后来

多租户通道切换做完，认证中心两头都照顾到了：想快速接入的用平台统一配置；要隔离的客户自带腾讯云账号，签名、凭证完全独立。加密存储、Provider 缓存、默认回退、人机校验，几个机制组合在一起，安全性和易用性都站住了，支撑住了多业务线和外部客户的验证码与通知需求。

封面图：Matthew Summerton / Wikimedia Commons · CC BY-SA 3.0

RBAC 权限模型：用户-团队-角色的设计与落地

Wed, 29 May 2024 10:30:00 +0800

权限模型五花八门

统一认证中心之前，有的系统把权限硬编码在代码里，有的用配置文件，还有的直接在数据库里存用户和菜单的关联。人员入职、换岗，得在每个系统分别改一遍权限；真到审计的时候，谁到底有什么权限，根本说不清。

所以要做的就是把用户、团队、角色、权限点收敛到统一认证中心一处管理，同时还得支撑前面说过的 AppRole 应用自治。

比经典 RBAC 多一层团队

经典 RBAC 是用户-角色-权限三层，我们在中间加了团队，变成用户-团队-角色-权限。核心实体四个：User、Team、Role、Permission。用户和团队多对多，进了团队之后，通过 TeamMember 关联一个或多个角色。角色分全局角色和 AppRole 两种；权限点用「资源:操作」的格式，比如 dataset:read、order:refund，角色绑定权限点，用户经由角色间接拿到权限。

还支持角色继承：team-admin 继承 team-viewer 的全部权限，管理员比普通成员多出一堆权限这种常见配置，就不用重复维护了。

查权限就是展开继承链

角色定义和角色-权限绑定是两张表：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


type Role struct {
 ID int64 `gorm:"primaryKey"`
 AppID string `gorm:"index"` // 空表示全局角色
 Code string `gorm:"size:64;uniqueIndex:idx_app_code"`
 Name string `gorm:"size:128"`
 ParentID int64 // 角色继承
 IsBuiltin bool
}

type RolePermission struct {
 RoleID int64 `gorm:"uniqueIndex:idx_role_perm"`
 Permission string `gorm:"uniqueIndex:idx_role_perm;size:64"`
}

func (s *Service) ListUserPermissions(ctx context.Context,
 userID, teamID int64, appID string) ([]string, error) {

 roles, err := s.memberDAO.ListRoles(ctx, teamID, userID, appID)
 if err != nil {
 return nil, err
 }
 // 展开继承链上的所有角色
 allRoles, err := s.roleDAO.ExpandWithParents(ctx, roles)
 if err != nil {
 return nil, err
 }
 return s.permDAO.ListByRoleIDs(ctx, allRoles)
}

ListUserPermissions 做的事不复杂：先查出用户在这个团队、这个应用上的角色，把继承链上的父角色全部展开，最后汇总权限点。

鉴权分两级。网关层做粗粒度：这个 Token 能不能访问这个路由，用 JWT 里带的角色信息判断就够。业务服务层做细粒度：能不能操作这条数据，通过 gRPC 调统一认证中心的 CheckPermission，或者读本地权限缓存。缓存用 Redis，key 是 perm:{teamID}:{userID}:{appID}，成员关系或角色变更时主动失效。

缓存这坑最深

权限缓存的一致性，是最初低估了的部分。成员变更时只删当前用户的缓存，这没问题；但角色权限变更时，得把这个角色下所有用户的缓存都删掉，用户一多就是缓存击穿。

后来改成版本号方案：每个团队的权限版本号存在 Redis，缓存 key 带上版本号，变更时递增版本，旧缓存自然过期。代价是新旧权限会有短暂的并存窗口，评估下来可以接受。

粒度是另一件要拿捏的事。权限点切得太细，配置维护成本高；太粗又起不到管控效果。我们的经验是按业务操作定义，一个接口一个权限点，特殊操作再细分。

后来

这套模型落地之后，人员的入转调离只需要在一处改权限，审计也能统一导出。配上 AppRole 的应用自治和带版本号的权限缓存，安全管控是统一的，业务线的灵活性也保住了。这套用户-团队-角色-权限的模型后来还复用到了 alchemy-furnace 开源项目里，换了个场景，依然适用。

AppRole 与应用团队隔离：多业务线权限自治的实现

Mon, 13 May 2024 10:30:00 +0800

角色表快撑不住了

统一认证中心接入的应用越来越多，权限模型先扛不住了。支付平台有运营、财务、商户管理员这些角色；数据治理服务有数据管理员、分析师；数据集管理服务又有自己的文档管理员。要是所有角色都放到认证中心全局定义，角色表迟早撑爆，而且业务线想调整自己的角色，还得来找认证中心团队，自治无从谈起。

我们需要一层「应用角色（AppRole）」：每个应用自己定义、自己管理角色，认证中心只负责团队隔离。

认证中心管边界，应用管角色

做法是把权限拆成两层。认证中心全局层只管团队（Team）和成员关系，应用层管 AppRole。一个用户在同一个团队里，对不同应用可以有不同角色：张三在数据中台团队里，对数据治理服务是 admin，对知识库问答就只是 viewer。

团队是隔离边界，数据、配置、成员都按 team_id 隔离，跨团队访问必须显式授权。AppRole 的角色编码（admin/editor/viewer 这类）和对应权限点由应用自己定义，认证中心只存绑定关系，不关心权限点具体是什么意思。

查权限就是查一次绑定

绑定关系就一张表，team_id、user_id、app_id 联合唯一，AppRole 字段存的是应用自己定义的角色编码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


type TeamMember struct {
 ID int64 `gorm:"primaryKey"`
 TeamID int64 `gorm:"uniqueIndex:idx_team_user_app"`
 UserID int64 `gorm:"uniqueIndex:idx_team_user_app"`
 AppID string `gorm:"uniqueIndex:idx_team_user_app"`
 AppRole string `gorm:"size:32"` // 应用自定义角色编码
}

func (s *Service) CheckPermission(ctx context.Context,
 userID, teamID int64, appID, perm string) bool {

 member, err := s.memberDAO.Get(ctx, teamID, userID, appID)
 if err != nil {
 return false
 }
 // 应用通过接口返回角色 -> 权限点映射
 perms, err := s.appProvider.GetPermissions(ctx, appID, member.AppRole)
 if err != nil {
 return false
 }
 for _, p := range perms {
 if p == perm || p == "*" {
 return true
 }
 }
 return false
}

CheckPermission 的逻辑很直白：查出用户在这个团队、这个应用上的角色，再向应用要这个角色对应的权限点列表，匹配上就放行。角色到权限点的映射由应用自己实现，认证中心不做解释。

JWT 里带了当前 team_id 和各应用的 role 映射，业务系统在本地就能做粗粒度鉴权，细粒度权限点再查认证中心或读缓存。团队隔离则下沉到 DAO 层强制：所有查询都带 team_id 条件，我们用 Gorm 的 Scopes 封了个 WithTeam，免得哪次手写漏了。

两个坑

第一个是切换团队。用户可能同时属于多个团队，但 Token 里只能放一个当前 team_id。最初想把所有团队都塞进 Token，团队一多就超过 HTTP 头大小限制了。后来改成 Token 只放当前团队，加了个 switch-team 接口重新签发，前端切团队时调一下。

第二个是自治带出来的小代价：AppRole 让应用自己定义之后，认证中心管理后台没法统一展示权限点了。解决办法是让应用注册一个权限元数据接口，认证中心拉取后展示。多了一次对接，换来自治，这笔账算得过来。

后来

AppRole 加 Team 的两层模型，说白了就是在全局管控和应用自治之间找平衡：认证中心管身份和团队边界，应用管自己的角色和权限点。后来支付平台、数据治理、知识库问答几条业务线先后接入，新应用进来定义好自己的角色就能用，认证中心的表结构不用动。

封面图：bfi Office Furniture / Flickr · CC BY-SA 2.0

多应用接入体系设计：AppID/AppSecret 与应用级 AccessToken

Sat, 27 Apr 2024 10:30:00 +0800

一套凭证共用，边界就没了

统一认证中心上线后，统一支付平台、数据治理服务、数据集管理服务、知识库问答服务等多个应用都要接入。这些应用形态不一：有的是前端 SPA，有的是后端服务间调用，还有第三方合作方的系统。如果共用一套 client 凭证，权限边界根本划不清，某个应用被攻破会波及所有系统，也没法按应用做限流和审计。

所以我们需要一套多应用接入体系，目标很明确：每个应用有独立身份、独立密钥、独立 Token，权限和配额都能按应用隔离。

每个应用一个身份

我们给每个接入应用签发全局唯一的 AppID（Snowflake 生成）和 AppSecret。AppSecret 在数据库里只存 bcrypt 哈希，创建时明文只返回一次。

应用有两种拿 Token 的方式。一是用户登录后拿用户级 Access Token，audience 绑定到该 AppID；二是服务间调用走 client_credentials，应用拿 AppID+AppSecret 去换应用级 Access Token。这种 Token 没有用户上下文，但带 app_role 和 scope，2 小时有效期，网关按 AppID 做独立限流。

AppToken：先验应用，再对哈希

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


type App struct {
 ID int64 `gorm:"primaryKey"`
 AppID string `gorm:"uniqueIndex;size:32"`
 SecretHash string `gorm:"size:128"`
 Name string `gorm:"size:128"`
 RedirectURI string `gorm:"size:512"`
 Scopes string `gorm:"size:512"` // 逗号分隔
 AppRole string `gorm:"size:32"`
 Status int8
}

func (s *Service) AppToken(ctx context.Context, appID, secret string) (*Token, error) {
 app, err := s.appDAO.GetByAppID(ctx, appID)
 if err != nil || app.Status != 1 {
 return nil, ErrInvalidApp
 }
 if err := bcrypt.CompareHashAndPassword(
 []byte(app.SecretHash), []byte(secret)); err != nil {
 return nil, ErrInvalidSecret
 }
 claims := &Claims{
 AppID: app.AppID,
 AppRole: app.AppRole,
 Scopes: strings.Split(app.Scopes, ","),
 RegisteredClaims: jwt.RegisteredClaims{
 Subject: app.AppID,
 Issuer: "passport",
 ExpiresAt: jwt.NewNumericDate(time.Now().Add(2 * time.Hour)),
 },
 }
 return s.issueToken(ctx, claims)
}

AppSecret 支持重置，重置后老 Secret 有 10 分钟宽限期，期间新旧都能用，给接入方留出平滑切换的时间。网关层按 AppID 配置独立 QPS 配额，免得一个应用把认证中心打满。

不存明文，也不要过大的权限

AppSecret 明文只展示一次，初期不少接入方抱怨"忘了存怎么办"。我们后来加了 Secret 重置流程，但坚决不在数据库存明文。

另一个坑是 client_credentials 拿到的 Token 权限过大：早期只认 AppID 就放行，后来强制应用级 Token 必须带 scope，网关按 scope 鉴权，遵循最小权限原则。

内部服务间调用我们考虑过 mTLS，运维成本高，放弃了。最终用的是 AppID/AppSecret 加短期 Token，配合内网隔离和 IP 白名单。

后来

AppID/AppSecret 是多应用接入的基础。独立身份让权限、限流、审计都能按应用维度切分；应用级 Access Token 解决了服务间调用的身份问题，但前提是配 scope 最小权限和短有效期。我们靠这套体系接入了公司内多个业务系统，新增应用只需要在管理后台创建、分配权限，认证中心的代码一行不用改。

封面图：kalleboo / Flickr · CC BY 2.0