Skip to content

Commit

Permalink
Fixing documentation of gmail smtp (#5998)
Browse files Browse the repository at this point in the history
• removal of "accessToken" from documentation, since it is not in the source code.
• addition of a new step of 'changing publishing status from testing to production'
• removal of a duplicate picture in index.md and adding an appropriate pic instead.
  • Loading branch information
adnan29979 committed Apr 6, 2024
1 parent f9af1ff commit 4a3c6db
Show file tree
Hide file tree
Showing 3 changed files with 19 additions and 9 deletions.
Binary file added docs/docs/meshcentral/images/In-production.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
28 changes: 19 additions & 9 deletions docs/docs/meshcentral/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -336,19 +336,25 @@ Please map the host, port values to connect to the right host that provides this

Some SMTP servers will require a valid username and password to login to the mail server. This is to prevent unauthorized e-mail correspondence. TLS option can be set to ‘true’ if the SMTP server requires TLS.

One option is to configure MeshCentral work with Google Gmail* by setting “host” with smtp.gmail.com, and “port” with 587. In the config.json file, use user’s Gmail* address for both “from” and “user” and Gmail* password in the “pass” value. You will also need to enable “Less secure app access” in for this Google account. It’s in the account settings, security section:
#### SMTP: User/Pass
##### Gmail

One option is to configure MeshCentral work with Google Gmail by setting “host” with smtp.gmail.com, and “port” with 587. In the config.json file, use user’s Gmail address for both “from” and “user” and Gmail password in the “pass” value. You will also need to enable “Less secure app access” in for this Google account. It’s in the account settings, security section:

![](images/2022-05-19-00-01-19.png)

If a Google account is setup with 2-factor authentication, the option to allow less secure applications not be available. Because the Google account password is in the MeshCentral config.json file and that strong authentication can’t be used, it’s preferable to use a dedicated Google account for MeshCentral email.

#### SMTP: OAuth Authentication
##### Gmail

Google has announced that less secure app access will be phased out. For Google Workspace or G-Suite accounts, the following process can be used to allow OAuth2 based authentication with Google's SMTP server. It is likely a very similar process for regular Gmail accounts.

Start by visiting the Google API console:

https://console.developers.google.com/

First, you will create a new project. Name it something unique in case you need to create more in the future. In this example, I've named the project "MeshCentral"
First, you will create a new project. Name it something unique in case you need to create more in the future. In this example, I've named the project "MeshCentral"

![](images/gc-newproject.png)

Expand All @@ -358,9 +364,9 @@ Click on the "OAuth Consent Screen" link, Under "APIs and Services" from the lef

If you have a Google Workspace account, you will have the option to choose "Internal" application and skip the next steps. If not, you will be required to provide Google with information about why you want access, as well as verifying domain ownership.

![](images/gc-oauthconsent2.png)
![](images/OAuth-Internal-External.png)

You will want to add a scope for your app, so that your token is valid for gmail:
Add the Gmail address under which you have created this project to the fields labelled ‘User support email’ and ‘Developer contact information’ so that you will be allowed for authentication. After that, you will want to add a scope for your app, so that your token is valid for gmail:

![](images/gc-oauthscopes.png)

Expand All @@ -370,7 +376,7 @@ Once this is complete, the next step will be to add credentials.

Choose OAuth Client

You will obtain a Client ID and a Client secret once you've completed the process. Be sure to store the secret immediately, as you won't be able to retreive it after you've dismissed the window.
You will obtain a Client ID and a Client secret once you've completed the process. Be sure to store the secret immediately, as you won't be able to retreive it after you've dismissed the window.

Next, you will need to visit the Google OAuth Playground:

Expand All @@ -380,7 +386,7 @@ https://developers.google.com/oauthplayground

Enter your Client ID and secret from the last step. On the left side of the page, you should now see a text box that allows you to add your own scopes. Enter https://mail.google.com and click Authorize API.

You will need to follow the instructions provided to finish the authorization process. Once that is complete, you should receive a refresh token and an access token. These are the final items we need to complete the SMTP section of our config.json. It should now look something like this:
You will need to follow the instructions provided to finish the authorization process. Once that is complete, you should receive a refresh token. The refresh token, Client ID and Client Secret are the final items we need to complete the SMTP section of our config.json. It should now look something like this:

```
"smtp": {
Expand All @@ -389,9 +395,8 @@ You will need to follow the instructions provided to finish the authorization pr
"from": "my@googleaccount.com",
"auth": {
"clientId": "<YOUR-CLIENT-ID>",
"clientSecret": "<YOUR-SECRET>",
"refreshToken": "<YOUR-REFRESH-TOKEN>",
"accessToken": "<YOUR-ACCESS-TOKEN>"
"clientSecret": "<YOUR-CLIENT-SECRET>",
"refreshToken": "<YOUR-REFRESH-TOKEN>"
},
"user": "noreply@authorizedgooglealias.com",
"emailDelaySeconds": 10,
Expand All @@ -405,6 +410,11 @@ Regardless of what SMTP account is used, MeshCentral will perform a test connect

![](images/2022-05-19-00-01-43.png)

After successfully configuring the Gmail SMTP server, switch the OAuth 'Publishing Status' from `Testing` to `In Production`. This step prevents the need for frequent refresh token generation. Verification of your project isn't required to make this change.

![](images/In-production.png)


## Database

A critical component of MeshCentral is the database. The database stores all of the user account information, groups and node data, historical power and event, etc. By default MeshCentral uses NeDB (https://github.com/louischatriot/nedb) that is written entirely in NodeJS and is setup automatically when MeshCentral is installed with the npm tool. The file “meshcentral.db” will be created in the “meshcentral-data” folder when MeshCentral is first launched. This database works well for small deployments scenarios.
Expand Down

0 comments on commit 4a3c6db

Please sign in to comment.