SovereignID
文档目录 接入 Gitea

Gitea OAuth2 / OpenID Connect

接入 Gitea

Gitea 1.25.x

配置 Gitea OIDC 认证源、回调地址、scope、声明映射和自动注册。

Gitea 通过 OAuth2 认证源接入 SovereignID。配置时不要写死某个部署域名， 统一使用当前环境的 SovereignID 外部访问地址作为 OIDC issuer。

域名约定 将 <SOVEREIGNID_ISSUER_URL> 替换为 SovereignID 的公网根地址，例如 https://id.example.com。生产配置中的 SOVEREIGNID_ISSUER_URL、 Gitea 填写的自动发现 URL、浏览器实际访问的登录地址必须属于同一个 origin。

一、准备 OIDC 应用

使用管理员账号登录 SovereignID 后，进入账号页，再打开 /accounts/applications/ 的“应用管理 / OIDC 应用”，为 Gitea 新建一个应用。

配置项 建议值 说明
应用名称 Gitea 便于管理员识别来源系统。
客户端类型 Confidential Gitea 后端会保存客户端密钥。
授权方式 Authorization Code Gitea 的 OpenID Connect 登录流程使用授权码模式。
回调地址 <GITEA_APP_URL>/user/oauth2/<认证源名称>/callback 认证源名称建议固定为 sovereignid，创建后不要随意修改。
授权范围 openid profile email groups 用于登录、邮箱同步、姓名同步和用户组声明。 
示例：
SovereignID issuer: https://id.example.com
Gitea 地址: https://gitea.example.com
认证源名称: sovereignid
回调地址: https://gitea.example.com/user/oauth2/sovereignid/callback

保存应用后，复制 SovereignID 生成的 客户端 ID 和 客户端密钥， 用于填写 Gitea 的认证源表单。客户端密钥只在创建成功或重置密钥后的页面显示一次； 离开或刷新页面后无法再次查看，只能重新生成。

二、在 Gitea 添加认证源

  1. 使用 Gitea 管理员账号登录。
  2. 进入“管理后台”，打开“身份及认证”。
  3. 进入“认证源”，点击“添加认证源”。
  4. 认证类型选择 OAuth2。
  5. OAuth2 提供程序选择 OpenID Connect。
  6. 按下表填写字段，确认无误后点击“添加认证源”。
Gitea 字段 填写内容 注意事项
认证名称 sovereignid 会进入回调 URL，后续修改需同步更新 SovereignID 应用回调地址。
客户端 ID（键） SovereignID 应用详情页生成的 client_id 从 Gitea 对应的 OIDC 应用复制，不要和其他系统共用。
客户端密钥 SovereignID 应用详情页生成的 client_secret 只在 Gitea 服务器侧保存，不要写入公开文档或代码仓库。
OpenID 连接自动发现 URL <SOVEREIGNID_ISSUER_URL>/.well-known/openid-configuration 例如 https://id.example.com/.well-known/openid-configuration。
附加授权范围 Scopes profile email groups Gitea 会请求 OpenID Connect 登录所需声明。
全名声明名称 name 用于同步 Gitea 用户全名。
必须填写 Claim 声明的名称和值 留空 MVP 阶段不通过固定 claim 限制登录来源。
用于提供用户组名称的 Claim 声明名称 groups SovereignID 会把用户所属组作为 groups claim 返回。
启用用户同步 开启 允许 Gitea 根据 OIDC claims 同步用户资料。
该认证源已经启用 开启 开启后 Gitea 登录页会显示该认证源。

三、建议的 Gitea 配置

如果可以修改 Gitea 的 app.ini，建议同步确认以下配置，确保首次 OIDC 登录时可以自动创建账号， 并用 SovereignID 返回的稳定用户名作为 Gitea 用户名。 

[oauth2_client]
ENABLE_AUTO_REGISTRATION = true
OPENID_CONNECT_SCOPES = profile email groups
USERNAME = preferred_username

四、SovereignID 返回给 Gitea 的声明

Claim 来源 用途
sub SovereignID 内部稳定用户 ID Gitea 识别同一个外部账号。
preferred_username SovereignID 用户名 建议作为 Gitea 自动创建账号时的用户名。
nickname SovereignID 用户名 兼容部分默认读取 nickname 的 OIDC 客户端。
name 用户全名或用户名 同步 Gitea 用户全名。
email 用户邮箱 同步 Gitea 邮箱。
email_verified 邮箱验证状态 未验证邮箱不能完成授权。
groups SovereignID 用户组 供 Gitea 用户组或团队映射使用。

五、验收检查

  • Gitea 能保存 OpenID Connect 认证源，没有 discovery 或证书错误。
  • Gitea 登录页出现 sovereignid 登录入口。
  • 点击登录后跳转到 SovereignID 登录页。
  • 已验证邮箱的用户登录后能回到 Gitea。
  • 首次登录时 Gitea 能自动创建或绑定用户，并同步邮箱、姓名和用户组声明。

六、常见排错

保存认证源时报 discovery 失败

检查 Gitea 服务器是否能访问 <SOVEREIGNID_ISSUER_URL>/.well-known/openid-configuration，并确认反向代理 HTTPS 证书可信。

登录后提示 redirect_uri 不匹配

确认 SovereignID 应用登记的回调地址与 Gitea 实际生成的回调地址完全一致，包括协议、域名、路径和认证源名称。

用户能登录但资料没有同步

确认 Gitea 已开启用户同步，并检查 scope 是否包含 profile email groups。

未验证邮箱无法进入 Gitea

这是预期行为。手机号账号会看到“绑定邮箱并继续”入口；完成绑定验证后会安全返回原授权地址。