-
Notifications
You must be signed in to change notification settings - Fork 115
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* 更新新功能介绍 * route * update english doc * remark -> note * 增加 OAuth 2文档 * update oauth2
- Loading branch information
Showing
24 changed files
with
794 additions
and
142 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| # Profile | ||
|
|
||
| **You can access the profile by clicking on the avatar → Profile.** | ||
|
|
||
| The profile page displays the current user's information, such as IP address, number of owned servers, and OAuth 2.0 bindings. | ||
|
|
||
| You can also update the current user's information. | ||
|
|
||
| --- | ||
|
|
||
| ## Update Profile | ||
|
|
||
| Click the "Update Profile" button below the user avatar to open the form. | ||
|
|
||
| The values that need to be filled in are as follows: | ||
|
|
||
| - **New Username** | ||
| - The new username, with the current username pre-filled. | ||
|
|
||
| - **Original Password** | ||
| - The user's current password. | ||
|
|
||
| - **New Password** | ||
| - The password to be changed, with a minimum length of 8 characters. | ||
|
|
||
| - **Reject Password Login** | ||
| - See [Reject Password Login](/en_US/guide/q14.html#reject-password-login). | ||
|
|
||
| After confirming that the information is correct, click "Confirm" to submit the form, and the page will automatically refresh. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,192 @@ | ||
| --- | ||
| outline: deep | ||
| --- | ||
|
|
||
| # 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. | ||
|
|
||
| ```yaml | ||
| 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: `https://nezha.example.com/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 | ||
|
|
||
| <details> | ||
| <summary>Expand/Collapse</summary> | ||
|
|
||
| 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: | ||
| ```yaml | ||
| 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" | ||
| ``` | ||
|
|
||
| </details> | ||
|
|
||
| #### Cloudflare Access | ||
|
|
||
| <details> | ||
| <summary>Expand/Collapse</summary> | ||
|
|
||
| Go to the Zero Trust Dashboard: [https://one.dash.cloudflare.com/](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: | ||
| ```yaml | ||
| 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" | ||
| ``` | ||
|
|
||
| </details> | ||
|
|
||
| #### Gitea / Forgejo | ||
|
|
||
| <details> | ||
| <summary>Expand/Collapse</summary> | ||
|
|
||
| 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: | ||
| ```yaml | ||
| 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" | ||
| ``` | ||
|
|
||
| </details> | ||
|
|
||
| #### GitLab | ||
|
|
||
| <details> | ||
| <summary>Expand/Collapse</summary> | ||
|
|
||
| 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: | ||
| ```yaml | ||
| 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" | ||
| ``` | ||
|
|
||
| </details> | ||
|
|
||
| --- | ||
|
|
||
| ## 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.