设置 OAuth 2.0 绑定

哪吒支持为已有的本地账户通过 OAuth 2.0 绑定第三方网站账户。

---

配置

使用 OAuth 2.0 需要手动更改 Dashboard 配置文件。

oauth2:
  Example: # replace it with desired name, like `GitHub`
    clientid: "a-unique-id"
    clientsecret: "a-unique-secret"
    endpoint:
      authurl: "https://example.com/authorize"
      tokenurl: "https://example.com/token"
    scopes:
      - "read"
    userinfourl: "https://api.example.com/user"
    useridpath: "id"

配置说明：

• clientid

  • OAuth 2.0 客户端 ID。

• clientsecret

  • OAuth 2.0 客户端密钥。

• endpoint.authurl

  • 授权端点。

• endpoint.tokenurl

  • 令牌端点。

• endpoint.scopes

  • 指定的权限列表，需要根据情况填写。

• endpoint.userinfourl

  • 第三方网站的用户 API 端点。

• endpoint.useridpath

  • 用户 API 中代表 ID 的字段。

---

创建 OAuth 2.0 应用

使用此功能前首先需要在第三方网站上创建一个 OAuth 2.0 应用。

哪吒的 Callback URI 为：/api/v1/oauth2/callback

由于各个网站的步骤不同，这里只能给出部分示例，一般来说各个平台的操作类似，只需要获取到哪吒所需的信息即可。

创建示例

GitHub

点击展开/收起

1. 打开 https://github.com/settings/developers，依次选择 “OAuth Apps” - “New OAuth App”。
2. 填写以下需要的字段：

• Application name：应用名
• Homepage URL：面板访问地址，例如 https://nezha.example.com
• Authorization callback URL 面板的 Callback 地址，这里只检测前缀，所以可以填写 https://nezha.example.com/api/v1/oauth2/callback。

3. 在新页面中保存 Client ID 和 Client secrets，完成面板 OAuth 2.0 配置：

oauth2:
  GitHub:
    clientid: "a-unique-id"
    clientsecret: "a-unique-secret"
    endpoint:
      authurl: "https://github.com/login/oauth/authorize"
      tokenurl: "https://github.com/login/oauth/access_token"
    userinfourl: "https://api.github.com/user"
    useridpath: "id"

Cloudflare Access

点击展开/收起

前往 Zero Trust Dashboard：https://one.dash.cloudflare.com/，选择或新建一个账户（Account），然后按照以下步骤操作：

1. My Team -> Users -> 点击<具体用户> -> 获取 User ID 并保存 （如果是第一次使用 Zero Trust，Users 列表会为空，可暂时跳过这一步；你需要完成一次验证后，用户才会出现在 Users 列表中）；
2. Access -> Applications -> Add an Application;
3. 选择 SaaS，在 Application 字段中输入自定义的应用名称（例如 nezha），选择 OIDC 后点击 Add application;
4. Scopes 需要选择 openid 和 profile;
5. 在 Redirect URLs 中添加你的 Dashboard Callback 地址，比如 https://nezha.example.com/api/v1/oauth2/callback；
6. 添加 Policy，Action 设为 Allow，添加一条 Include 规则，Selector 选择 Emails，在文本框中输入你的邮箱地址，保存策略；
7. 分别记录 Client ID、Client Secret、Token endpoint 和 Authorization endpoint;
8. 填写哪吒 OAuth 2.0 配置，保存后重启面板：

oauth2:
  Cloudflare:
    clientid: "a-unique-id"
    clientsecret: "a-unique-secret"
    endpoint:
      authurl: "https://xxx.cloudflareaccess.com/cdn-cgi/access/sso/oidc/xxx/authorization"
      tokenurl: "https://xxx.cloudflareaccess.com/cdn-cgi/access/sso/oidc/xxx/token"
    scopes:
      - openid
      - profile
    userinfourl: "https://xxx.cloudflareaccess.com/cdn-cgi/access/sso/oidc/xxx/userinfo"
    useridpath: "sub"

Gitea / Forgejo

点击展开/收起

以 Codeberg 为例：

1. 进入 https://codeberg.org/user/settings/applications，在 Manage OAuth2 applications 处创建新的 OAuth 2.0 应用，填写 Redirect URIs：https://nezha.example.com/api/v1/oauth2/callback；
2. 创建之后会跳转到新创建的应用，保存下 Client ID 和 Client Secret；
3. 填写哪吒 OAuth 2.0 配置，保存后重启面板：

oauth2:
  Codeberg:
    clientid: "a-unique-id"
    clientsecret: "a-unique-secret"
    endpoint:
      authurl: "https://codeberg.org/login/oauth/authorize"
      tokenurl: "https://codeberg.org/login/oauth/access_token"
    userinfourl: "https://codeberg.org/api/v1/user"
    useridpath: "id"

GitLab

点击展开/收起

1. 进入 https://gitlab.com/-/user_settings/applications，点右侧 Create new application 创建新的 OAuth 2.0 应用，填写以下内容：

• Callback URL：哪吒 Callback URL，比如 https://nezha.example.com/api/v1/oauth2/callback；
• Scopes：这里只需要 read_user。 其它的默认即可

2. 创建之后会跳转到应用界面，保存下 Client ID (Application ID) 和 Client Secret (Secret)；
3. 填写哪吒 OAuth 2.0 配置，保存后重启面板：

oauth2:
  GitLab:
    clientid: "a-unique-id"
    clientsecret: "a-unique-secret"
    endpoint:
      authurl: "https://gitlab.com/oauth/authorize"
      tokenurl: "https://gitlab.com/oauth/token"
    scopes:
      - read_user
    userinfourl: "https://gitlab.com/api/v4/user"
    useridpath: "id"

Gitee

点击展开/收起

1. 进入 https://gitee.com/oauth/applications，点右侧 创建应用 创建新的 OAuth 2.0 应用，填写以下内容：

• 应用名称：你的应用名称，例如 ServerStatus；
• 上传LOGO：你的应用图标；
• 应用主页：你的哪吒面板地址，例如 https://nezha.example.com；
• 回调地址：哪吒 Callback URL，比如 https://nezha.example.com/api/v1/oauth2/callback；
• 权限：这里只需要 user_info。 其它的默认即可

2. 创建之后会跳转到我的应用界面，点击 应用详情 保存下 Client ID 和 Client Secret；
3. 填写哪吒 OAuth 2.0 配置，保存后重启面板：

oauth2:
  Gitee:
    clientid: "a-unique-id"
    clientsecret: "a-unique-secret"
    endpoint:
      authurl: "https://gitee.com/oauth/authorize"
      tokenurl: "https://gitee.com/oauth/token"
    scopes:
      - user_info
    userinfourl: "https://gitee.com/api/v5/user"
    useridpath: "id"

---

绑定账户

在配置好 OAuth 2.0 信息后，登录后台，点击右上角头像进入个人设置。

在个人信息页的卡片列表里可以看见 OAuth 2 绑定的字样，其中有您所填写的 OAuth 2.0 配置名及其对应用户。点击配置名右侧的 绑定 按钮就可以跳转到认证页面进行账户绑定。

完成绑定后，便可以使用登录页下方的 OAuth 2 按钮登录您的账户。

---

禁止密码登录

在更新个人信息的表单中可以为当前用户启用该选项。

启用后，将无法通过密码登录当前用户，与验证失败的错误一致。

如果当前用户还没有任何 OAuth 2.0 绑定关系，则无法启用该选项；相应地，如果启用了该选项，当前用户只剩下一个 OAuth 2.0 绑定关系时将无法删除此绑定关系。