跳到主要内容

Nebula Auth 配置说明

1. 配置总览​

nebula-auth 的配置来源主要分成三类:

  1. 静态 Spring Boot 配置项:以 nebula.auth.* 为主
  2. 动态登录参数:通过参数中心读取 auth.login.*
  3. 独立服务运行配置:如端口、数据源、Redis、MyBatis 等

理解这三类配置的边界很重要:

  • nebula.auth.* 决定 auth 模块如何运行
  • auth.login.* 决定登录开关、注册策略和锁定策略
  • application.yml 决定独立 auth 服务如何启动

2. nebula.auth.* 核心配置​

对应源码:

  • nebula-auth-core/src/main/java/com/cludix/nebula/auth/config/AuthProperties.java

基础示例:

nebula:
auth:
mode: local
excluded-paths:
- /api/demo/public
token:
access-token-expire: 7200
refresh-token-expire: 604800
header: Authorization
algorithm: HmacSHA256
secret-key: Xtzlos2FEi5jVzqMAjAWUAhtD7rw6btGek0+pUTHxxA=
password:
salt-length: 8
remote:
service-name: nebula-auth-service
service-url: http://localhost:17778
oauth2:
enabled: false
register-allowed: true

2.1 nebula.auth.mode​

可选值:

  • local
  • remote

作用:

  • local:启用本地控制器与本地 service 实现
  • remote:当前应用作为 auth 服务消费者,通过 remote 层转调

2.2 nebula.auth.excluded-paths​

作用:

  • 在框架固定白名单之外,追加开放接口路径

说明:

  • 固定白名单已经包含登录、注册、刷新令牌、认证初始化和部分微信登录接口
  • Swagger 文档路径也会自动加入白名单
  • 这里适合按项目需要增加公共接口

2.3 nebula.auth.token.*​

配置项说明默认值
nebula.auth.token.access-token-expireaccess token 过期时长,单位秒7200
nebula.auth.token.refresh-token-expirerefresh token 过期时长,单位秒604800
nebula.auth.token.headertoken 请求头名Authorization
nebula.auth.token.algorithmJWT 签名算法HmacSHA256
nebula.auth.token.secret-keybase64 编码后的密钥默认内置值

建议:

  • 生产环境务必替换 secret-key
  • access-token-expire 不宜过长,便于降低泄漏风险
  • refresh-token-expire 应与前端续期策略匹配

2.4 nebula.auth.password.salt-length​

作用:

  • 控制 BCryptPasswordEncoder 的 strength

默认值:

  • 8

注意:

  • 代码中允许范围为 4 ~ 31
  • 超出该范围时会退回到 10
  • 值越高,密码哈希越安全,但 CPU 开销也更高

2.5 nebula.auth.remote.*​

配置项说明默认值
nebula.auth.remote.service-name远程 auth 服务名nebula-auth-service
nebula.auth.remote.service-url远程 auth 服务直连地址无

适用场景:

  • 微服务消费者通过服务发现访问 auth
  • 本地开发时通过固定 URL 直连独立 auth 服务

3. OAuth2 配置​

AuthProperties 中的 OAuth2 配置树如下:

nebula:
auth:
oauth2:
enabled: false
register-allowed: true
qq:
enabled: false
client-id:
client-secret:
authorize-url:
token-url:
user-info-url:
redirect-uri:
grant-type:
scope:
providers:
github:
enabled: false
client-id:
client-secret:
authorize-url:
token-url:
redirect-uri:
scope:
wechat:
enabled: false
mini:
app-id:
app-secret:
js-code2-session-url:
access-token-url:
phone-number-url:
web:
app-id:
app-secret:
authorize-url:
access-token-url:
redirect-uri:
scope:
frontend-callback-uri:
alipay:
enabled: false
client-id:
client-secret:
authorize-url:
token-url:
user-info-url:
redirect-uri:
grant-type:
scope:

3.1 顶层开关​

配置项说明
nebula.auth.oauth2.enabled是否启用 OAuth2 登录能力
nebula.auth.oauth2.register-allowedOAuth2 登录后是否允许自动注册 / 自动开通

自动建号用户的默认角色 / 默认组织不是静态配置项,而是参数中心的系统参数 login.oauth2.default-role-id / login.oauth2.default-org-id(见 §4.4);未设置(空值)时不绑定。绑定逻辑在 UserDefaultRoleOrgBinder,由所有自助注册建号路径在建号事务内调用(OAuth2 首登、用户名注册、手机号 / 邮箱验证码首次登录)。

3.2 QQ / 支付宝通用 OAuth2 客户端配置​

适用于:

  • nebula.auth.oauth2.qq.*
  • nebula.auth.oauth2.alipay.*

字段说明:

配置项说明
enabled提供商开关
client-idOAuth2 客户端 ID
client-secretOAuth2 客户端密钥
authorize-url授权地址
token-url令牌地址
user-info-url用户信息地址
redirect-uri回调地址
grant-type授权类型
scope授权范围

3.3 微信登录配置(nebula.auth.oauth2.providers.wechat.*)​

微信统一为一个 provider(providerId wechat),凭据按接入渠道分两级:

  • mini —— 小程序渠道:wx.login() 直连式登录,无浏览器重定向
  • web —— 开放平台「网站应用」渠道(网页应用):connect/qrconnect 扫码授权,可用于 Web 登录与「已登录用户绑定」

顶层:

配置项说明默认值
nebula.auth.oauth2.providers.wechat.enabled微信登录总开关(静态装配开关)false
nebula.auth.oauth2.providers.wechat.access-token-safety-margin-secondsaccess_token 缓存提前失效余量(秒)300

小程序渠道(mini):

配置项说明默认值
mini.app-id小程序 AppID无
mini.app-secret小程序 AppSecret,必须环境变量注入无
mini.js-code2-session-url授权码换会话接口https://api.weixin.qq.com/sns/jscode2session
mini.access-token-url接口调用凭证接口(手机号能力依赖)https://api.weixin.qq.com/cgi-bin/token
mini.phone-number-url手机号获取接口https://api.weixin.qq.com/wxa/business/getuserphonenumber

网页应用渠道(web):

配置项说明默认值
web.app-id网站应用 AppID无
web.app-secret网站应用 AppSecret,必须环境变量注入无
web.authorize-url扫码授权页地址https://open.weixin.qq.com/connect/qrconnect
web.access-token-url授权码换 token 接口https://api.weixin.qq.com/sns/oauth2/access_token
web.redirect-uri微信侧回调地址,须与开放平台后台授权回调域一致无(启用网页应用渠道时必填)
web.scope授权作用域snsapi_login
web.frontend-callback-uri扫码登录完成后前端承接页地址/login/wechat-callback

校验规则:

  • enabled=true 时 mini 与 web 至少一个渠道配置完整,否则启动失败
  • 渠道配置完整即参与装配:仅配 mini 时绑定能力不可用,配齐 web 后个人信息页出现微信绑定入口

环境变量参考(推荐注入方式):

nebula:
auth:
oauth2:
providers:
wechat:
enabled: ${NEBULA_AUTH_WECHAT_ENABLED:false}
mini:
app-id: ${NEBULA_AUTH_WECHAT_MINI_APP_ID:}
app-secret: ${NEBULA_AUTH_WECHAT_MINI_APP_SECRET:}
web:
app-id: ${NEBULA_AUTH_WECHAT_WEB_APP_ID:}
app-secret: ${NEBULA_AUTH_WECHAT_WEB_APP_SECRET:}
redirect-uri: ${NEBULA_AUTH_WECHAT_WEB_REDIRECT_URI:}
frontend-callback-uri: ${NEBULA_AUTH_WECHAT_WEB_FRONTEND_CALLBACK_URI:/login/wechat-callback}

3.4 微信登录运行时开关(系统参数)​

静态 enabled 只管「装配不装配」,用户能否用微信登录以参数中心的系统参数为准:

参数键说明
login.oauth2.enabledOAuth2 总开关,微信登录要求同时为 true
login.oauth2.provider.wechat.enabled微信登录开关(小程序 + 扫码共用),默认 false

该开关可在管理端「高级配置 → 通用配置 → 第三方登录(OAuth2)」运行时切换。


4. 动态登录参数(参数中心 login.* / auth.login.*)​

除了 nebula.auth.* 之外,登录初始化配置还依赖参数中心中的动态参数。

对应源码:

  • nebula-auth-core/src/main/java/com/cludix/nebula/auth/config/AuthLoginParamKeys.java
  • nebula-auth-core/src/main/java/com/cludix/nebula/auth/service/AuthLoginConfigSupport.java

这些参数不是写在 AuthProperties 里,而是运行期通过 ISystemParamService 获取。

4.1 用户名登录相关​

参数键说明
auth.login.username.allow-register是否允许用户名注册
auth.login.username.password-min-length用户名登录密码最小长度
auth.login.username.password-max-length用户名登录密码最大长度
auth.login.username.login-fail-max-count最大连续失败次数
auth.login.username.lock-time-hours锁定时长(小时)

4.2 手机登录相关​

参数键说明
auth.login.phone.enabled是否启用手机号登录
auth.login.phone.allow-register是否允许手机号注册
auth.login.phone.code-expire-minutes手机验证码有效期(分钟)
auth.login.phone.send-interval-seconds手机验证码发送间隔(秒)

4.3 邮箱登录相关​

参数键说明
auth.login.email.enabled是否启用邮箱登录
auth.login.email.allow-register是否允许邮箱注册
auth.login.email.code-expire-minutes邮箱验证码有效期(分钟)
auth.login.email.send-interval-seconds邮箱验证码发送间隔(秒)

4.4 OAuth2 登录相关​

参数键说明
login.oauth2.enabled是否启用 OAuth2 登录
login.oauth2.allow-register是否允许 OAuth2 自动注册
login.oauth2.default-role-id自助注册建号绑定的默认角色 ID(角色须已存在,否则建号失败);留空则不绑定角色。键名保留历史前缀 login.oauth2.,但作用域是全部自助注册建号,不是只给 OAuth2 用
login.oauth2.default-org-id自助注册建号绑定的默认组织 ID(组织须已存在,否则建号失败,并以「主组织」写入);留空则不绑定组织。键名说明同上
login.oauth2.provider.github.enabled是否启用 GitHub 登录
login.oauth2.provider.wechat.enabled是否启用微信登录(小程序 + 扫码共用)

说明:

  • 默认角色 / 组织在同一个创建事务内同步绑定(不是靠监听建号事件),因为登录在创建用户后会紧接着签发会话,事件却在提交后才派发,届时不绑定就没机会了。绑定收敛在 UserDefaultRoleOrgBinder,四个自助注册建号点(OAuth2 自动开通、用户名注册、手机号首次登录建号、邮箱首次登录建号)都会调用;后台「用户管理」建号不受影响(由管理员显式选择角色)。
  • 参数是单一开关:接上一条,它同时作用于全部自助注册入口。只想给其中一类入口绑角色时用入口开关收窄(login.username.allow-register / login.phone.allow-register / login.email.allow-register / login.oauth2.allow-register),本版没有按来源分开的默认角色参数。
  • 配了但角色 / 组织不存在时快速失败(ROLE_NOT_FOUND / ORG_NOT_FOUND)并回滚建号,不静默建出无角色账号。

说明:

  • GET /api/auth/get-auth-config 返回给前端的初始化配置,主要就是基于这些动态参数拼装出来的
  • 如果这些参数缺失,登录初始化或相关登录流程会抛出参数缺失异常

5. Spring Security 相关固定行为​

虽然不是所有安全策略都通过配置项暴露,但当前 SecurityConfig 中有一些固定行为需要在文档里明确:

5.1 固定白名单路径​

框架固定放行的认证接口包括:

  • /api/auth/get-auth-config
  • /api/auth/login
  • /api/auth/wechat/mini-login
  • /api/auth/wechat/web/redirect/prepare
  • /api/auth/wechat/web/redirect/callback
  • /api/auth/wechat/web/status
  • /api/auth/wechat/web/callback
  • /api/auth/refresh
  • /api/auth/register
  • /api/frontend/init
  • /api/storage/download-signed

5.2 安全链之外直接忽略的路径​

当前直接绕过 Spring Security 的路径包括:

  • /actuator/**
  • /error
  • /health

这意味着这些路径不是“permitAll 后再经过过滤器”,而是根本不进入 Spring Security。


6. 缓存相关配置语义​

AuthCacheDefinitionConfiguration 里有两项关键缓存定义:

缓存域TTL 来源
用户上下文缓存跟随 nebula.auth.token.access-token-expire
微信网站登录状态缓存固定 600 秒

说明:

  • 用户上下文缓存过期时间与 access token 保持一致
  • 微信网站扫码登录状态属于短时流程态缓存,过期较快是合理设计

7. 独立服务配置示例​

对应文件:

  • nebula-auth-service/src/main/resources/application.yml

当前示例配置如下:

server:
port: 17778

spring:
data:
redis:
host: 192.168.1.28
port: 6379
database: 0
datasource:
driver-class-name: com.mysql.cj.jdbc.Driver
url: jdbc:mysql://192.168.1.28:3306/nebula?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true
username: root
password: cludix-mysql-pwd
type: com.alibaba.druid.pool.DruidDataSource

nebula:
architecture:
mode: remote
auth:
mode: local
param:
mode: remote
web:
result-advice-enable: true
cache:
type: caffeine
default-ttl: 300

mybatis-plus:
configuration:
map-underscore-to-camel-case: true
log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
global-config:
db-config:
table-underline: true
id-type: assign_uuid
mapper-locations: classpath*:mapper/*.xml

从这个示例可以得到几个结论:

  • auth 独立服务默认监听 17778
  • 独立服务自身仍然运行本地 auth 实现,即 nebula.auth.mode=local
  • 参数中心模式当前示例为 nebula.param.mode=remote
  • 认证中心依赖 MySQL 与 Redis

注意:这里的 IP、账号和密码属于示例环境信息,不应直接照搬到生产环境。


8. 推荐配置建议​

8.1 单体应用​

推荐:

nebula:
auth:
mode: local

并引入:

  • nebula-auth-local

8.2 微服务消费者​

推荐:

nebula:
auth:
mode: remote
remote:
service-name: nebula-auth-service
service-url: http://localhost:17778

并引入:

  • nebula-auth-remote

8.3 生产环境注意事项​

建议重点检查:

  • 替换 JWT secret-key
  • 调整 token 过期时间
  • 配好 OAuth2 提供商密钥与回调地址
  • 补齐参数中心中的 auth.login.* 动态参数
  • 不要同时引入 local 与 remote 两套接入层