Setting Up OAuth 2.0 Binding

Nezha supports binding third-party website accounts to existing local accounts using OAuth 2.0.

---

Configuration

Using OAuth 2.0 requires manually modifying the Dashboard configuration file.

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"

Configuration explanation:

• clientid

  • OAuth 2.0 client ID.

• clientsecret

  • OAuth 2.0 client secret.

• endpoint.authurl

  • Authorization endpoint.

• endpoint.tokenurl

  • Token endpoint.

• endpoint.scopes

  • List of specified permissions, needs to be filled according to the situation.

• endpoint.userinfourl

  • User API endpoint of the third-party website.

• endpoint.useridpath

  • The field representing the ID in the user API.

---

Creating an OAuth 2.0 Application

Before using this feature, you need to create an OAuth 2.0 application on the third-party website.

The Callback URI of Nezha is: /api/v1/oauth2/callback

Since the steps vary across different websites, only some examples can be provided here. Generally speaking, the operations on each platform are similar, and you only need to obtain the information needed by Nezha.

Examples

GitHub

Expand/Collapse

1. Open https://github.com/settings/developers, and select “OAuth Apps” - “New OAuth App”.
2. Fill in the following required fields:

• Application name：Application name
• Homepage URL：Dashboard access address, such as https://nezha.example.com
• Authorization callback URL Dashboard Callback address, only the prefix is checked here, so you can fill in https://nezha.example.com/api/v1/oauth2/callback.

3. On the new page, save the Client ID and Client secrets, and complete the Dashboard OAuth 2.0 configuration:

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

Expand/Collapse

Go to the Zero Trust Dashboard: https://one.dash.cloudflare.com/, select or create an account, and then follow these steps:

1. My Team -> Users -> Click on <specific user> -> Get User ID and save it (If you are using Zero Trust for the first time, the Users list will be empty, you can temporarily skip this step; you need to complete a verification before the user appears in the Users list);
2. Access -> Applications -> Add an Application;
3. Select SaaS, enter a custom application name (e.g., nezha) in the Application field, select OIDC and click Add application;
4. Scopes need to select openid and profile;
5. Add your Dashboard Callback address to Redirect URLs, you need to add two, in the following format:

• https://nezha.example.com/api/v1/oauth2/callback

6. Add a Policy, set Action to Allow, add an Include rule, select Emails in Selector, enter your email address in the text box, and save the policy;
7. Record Client ID, Client Secret, Token endpoint and Authorization endpoint;
8. Fill in the Nezha OAuth 2.0 configuration, save and restart the Dashboard:

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

Expand/Collapse

Take Codeberg as an example:

1. Go to https://codeberg.org/user/settings/applications, create a new OAuth 2.0 application under Manage OAuth2 applications, fill in the Redirect URIs, in the following format:

• https://nezha.example.com/api/v1/oauth2/callback

2. After creation, you will be redirected to the newly created application, save the Client ID and Client Secret;
3. Fill in the Nezha OAuth 2.0 configuration, save and restart the Dashboard:

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

Expand/Collapse

1. Go to https://gitlab.com/-/user_settings/applications, click Create new application on the right side, and fill in the following contents:

• Callback URL: Nezha Callback URL, for example https://nezha.example.com/api/v1/oauth2/callback;
• Scopes: Only read_user is needed here. The rest can be default

2. After creation, you will be redirected to the application page, save the Client ID (Application ID) and Client Secret (Secret);
3. Fill in the Nezha OAuth 2.0 configuration, save and restart the Dashboard:

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

Expand/Collapse

1. Go to https://gitee.com/oauth/applications, click on the Create Application button on the right to create a new OAuth 2.0 application, and fill in the following details:

• Application Name: Your application name, for example, ServerStatus;
• Upload LOGO: Your application icon;
• Homepage URL: Your Nezha address, for example, https://nezha.example.com;
• Callback URL: Nezha Callback URL, for example, https://nezha.example.com/api/v1/oauth2/callback;
• Scope: Only user_info is needed here. The rest can be left as default.

2. After creation, you will be redirected to the My Applications page. Click on Application Details to save the Client ID and Client Secret.
3. Fill in the Nezha OAuth 2.0 configuration, save it, and restart Dashboard:

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"

---

Binding Accounts

After configuring the OAuth 2.0 information, log in to the Dashboard and click on the avatar in the upper right corner to enter personal settings.

In the card list on the personal information page, you can see the OAuth 2 binding, which includes the OAuth 2.0 configuration name you filled in and the corresponding user. Click the Bind button on the right side of the configuration name to jump to the authentication page and bind your account.

After completing the binding, you can use the OAuth 2 button at the bottom of the login page to log in to your account.

---

Reject Password Login

This option can be enabled for the current user in the update personal information form.

Once enabled, the current user will not be able to log in using a password, similar to a failed authentication error.

If the current user does not have any OAuth 2.0 binding, this option cannot be enabled; correspondingly, if this option is enabled, the current user will not be able to delete their last remaining OAuth 2.0 binding.