OAUTH2

配置举例说明

# 是否启用OAuth2登录功能 参数选项true/false
Enable = true
# OAuth2登录方式在前端显示的名称
DisplayName = 'OAuth2登录'
# OAuth2认证成功后的重定向URL。这个URL应该是夜莺监控服务的回调地址
RedirectURL = 'http://n9e-server:port/callback/oauth'
# SSO服务的地址
SsoAddr = 'https://<authing-tenant-name>.authing.cn/oauth2/authorize'
# SSO登出地址，用于处理用户退出登录的请求
SsoLogoutAddr = 'https://<authing-tenant-name>.authing.cn/logout'
# SSO服务获取令牌的地址
TokenAddr = 'https://<authing-tenant-name>.authing.cn/oauth2/token'
# SSO服务获取用户信息的地址
UserInfoAddr = 'https://<authing-tenant-name>.authing.cn/userinfo'
# 传递令牌的方法，参数为header | querystring | formdata
TranTokenMethod = 'header'
# SSO服务App ID
ClientId = '66***********'
# SSO服务App Secret
ClientSecret = 'ccc***********'
# 是否覆盖用户属性 参数选项true/false
CoverAttributes = true
# 用户在夜莺系统中的默认角色 Guest/Standard/Admin
DefaultRoles = ['Standard']
# 用户信息是否为数组
UserinfoIsArray = false
# 用户信息的前缀
UserinfoPrefix = 'data'
# 请求的OAuth2范围
Scopes = ['profile', 'email', 'phone']

# OAuth2的用户属性映射平台的用户属性
[Attributes]
# 用户名字段的映射
Username = 'sub'
# 昵称字段的映射
Nickname = 'nickname'
# 电话字段的映射
Phone = 'phone_number'
# email字段映射
Email = 'email'

TranTokenMethod 参数说明

TranTokenMethod 配置是设定获取 getUserInfo 接口信息时候的 Token 发送方式。大家在配置是可以查看确认一下 getUserInfo 接口对传递 Token 的要求。下面是分情况配置参数。

接口要求 GET 请求，并放到 header 中传递，TranTokenMethod 设置为 header ；

接口要求 GET 请求，并放到 url 中传递，TranTokenMethod 设置为 querystring ；

接口要求 POST 请求，TranTokenMethod 设置为 formdata ；

用户属性映射

在对接适配时，可以通过 DEBUG 日志过滤关键词 oauth2 进行查看分析，如下图所示我们可以看到平台通过 getUserInfo 接口可以获得的相关数据。 我们把接口中获取到的用户信息填写在配置中，与平台字段对应即可实现用户信息的映射。

如上图所示，将获取到的 name —> Username ; nickename —> Nickname ; phone_number —> Phone ; email —> Email;

UserinfoPrefix 参数说明

UserinfoPrefix 参数用于指定在返回的用户信息 JSON 中，属性前缀的设置。

如果 API 返回的用户信息结构如下，需要设置 UserinfoPrefix 为 data 。

{
  "data": {
    "username": "john_doe",
    "email": "john@example.com"
  }
}

如果不清楚返回的数据结构，可以通过查看平台 DEBUG 日志分析数据结构。

基础配置说明

下面是一个Authing的OAuth2配置对应说明：

RedirectURL默认是http://n9e-server:port/callback/oauth

账号登陆

常见问题

Q1：点击 OAuth2 登录后跳到第三方页面但回调失败？

A：检查 OAuth2 提供方的回调白名单 / Redirect URI：必须包含夜莺的完整回调地址（如 https://your-n9e.com/callback/oauth）。常见错误是只填了 domain 没带 path。

Q2：第一次用 OAuth2 登录成功了但提示"用户不存在"？

A：夜莺默认不自动建账号。两种处理：

• 让管理员先在 用户管理 里建好对应用户名（与 OAuth2 返回的 username 字段一致）；
• 或者在 n9e.toml 里把 OAuth2 配置的 CoverAttributes / 自动创建用户开关打开。

Q3：用户的角色/团队怎么自动同步？

A：OAuth2 不自动同步组织关系。常见做法：

• 自动建账号后给所有人默认 Standard 角色，由 Admin 后续手工分团队；
• 或者用脚本对接 OAuth2 服务端的组织 API 定时同步到夜莺。

Q4：能不能限制只有特定组织内的人能登录？

A：在 OAuth2 服务端做 — n9e 这边收到的就是认证后的用户。要做"白名单"在 IDP 侧的 app 配置里限制可登录用户范围。

参考资料

• LDAP SSO
• OIDC SSO
• 用户管理
• OAuth 2.0 规范（RFC 6749）