-
Notifications
You must be signed in to change notification settings - Fork 19
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
4 changed files
with
493 additions
and
118 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,281 @@ | ||
| # Administrator Configuration | ||
|
|
||
| ## Overview | ||
|
|
||
| After enabling the email plugin, administrators need to complete some configurations before regular users can connect their email accounts to NocoBase. | ||
|
|
||
| These configurations primarily involve obtaining settings from the email provider for API authentication. The main business flow is as follows: | ||
|
|
||
| #### Business Flow | ||
|
|
||
| **Administrator** | ||
| 1. Visit the provider's platform and create an application. | ||
| 2. Configure application-related information. | ||
| 3. Enable Mail API permissions and OAuth. | ||
| 4. Enter the obtained information into NocoBase. | ||
|
|
||
| **NocoBase** | ||
| 1. Use the application parameters to call the provider's Mail API. | ||
| 2. Retrieve email information when users authorize login. | ||
| 3. Provide email-related features. | ||
|
|
||
| **Regular Users** | ||
| 1. Authorize their email accounts in NocoBase. | ||
|
|
||
| ## Plugin Configuration | ||
|
|
||
| ### Enabling the Email Plugin | ||
|
|
||
| 1. Navigate to the Plugin Management page. | ||
| 2. Enable the plugin. | ||
|
|
||
| ### Email Provider Configuration | ||
|
|
||
| After enabling the email plugin, you can configure the email provider settings. Currently, both Google and Microsoft emails are supported. Go to **"Settings" -> "Email Settings"** to access the configuration page. | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| Each provider requires **Client ID** and **Client Secret**. Below are detailed steps to obtain these parameters. | ||
|
|
||
| ## Google Configuration | ||
|
|
||
| ### Prerequisites | ||
| 1. Ensure NocoBase is deployed on a server that can access Google services. The backend will call the Google API. | ||
|
|
||
| ### Account Registration | ||
| 1. Visit [Google Cloud Console](https://console.cloud.google.com/welcome). | ||
| 2. Agree to the terms on the first visit. | ||
|
|
||
|  | ||
|
|
||
| ### Creating an App | ||
| 1. Click **"Select a project"** at the top. | ||
|
|
||
|  | ||
|
|
||
| 2. In the pop-up, click **"NEW PROJECT"**. | ||
|
|
||
|  | ||
|
|
||
| 3. Enter project details. | ||
|
|
||
|  | ||
|
|
||
| 4. Once created, select the project. | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| ### Enabling Gmail API | ||
| 1. Click **"APIs & Services"**. | ||
|
|
||
|  | ||
|
|
||
| 2. Go to the **APIs & Services** panel. | ||
|
|
||
|  | ||
|
|
||
| 3. Search for **"mail"**. | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| 4. Click **"ENABLE"** to activate Gmail API. | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| ### Configuring OAuth Consent Screen | ||
| 1. Click **"OAuth consent screen"** in the left menu. | ||
|
|
||
|  | ||
|
|
||
| 2. Choose **"External"**. | ||
|
|
||
|  | ||
|
|
||
| 3. Enter project information for the authorization screen and save. | ||
|
|
||
|  | ||
|
|
||
| 4. Fill in the **Developer contact information** and proceed. | ||
|
|
||
|  | ||
|
|
||
| 5. Continue through the prompts. | ||
|
|
||
|  | ||
|
|
||
| 6. Add test users for pre-release testing. | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| 7. click to continue | ||
|
|
||
|  | ||
|
|
||
| 8. Review the overview and return to the control panel. | ||
|
|
||
|  | ||
|
|
||
| ### Creating Credentials | ||
| 1. Click **"Credentials"** in the left menu. | ||
|
|
||
|  | ||
|
|
||
| 2. Click **"CREATE CREDENTIALS"** and choose **"OAuth client ID"**. | ||
|
|
||
|  | ||
|
|
||
| 3. Choose **"Web application"**. | ||
|
|
||
|  | ||
|
|
||
| 4. Enter application details. | ||
|
|
||
|  | ||
|
|
||
| 5. Provide the final deployment domain (e.g., a test address for NocoBase). | ||
|
|
||
|  | ||
|
|
||
| 6. Add the authorized callback URL as `domain + "/admin/settings/mail/oauth2"`. Example: `https://pr-1-mail.test.nocobase.com/admin/settings/mail/oauth2`. | ||
|
|
||
|  | ||
|
|
||
| 7. Create and view OAuth details. | ||
|
|
||
|  | ||
|
|
||
| 8. Copy **Client ID** and **Client Secret** and paste them into the email configuration page. | ||
|
|
||
|  | ||
|
|
||
| 9. Save to complete the configuration. | ||
|
|
||
| ### Publishing the App | ||
| 1. Go to **"OAuth consent screen"**. | ||
|
|
||
|  | ||
|
|
||
| 2. Click **"PUBLISH APP"**. | ||
|
|
||
|  | ||
|
|
||
| 3. Confirm and publish. | ||
|
|
||
|  | ||
|
|
||
| ## Microsoft Configuration | ||
|
|
||
| ### Register an Account | ||
|
|
||
| 1. Visit https://azure.microsoft.com/en-us/pricing/purchase-options/azure-account. | ||
|
|
||
| 2. Log in to your Microsoft account. | ||
|
|
||
|  | ||
|
|
||
| ### Create a Tenant | ||
|
|
||
| 1. Visit https://azure.microsoft.com/zh-cn/pricing/purchase-options/azure-account?icid=azurefreeaccount and log in to your account. | ||
|
|
||
| 2. Fill in the basic information and complete the verification. | ||
|
|
||
|  | ||
|
|
||
| 3. Provide additional information and proceed. | ||
|
|
||
|  | ||
|
|
||
| 4. Fill in credit card details (optional at this stage). | ||
|
|
||
|  | ||
|
|
||
| ### Obtain the Client ID | ||
|
|
||
| 1. From the top menu, select **"Microsoft Entra ID"**. | ||
|
|
||
|  | ||
|
|
||
| 2. On the left sidebar, click **"App registrations"**. | ||
|
|
||
|  | ||
|
|
||
| 3. Click **"New registration"** at the top. | ||
|
|
||
|  | ||
|
|
||
| 4. Enter the required details and submit. | ||
|
|
||
| - You can choose any name. | ||
| - Select account types as shown in the example below. | ||
| - The **Redirect URI** field can be left empty for now. | ||
|
|
||
|  | ||
|
|
||
| 5. Retrieve the **Client ID**. | ||
|
|
||
|  | ||
|
|
||
| ### API Authorization | ||
|
|
||
| 1. Open the **"API permissions"** menu on the right sidebar. | ||
|
|
||
|  | ||
|
|
||
| 2. Click **"Add a permission"**. | ||
|
|
||
|  | ||
|
|
||
| 3. Select **"Microsoft Graph"**. | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| 4. Search for and add the following permissions. The final configuration should include: | ||
|
|
||
| 1. `"email"` | ||
| 2. `"offline_access"` | ||
| 3. `"IMAP.AccessAsUser.All"` | ||
| 4. `"SMTP.Send"` | ||
| 5. `"offline_access"` | ||
| 6. `"User.Read"` (default) | ||
|
|
||
|  | ||
|
|
||
| ### Obtain a Secret Key | ||
|
|
||
| 1. Open the **"Certificates & secrets"** menu on the left. | ||
|
|
||
|  | ||
|
|
||
| 2. Click the **"New client secret"** button. | ||
|
|
||
|  | ||
|
|
||
| 3. Provide a description and set an expiration date, then create the secret. | ||
|
|
||
|  | ||
|
|
||
| 4. Retrieve the **Secret ID**. | ||
|
|
||
|  | ||
|
|
||
| 5. Copy both the **Client ID** and **Client Secret**, then fill them in on the email configuration page. | ||
|
|
||
|  | ||
|
|
||
|
|
||
| ## FAQ | ||
|
|
||
| **Q:** Why can’t emails be received after logging in with a Microsoft account? | ||
| **A:** Currently, only Outlook and Gmail accounts are supported. Microsoft and Google accounts are not yet supported. For more details, refer to [this discussion](https://answers.microsoft.com/zh-hans/outlook_com/forum/all/%E7%8E%B0%E6%9C%89%E5%BE%AE%E8%BD%AF%E8%B4%A6/dba12dda-a7c7-4346-8263-53f4a6d9dc68). |
Oops, something went wrong.