配置举例说明

# 是否启用OIDC登录功能 参数选项true/false
Enable = true
# OIDC登录方式在前端显示的名称
DisplayName = 'OIDC登录'
# OIDC认证成功后的重定向URL。这个URL应该是夜莺监控服务的回调地址
RedirectURL = 'http://n9e-server:port/callback'
# SSO服务的地址
SsoAddr = 'https://xxx.authing.cn/oidc'
# SSO登出地址，用于处理用户退出登录的请求
SsoLogoutAddr = 'https://xxx.authing.cn/oidc/session/end'
# SSO服务App ID
ClientId = '66988*************'
# SSO服务App Secret
ClientSecret = 'cbc*************'
# 是否覆盖用户属性 参数选项true/false
CoverAttributes = true
# 用户在夜莺系统中的默认角色 选项Guest/Standard/Admin
DefaultRoles = ['Guest']
# 请求的OIDC范围
Scopes = ['openid', 'profile', 'email', 'phone']

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

基础配置说明

下面是一个Authing的OIDC配置对应夜莺配置基本说明：

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

在不同的OIDC服务端可能会有映射字段差异，通过配置文件中Attributes里面的映射关系进行调整；下图是一个调整举例，将email映射为Username。

[Attributes]
Username = 'email'
Nickname = 'nickname'
Phone = 'phone_number'
Email = 'email'

账号登陆

常见问题

Q1：OIDC 登录后 token 校验失败，提示"invalid signature"？

A：

• OIDC Provider 的 JWKS URL 不可达（n9e 拉不到公钥）— 在 n9e Server 主机上 curl <jwks_uri> 测试；
• Provider 切换了签名算法但 n9e 没及时刷新 JWKS — 重启 n9e Server；
• 时钟严重偏移导致 token 校验失败 — 检查 NTP 同步。

Q2：OIDC 和 OAuth2 怎么选？

A：

• OIDC = OAuth2 + 标准化的身份信息（id_token + userinfo endpoint）。Keycloak / Auth0 / Okta / Google / Microsoft Entra 等现代 IDP，优先用 OIDC；
• OAuth2 = 早期协议，只解决"授权"，身份信息靠 IDP 自定义。对接老系统或者公司自研 IDP 时常用。

Q3：能不能把 IDP 的 group claim 同步到夜莺团队？

A：当前不直接支持。变通：让 IDP 把组信息塞到 id_token 的 claim 里；通过 n9e.toml 的 ClaimMap 把 group claim 写入用户的某个字段；用定时脚本读 group 字段 → 调 n9e API 同步到团队。

Q4：OIDC 配置完成后某些用户登录成功别人失败？

A：常见因素：IDP 这边对该用户没授权访问 n9e 应用；用户的 email / preferred_username claim 与 n9e 现有用户名冲突；用户首次登录 + 没开启自动创建账号。

参考资料

• OAuth2 SSO
• LDAP SSO
• OpenID Connect 规范
• Keycloak OIDC 配置
• 用户管理