Music Tag Web 单点登录配置教程

本文说明如何为 Music Tag Web 配置 Casdoor 等通用 OIDC 身份提供方，以及 Google、GitHub、QQ、微博登录。

先区分 OIDC 和 OAuth

OIDC 建立在 OAuth 2.0 之上，身份提供方会返回经过校验的身份声明。本项目的通用 OIDC 入口适用于 Casdoor 等兼容 OIDC Discovery 的服务；Google 也使用 OIDC。

GitHub、QQ、微博在本项目中走 OAuth 2.0：登录授权后，服务端再调用平台用户接口取得稳定用户 ID。它们不是本项目通用 OIDC 配置的 issuer，不能把它们的 Client ID 填进 OIDC_CLIENT_ID。

所有平台登录成功后，Music Tag Web 都会按“平台 + 平台用户 ID”映射本地用户，再签发 Music Tag Web 自己的 JWT。不会仅根据邮箱自动关联已有账号。新建账号默认为普通用户。

准备公网地址

下文用 https://music.example.com 表示用户浏览器访问 Music Tag Web 的完整公网 origin。替换成实际域名；如果部署在路径前缀下，也要把路径前缀保留在回调 URL 中。

回调地址必须同时满足：

• 与平台开发者后台登记的地址逐字符一致，包括 http/https、域名、端口、路径和结尾斜杠。
• 从用户浏览器及身份提供方都能访问。
• 使用 HTTPS 部署公网服务。仅本机开发时才使用 localhost HTTP 回调。

通用 OIDC / Casdoor

在 Casdoor 创建应用

1. 登录 Casdoor 管理后台，进入 Applications，新建一个应用。
2. 在应用中启用授权码登录，并将 Redirect URL 登记为：

https://music.example.com/auth/oidc/callback

3. 保存应用后复制应用详情中的 Client ID 和 Client Secret。这两项必须来自同一个应用。
4. OIDC_ISSUER 填 Casdoor 的外部访问地址，例如 https://casdoor.example.com。本项目会从该地址请求 /.well-known/openid-configuration。

不要使用容器内只对 Casdoor 自己可见的地址作为 issuer。身份提供方 discovery 文档返回的 issuer、授权地址、Token 地址必须能被 Music Tag Web 服务访问。

配置变量

四项都非空后，登录页会显示 OIDC 按钮。

Google

Google 使用 OIDC，但本项目为它提供了独立配置，避免和 Casdoor 的通用 OIDC 设置冲突。

1. 打开 Google Cloud Console - Credentials，创建或选择一个项目。
2. 配置 OAuth consent screen。应用处于 Testing 状态时，将用于测试登录的 Google 账号加入 Test users。
3. 进入 Credentials → Create Credentials → OAuth client ID，应用类型选择 Web application。
4. 在 Authorized redirect URIs 中登记：

https://music.example.com/auth/social/google/callback

5. 保存并复制 Client ID、Client Secret。

GitHub

GitHub 在本项目中使用 OAuth App，不是 GitHub Actions 的 OIDC token 功能。

1. 打开 GitHub Developer settings → OAuth Apps → New OAuth App。
2. 填写应用名称和 Homepage URL。
3. Authorization callback URL 填：

https://music.example.com/auth/social/github/callback

4. 创建后复制 Client ID，并生成 Client Secret。

当前申请 read:user 和 user:email 权限；邮箱只作为本地资料字段，不作为账号关联依据。

QQ

QQ 登录使用 QQ 互联的 OAuth 2.0 接口。

1. 打开 QQ 互联 并注册开发者账号。
2. 创建网站应用，按平台要求完成网站信息和域名验证，申请 QQ 登录能力。
3. 将回调地址登记为：

https://music.example.com/auth/social/qq/callback

4. 从应用信息页取得 App ID 和 App Key。

用户资料权限使用 get_user_info。QQ 返回的 OpenID 用于身份映射；QQ 的应用审核、网站验证和能力开通由 QQ 互联平台决定。

微博

微博登录使用微博开放平台 OAuth 2.0 接口。

1. 打开微博开放平台，注册开发者账号并创建网站应用。
2. 在应用设置中完善网站信息、授权回调信息，并按平台要求申请或开通登录权限。
3. 将回调地址登记为：

https://music.example.com/auth/social/weibo/callback

4. 从应用信息页复制 App Key 和 App Secret。

平台授权成功后，本项目使用微博返回的用户 ID 标识身份。微博应用的审核状态和权限可能影响登录及用户资料接口。

Docker 环境变量示例

把需要启用的平台变量放进运行 Django/Nginx 的 Music Tag Web 容器环境中。下面仅展示结构，替换域名和凭据；未使用的平台可以不配置。

services:
  music-tag-web:
    environment:
      OIDC_ISSUER: "https://casdoor.example.com"
      OIDC_CLIENT_ID: "casdoor-client-id"
      OIDC_CLIENT_SECRET: "replace-me"
      OIDC_REDIRECT_URI: "https://music.example.com/auth/oidc/callback"

      GOOGLE_CLIENT_ID: "replace-me.apps.googleusercontent.com"
      GOOGLE_CLIENT_SECRET: "replace-me"
      GOOGLE_REDIRECT_URI: "https://music.example.com/auth/social/google/callback"

      GITHUB_CLIENT_ID: "replace-me"
      GITHUB_CLIENT_SECRET: "replace-me"
      GITHUB_REDIRECT_URI: "https://music.example.com/auth/social/github/callback"

QQ 和微博分别使用 QQ_CLIENT_ID / QQ_CLIENT_SECRET / QQ_REDIRECT_URI、WEIBO_CLIENT_ID / WEIBO_CLIENT_SECRET / WEIBO_REDIRECT_URI。

Client Secret 只放在服务端环境变量或 Secret 管理系统，不要放进前端代码、镜像源码或提交到 Git。修改 Compose 环境变量后要重新创建容器，单纯重启旧容器不会更新它的环境变量。

部署后检查

1. 访问 Music Tag Web 登录页。只有 Client ID、Client Secret、Redirect URI 都配置完整的平台才会显示按钮；通用 OIDC 还要求 OIDC_ISSUER。
2. 点击按钮并完成平台授权。成功后应回到 Music Tag Web 并进入登录后的页面。
3. 若按钮不出现，检查容器环境变量及容器是否已重建。
4. 若平台提示 invalid client id，核对 Client ID 是否来自对应应用、Client Secret 是否配套，以及请求是否跳到了预期的平台实例。
5. 若提示 redirect URI 不匹配，比较容器变量和平台后台登记值，确认协议、域名、端口、路径完全一致。
6. 若回调提示 state 错误，确认浏览器访问登录页和回调时使用同一个域名，且浏览器允许该域名的 session cookie。
7. 通用 OIDC 无法发现 Provider 时，检查 OIDC_ISSUER 对应的 /.well-known/openid-configuration 是否可从 Music Tag Web 容器访问。

平台后台可能要求完成审核或指定测试用户。单测能验证本项目的回调和响应解析，但最终仍需用各平台的真实应用凭据做一次登录验证。