NocoBase Auth 认证抽象类全解析从接口契约到自定义认证类型的落地实现【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobaseAuth是 NocoBase 用户认证体系的抽象基类定义了所有认证类型密码、短信、OIDC、SAML 等必须遵守的统一接口契约。本文以 Auth API 文档 为核心骨架结合nocobase/auth包的源码实现与plugin-auth插件中的真实用例系统讲解Auth的接口定义、构造函数配置、四个核心方法check/signIn/signUp/signOut以及基于它扩展自定义认证类型的完整路径。读完本文你将掌握 NocoBase 认证插件的底层工作原理并能独立实现一套新的认证方式。概览Auth在 NocoBase 认证体系中的定位NocoBase 的认证体系由三层结构组成Auth位于最底层AuthManager认证管理器负责注册认证类型registerTypes、通过认证器标识获取对应实例get并提供挂载到请求链路的鉴权中间件middleware见 auth-manager.ts 与 AuthManager 文档Auth抽象类用户认证类型的抽象定义完成用户认证所需的接口。扩展新的用户认证类型必须继承Auth并实现其中的方法BaseAuthAuth的基础实现以 JWT 作为鉴权方式提供了可直接复用的 token 签发、校验、续期、注销等能力。大多数情况下扩展认证类型继承BaseAuth即可见 BaseAuth 文档。文档中给出的核心抽象定义如下对应源码 auth.tsinterface IAuth { user: Model; // Check the authenticaiton status and return the current user. check(): PromiseModel; signIn(): Promiseany; signUp(): Promiseany; signOut(): Promiseany; } export abstract class Auth implements IAuth { abstract user: Model; abstract check(): PromiseModel; // ... }IAuth接口定义了五个契约成员user属性承载认证用户信息check负责鉴权signIn/signUp/signOut对应登录、注册、注销。需要特别注意的是在 auth.ts 的实际源码中IAuth还额外声明了syncCookies(): Promiseunknown方法用于在刷新 token 后同步浏览器 Cookie这也是实现自定义认证类型时可选覆盖的钩子。实例属性useruser用于承载当前认证用户信息在抽象类中以抽象属性形式声明签名abstract user: ModelModel是 NocoBase 数据库层的模型实例来自nocobase/database在BaseAuth中的默认存取实现为读写请求上下文中的ctx.state.currentUser见 base/auth.tsset user(user: Model) { this.ctx.state.currentUser user; } get user() { return this.ctx.state.currentUser; }鉴权中间件在check()通过后会把返回的用户写入ctx.auth.user见 auth-manager.ts后续业务代码即可通过ctx.auth.user读取当前登录用户。构造函数与AuthConfig配置Auth的构造函数签名constructor(config: AuthConfig)AuthConfig类型定义源码见 auth.tsexport type AuthConfig { authenticator: Authenticator; options: { [key: string]: any; }; ctx: Context; };各字段说明属性类型描述authenticatorAuthenticator认证器数据模型即存储在authenticators数据表中的配置记录AuthModeloptionsRecordstring, any认证器相关配置ctxContextKoa 请求上下文从源码看构造函数只是简单地把三个字段保存为受保护属性auth.tsconstructor(config: AuthConfig) { const { authenticator, options, ctx } config; this.authenticator authenticator; this.options options; this.ctx ctx; }在实际应用中AuthManager通过createAuth方法把从存储层取出的认证器与当前请求上下文组装成认证实例auth-manager.tsprivate createAuth(authenticator: Authenticator, ctx: Context) { const { auth } this.authTypes.get(authenticator.authType) || {}; if (!auth) { throw new Error(AuthType [${authenticator.authType}] is not found.); } return new auth({ authenticator, options: authenticator.options, ctx }); }这意味着options实际上就是认证器配置记录中的options字段在 NocoBase 管理后台配置认证器时填写的各项参数如是否允许注册、邮件模板等都会以this.options的形式透传给认证类的业务方法。类方法详解check()用户鉴权必须实现签名abstract check(): PromiseModelcheck是所有认证类型都必须实现的抽象方法其职责是校验当前请求携带的凭证token返回用户信息。在BaseAuth中check的实现分两步checkToken()解析请求头Authorization: Bearer token中的 token判定其状态为valid/expired/invalid并校验用户是否存在base/auth.ts。校验逻辑包括token 为空抛出EMPTY_TOKEN用户不存在抛出NOT_EXIST_USERtoken 在 JWT 黑名单中抛出BLOCKED_TOKEN会话过期抛出EXPIRED_SESSION修改密码后旧 token 失效等token 续期当 token 状态为expired且未超过expiredTokenRenewLimit时通过tokenController.renew(jti)换发新 token并通过x-new-token响应头与authTokenCookie 下发base/auth.ts。这里涉及三个关键服务均挂在ctx.app.authManager上JwtServicejwt-service.ts封装jsonwebtoken的签发与校验默认有效期7d可通过JWT_EXPIRES_IN环境变量或AuthManagerOptions.jwt.expiresIn覆盖ITokenControlServicetoken-control-service.ts管理 token 策略tokenExpirationTime、sessionExpirationTime、expiredTokenRenewLimit与 token 记录jtiITokenBlacklistServicetoken 黑名单用于注销后立即失效。signIn()用户登录签名signIn(): PromiseanysignIn负责完成登录流程。BaseAuth中的流程为base/auth.ts调用子类实现的validate()校验凭证账号密码、短信验证码等失败则抛出 401通过signNewToken(userId)调用tokenController.add()登记 token 信息并签发 JWTbase/auth.tssetAuthCookies()写入authToken、authenticatorCookiesetSessionCookies()写入csrfToken、roleCookie返回{ user, token }。signUp()用户注册签名signUp(): PromiseanysignUp负责创建新用户。注意在BaseAuth中它是空实现base/auth.ts是否支持注册、注册表单包含哪些字段完全由具体认证类型决定。例如BasicAuth.signUp()会先检查认证器配置的options.public.allowSignUp再按注册表单设置校验用户名/邮箱格式与必填项、两次密码一致性最后创建用户basic-auth.ts。signOut()用户注销登录签名signOut(): PromiseanyBaseAuth.signOut()的执行步骤为base/auth.ts清除authToken、authenticator、role、csrfToken等全部认证 Cookie删除用户缓存与角色缓存最后把当前 token 加入黑名单jwt.block(token)使其立即失效。异常体系AuthError与AuthErrorCode源码中为认证流程定义了统一的异常类型与错误码auth.tsexport const AuthErrorCode { EMPTY_TOKEN: EMPTY_TOKEN as const, EXPIRED_TOKEN: EXPIRED_TOKEN as const, INVALID_TOKEN: INVALID_TOKEN as const, TOKEN_RENEW_FAILED: TOKEN_RENEW_FAILED as const, BLOCKED_TOKEN: BLOCKED_TOKEN as const, EXPIRED_SESSION: EXPIRED_SESSION as const, NOT_EXIST_USER: NOT_EXIST_USER as const, SKIP_TOKEN_RENEW: SKIP_TOKEN_RENEW as const, }; export class AuthError extends Error { code: AuthErrorType; constructor(options: { code: AuthErrorType; message: string }) { super(options.message); this.code options.code; } }错误码含义EMPTY_TOKEN请求未携带 tokenEXPIRED_TOKENtoken 已过期JWT 层INVALID_TOKENtoken 无效签名错误、格式非法等TOKEN_RENEW_FAILEDtoken 续期失败BLOCKED_TOKENtoken 已被加入黑名单EXPIRED_SESSION会话过期超过sessionExpirationTimeNOT_EXIST_USERtoken 对应的用户不存在SKIP_TOKEN_RENEW跳过 token 续期如 SSE 流式请求场景实现自定义认证类型时可复用这些错误码并通过ctx.throw(401, { code, message })抛出保证前后端错误处理口径一致。实战基于Auth/BaseAuth扩展自定义认证类型官方推荐的最小扩展方式是继承BaseAuth。以plugin-auth插件内置的密码认证BasicAuth为例basic-auth.tsimport { AuthConfig, BaseAuth } from nocobase/auth; import { PasswordField } from nocobase/database; export class BasicAuth extends BaseAuth { static readonly optionsKeysNotAllowedInEnv [emailContentText, emailContentHTML, emailSubject]; constructor(config: AuthConfig) { const userCollection config.ctx.db.getCollection(users); super({ ...config, userCollection }); } // 用户认证逻辑由 signIn 调用返回用户数据 async validate() { const ctx this.ctx; const { account, email, password } ctx.action.params.values || {}; if (!account !email) { ctx.throw(400, ctx.t(Please enter your username or email)); } const filter email ? { email } : { $or: [{ username: account }, { email: account }] }; const user await this.userRepository.findOne({ filter }); if (!user) { ctx.throw(401, ctx.t(The username/email or password is incorrect, please re-enter)); } const field this.userCollection.getFieldPasswordField(password); const valid await field.verify(password, user.password); if (!valid) { ctx.throw(401, ctx.t(The username/email or password is incorrect, please re-enter)); } return user; } }关键点拆解构造函数中设置用户数据表通过config.ctx.db.getCollection(users)拿到用户集合传给super()这样BaseAuth内部就能通过this.userCollection.repository查询用户validate()是登录的鉴权核心由BaseAuth.signIn()调用返回用户模型即视为登录成功返回null或抛错则登录失败。这是自定义认证类型通常唯一必须实现的方法static optionsKeysNotAllowedInEnv声明哪些配置项不允许通过环境变量注入防止敏感信息如邮件正文模板被意外覆盖check/signIn/signOut全部复用BaseAuth的 JWT 实现无需重写 token 签发、续期、黑名单等基础设施逻辑。随后把认证类型注册到AuthManagerauth-manager.ts并挂载鉴权中间件const authManager new AuthManager({ authKey: X-Authenticator }); authManager.setStorer({ get: async (name: string) { return db.getRepository(authenticators).findOne({ filter: { name } }); }, }); authManager.registerTypes(basic, { auth: BasicAuth, title: Password, }); app.resourceManager.use(authManager.middleware());middleware()的处理顺序为auth-manager.ts按请求头X-Authenticator→authenticatorCookie → 默认认证器default: basic的优先级确定认证器标识调用ctx.app.authManager.get(name, ctx)构造认证实例若skipCheck()判定当前资源为公开访问如登录页、静态资源则直接放行否则调用ctx.auth.check()完成鉴权把用户写入ctx.auth.user后进入后续业务逻辑。小结Auth 方法职责速查表方法是否抽象职责BaseAuth 默认行为user是认证用户信息读写ctx.state.currentUsercheck()是鉴权返回用户校验 Bearer token支持过期续期signIn()否用户登录调validate()→ 签发 token → 写 CookiesignUp()否用户注册空实现由具体类型定义signOut()否注销登录清 Cookie、删缓存、token 入黑名单深入阅读建议Auth 抽象类源码、BaseAuth 实现源码、AuthManager 源码、认证中间件与动作定义、BaseAuth 测试用例、密码认证真实实现。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考