help centre
For more info visit status.atmail.com

How can we help?


Search our knowledge base for answers to
common questions and latest updates.



My activities New request

Follow

gmail integration

Dominic -

PROBLEM

How do I allow users to add their Gmail accounts?

ENVIRONMENT

  • atmail suite.

CAUSE

I would like users to be able to add their Gmail accounts

RESOLUTION

The atmail API Server allows client integration with Google Gmail using Google OAuth 2.0. OAuth 2.0 allows users to share access to their Gmail account with the API Server, allowing it to act as a proxy to the Gmail IMAP server. Access is restricted to the following:

  • https://mail.google.com - Read, send, delete, and manage your email
  • https://www.googleapis.com/auth/userinfo.email - View your email address

Any application that uses OAuth 2.0 to access Google APIs must have authorization credentials that identify the application to Google's OAuth 2.0 server. As an email provider, you will need to obtain OAuth 2.0 client credentials from the Google API Console. This can be achieved using the below.

Creating a Project

  1. Open the Google API Console, and sign in using a Google account.
  2. Create a new project. For this example we will use a project called atmail-gmail.
    Screenshot_from_2017-08-17_13-29-53.pngScreenshot_from_2017-08-17_13-32-47.png

When adding a Gmail account from webmail, the user will be presented with a user consent screen, requesting access to specific data. The information presented on this screen is what we need to configure. It also presents branding information such as your product name, logo, and provides links to terms of service, privacy policies etc.

  1. With your previously created project selected, open the Credentials page in the API Console.
  2. Select the OAuth consent screen tab.
  3. Fill out any required and optional fields.
    Screenshot_from_2017-08-17_13-39-25.png

Create and install authorization credentials

The following steps explain how to obtain authorization credentials for your project. These credentials are downloaded as a client_secrets.json file, which must be stored securely in a location available only to the API Server.

  1. In the Google API Console, Click Create credentials > OAuth client ID.
    Screenshot_from_2017-08-17_13-48-52.png
  2. Set the application type to Web application.
  3. Under Authorized redirect URIs, enter the GMail callback URL. This will be the base URL of the API Server followed by the GMail Callback endpoint gmailcb, ie https://example.com/api/gmailcb. The domain used here is required to be a FQDN.
    Screenshot_from_2017-08-17_13-50-56.png
  4. From the Credentials tab, click the Download JSON link to download the client_secrets.json file. Store this file only in a location available only to the API Server.
    Screenshot_from_2017-08-17_13-54-00.png

atmail API Server configuration

Configure the API Server with the client_secrets.json file as follows:

  1. Place the client_secrets.json file in the api directory.
    [root@mydomain ~]# mv 
    client_secret_571814690693-7fu9jlacjhd8ntebe2l8790la141918m.apps.googleusercontent.com.json
     /etc/atmail/api/
  2. Open api.conf and insert the following OAUTH variable. Pass the client_secrets.json as the argument. Also add the HEALTH_CHECK variable to assist us in confirming a successful implementation.
    [root@mydomain ~]# vi /etc/atmail/api/api.conf

    OAUTH_CREDENTIAL_FILE=client_secret_571814690693-7fu9jlacjhd8ntebe2l8790la141918m.apps.googleusercontent.com.json
    HEALTH_CHECK=true
  3. Stop the apiserver and restart via the command line so we can see verbose output in-case troubleshooting is required.
    [root@mydomain api]# systemctl stop apiserver
    [root@mydomain api]# apiserver -c /etc/atmail/api/api.conf -V -console
  4. Ensure the healthcheck passes, with a line similar to:
    INFO[2017-08-18T10:30:56+10:00] :-) OAUTH Credentials File client_secret_571814690693-7fu9jlacjhd8ntebe2l8790la141918m.apps.googleusercontent.com.json validated. 
    INFO[2017-08-18T10:30:56+10:00] :-) Health Check Complete

Webadmin configuration

  1. From the Webadmin, click Services->Webmail Settings.
  2. Select your domain from the drop-down box.
  3. Allow Multiple accounts and Google accounts.
  4. Remember to Save Settings.
    Screenshot_from_2017-08-18_10-36-55.png

Testing

  1. Login to an existing account via webmail.
  2. Select Settings->Accounts and click Add Another Account.
  3. Select Google and ok.
    Screenshot_from_2017-08-18_10-41-19.png
    Screenshot_from_2017-08-18_10-44-06.png
  4. The browser will then walk through the necessary steps provided by google to provision the account. The first being, selecting which Gmail account you wish to provision.
    Screenshot_from_2017-08-18_10-45-04.png
  5. Unless you have previously verified your app/domain with google, you will be presented with the following during provisioning. Bypass this by accepting the unverified application/domain.
    Screenshot_from_2017-08-18_10-45-59.png
  6. Grant the relevant permissions to the Gmail account.
    Screenshot_from_2017-08-18_10-46-10.png
  7. Once provisioned, you should be redirected back to webmail where your Gmail account will be visible under Available Accounts.
    Screenshot_from_2017-08-18_10-47-35.png

Caveats

To implement the above, you will need the use of a FQDN with at-least one A record. Google requires this for the Authorized Redirect URIs. This may be an issue if you are testing locally on a VM that does not have a public IP. The easiest way to mitigate this is to update the servers hosts file to point this domain to its-self.

For example, the hostname used for my atmail suite and mailserver is atmailate.com, while the domain used with googles OAUTH is mydomain.party (which has an A record pointing at a random IP that is not the local VM). The servers host file then looks like the following where 192.168.10.158 is the address of the server.

[root@mydomain ~]# cat /etc/hosts
127.0.0.1   localhost localhost.localdomain localhost4 localhost4.localdomain4
::1         localhost localhost.localdomain localhost6 localhost6.localdomain6
192.168.10.158 mydomain.party
192.168.10.158 atmailate.com

This allows the server to resolve the domains involved which will give true testing results.

 

Once you have confirmed your service is working. You should remove the HEALTH_CHECK variable from your api.conf and restart the service via systemd:

[root@mydomain ~] # systemctl start apiserver
Have more questions? Submit a request

Comments


Contact our support team


+61 (7) 5357 6605       support@atmail.com