Nebula Auth 配置说明
1. 配置总览
nebula-auth 的配置来源主要分成三类:
- 静态 Spring Boot 配置项:以
nebula.auth.*为主 - 动态登录参数:通过参数中心读取
auth.login.* - 独立服务运行配置:如端口、数据源、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
可选值:
localremote
作用:
local:启用本地控制器与本地 service 实现remote:当前应用作为 auth 服务消费者,通过 remote 层转调
2.2 nebula.auth.excluded-paths
作用:
- 在框架固定白名单之外,追加开放接口路径
说明:
- 固定白名单已经包含登录、注册、刷新令牌、认证初始化和部分微信登录接口
- Swagger 文档路径也会自动加入白名单
- 这里适合按项目需要增加公共接口
2.3 nebula.auth.token.*
| 配置项 | 说明 | 默认值 |
|---|---|---|
nebula.auth.token.access-token-expire | access token 过期时长,单位秒 | 7200 |
nebula.auth.token.refresh-token-expire | refresh token 过期时长,单位秒 | 604800 |
nebula.auth.token.header | token 请求头名 | Authorization |
nebula.auth.token.algorithm | JWT 签名算法 | HmacSHA256 |
nebula.auth.token.secret-key | base64 编码后的密钥 | 默认内置值 |
建议:
- 生产环境务必替换
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-allowed | OAuth2 登录后是否允许自动注册 / 自动开通 |
自动建号用户的默认角色 / 默认组织不是静态配置项,而是参数中心的系统参数 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-id | OAuth2 客户端 ID |
client-secret | OAuth2 客户端密钥 |
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-seconds | access_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.enabled | OAuth2 总开关,微信登录要求同时为 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.javanebula-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 两套接入层