Setup Gmail


This guide describes how you can connect Gmail with Confluence Server/Data Center.

Google requires users to use OAuth2 to authenticate. Unfortunately to use OAuth2 with mailto.wiki and Gmail you will need to register your own OAuth2 client in the Google developer console. This guide will walk you through this process. This should take an estimated 15 minutes.

To follow this guide you will need administrative rights. If you are not a Confluence Administrator you will need to ask a Confluence admin of your organization to do the steps for you.

Step 1 - Go to the configuration page


If you are not already on the configuration page of mailto.wiki, go to the configuration page (see Getting Started).

In the Inbound Server Settings or the Outbound Server Settings click on Gmail. Copy and save the "Redirect Url". You will need this value later in Step 4 when you're creating your OAuth2 client.


Image

Step 2 - Create a new project in the Google Cloud console


Gmail only supports authentication with OAuth2. To use mailto.wiki with Gmail you will have to register your own OAuth2 client.

Start by going to the Google API Console Credentials page. You will have to login with a Google account. You can use the same account that you are trying to use with mailto.wiki, but it doesn't have to be the same. Only trusted users should have access to this Google account.

After logging in you should see the Credentials screen. If you haven't used the Google Api Console before, this screen should be empty. Start by clicking on the "CREATE PROJECT" button to create a new project:


Image

Give your project a meaningful name and then click on the "CREATE" button:


Image

After your project has been created you should be send back to the Credentials screen.

Step 3 - Configure the consent screen


The next necessary step is to configure the consent screen. To do so choose "OAuth consent screen" from the menu on the left:


Image

In the configuration dialog for the OAuth consent screen choose "External" and then click on the "Create" button:


Image

On the next screen fill out all required fields and then click on the "SAVE AND CONTINUE" button:


Image

On the Scopes screen click on "ADD OR REMOVE SCOPES". A dialog should open. Scroll down to "Manually add scopes" and enter the text "https://mail.google.com/". Then click on the "ADD TO TABLE" button. Finish by clicking on the "UPDATE" button:


Image

You should now see Gmail listed in the "Your restricted scopes" section. Continue with the next screen by clicking on the "SAVE AND CONTINUE" button:


Image

On the "Test users" screen you will have to add the gmail address that you want to use with Confluence. To do so click on the "ADD USERS" button. A dialog will open where you can enter the email address of the Gmail account. Confirm by clicking on "ADD" and then go to the next screen by clicking on "SAVE AND CONTINUE":


Image

Your consent screen is now configured. On the summary page check again that "https://mail.google.com/" is listed in the list of scopes. Also check that the Gmail account you want to connect with Confluence is listed in the test users section. Then click on the "BACK TO DASHBOARD" button:


Image

Next you will have to submit your consent screen for publishing. This is necessary because in testing mode you will be logged out after 7 days. However it's enough to submit the app, you don't actually have to go through with the verification process. To do so click on the "PUBLISH APP" button:


Image

Google will show you a message asking you if you're ready to push to production. This dialog will contain a list of things you will need for verification. You can ignore all this as you're not actually going to go through with the verification process. Just click on "CONFIRM":


Image

After doing so the app will be in production state. Even tough the verification isn't done. Don't do the verification and just leave things as they are. You're now done with the consent screen and you can proceed with creating the OAuth client.


Image

Step 4 - Create the Oauth client


Return to the Credentials page by clicking on "Credentials" in the menu on the left:


Image

To create a new Oauth2 client click on the "Create Credentials" button and then choose "OAuth client ID" from the drop-down.


Image

A dialog to create an OAuth client should open. From the "Application type" select box choose "Web application". This should show more fields. Next choose a name for your OAuth client. Finally add the redirect url by clicking on "ADD URI". Then enter the redirect url as displayed on the mailto.wiki confguration page (see Step 1):


Image

You are now done with creating the OAuth2 client. A dialog should pop open that shows you your client id and client secret. Copy and store these values for the next step.


Image

Step 6 - Connect Confluence with Gmail


Now return to the configuration page of mailto.wiki (Step 1) and enter the Gmail address you want to use with mailto.wiki into the Username field. Also enter the client ID and client secret from the previous step. Then click on the "Login to Gmail" button:


Image

This should open a new tab or window in your browser that should display the "Sign in with Google" dialog. If something went wrong you should see an error message here. If you can't resolve the issue on your own please make a screenshot and ask for help at support@mailto.wiki. Proceed by choosing the account you want to connect with Confluence:


Image

Because we did not complete the verification process in Step 3, Google will display prominently a warning that "Google hasn't verified this app" this is expected and not an issue. Continuing has no security ramifications. When the warning shows up click on "Advanced" and then click on "Go to your project name (unsafe)".


Image
Image

Next Google will ask you if you want to give Confluence permission to access Gmail. Confirm by clicking on "Continue":


Image

If everything went well you should now see a success message. If you don't you can make a screenshot and contact support@mailto.wiki for help.


Image

Finally close the tab or window with the success message and return back to the configuration screen. After waiting 10 seconds the configuration screen should now show you as logged in. Don't forget to save your settings by clicking on the "Save Settings" button:


Conclusion


Image

You now know how to connect Gmail with mailto.wiki. You can use the same client id and secret for the Inbound Server Settings and the Outbound Server Settings. If you ever change your password for the Gmail account or you suddenly stop receiving emails in Confluence go back to the configuration page and check that you're still logged in to Gmail.

If you experience any issues don't hesitate to write to support@mailto.wiki.