Google Workspace Integration

In addition to adding users manually as described in chapter User Management, MailStore Server can synchronize its internal user database with the G Suite account of your organization.

During synchronization, user information, such as user names and email addresses, is copied from the G Suite account into MailStore Server's user database. That way, users can use their G Suite account credentials to also log on to MailStore Server and emails can be assigned to their corresponding user archives automatically, for example. No changes are made to the G Suite account itself by MailStore Server. The scope of the synchronization can be limited through filters.

Register Project with Google

Irregardless of whether own or third-party applications such as MailStore are supposed to interact with a G Suite account through Google APIs, they must be registered as a project with Google first. This is necessary to ensure that access by external applications is limited to a minimum and that each application uses its own set of credentials to authenticate with Google.

Create New Project

To register a project for MailStore Server with Google, proceed as follows:

• Go to the Google Developers Console.
• If prompted, login using a Google account of you G Suite organization. Logging in with a user that has admin privileges is highly recommend.
• If no project exists, click Create Project on the dashboard. Otherwise open the project list by clicking on the project drop-down in the header bar and click New project.
• Type in a meaningful name into the Project name field, e.g. "MailStore Server".
• Verify that Organization matches the desired organization and adjust the Location if needed.
• Click on Create.

Once the project has been created, make sure that it is selected in the project drop-down list before proceeding.

Add API Libraries

• Open the Navigation menu and select APIs & Services > Library.
• In the API Library, search and enable the following APIs and services:

  Admin SDK

  Gmail API

Customize Consent Screen

• Open the Navigation menu and select APIs & Services > OAuth consent screen.
• Under User Type select Internal.
• Click Create
• Type in a meaningful name into the Application name field, e.g. "MailStore Server"
• Click Save.

Create Service Account

A service account is required for MailStore Server to authenticate with Google and request authorization to use certain Google APIs. The following steps describe the creation of such a service account.

• Open the Navigation menu and select APIs & Services > 'Credentials.
• Click + Create Credentials and select Service account from the drop-down list.
• On the Create service account page, enter a name for the service account, e.g. "MailStore Server Service".
• Enter a description such as "Service account for MailStore Server to synchronize users and access mailboxes"
• Click Create.
• The service account does not require permissions on project level, therefore do not select a role.
• Click on Continue.
• Under Keys click on + Create Key.
• Select JSON as key type and click Create.
• The JSON file will be downloaded automatically. Save the JSON file in a secure location as it allows access to cloud resources of your organization.
• Click on Close and then on Done.

The newly created service account should now be listed under Service Accounts.

Perform Domain-Wide Delegation of Authority

To grant the service account domain-wide access to your G Suite account, so called domain-wide delegation must be enabled as described in these steps:

• Click on the newly created service account to access its details.
• Click on Show Domain-wide Delegation.
• Check the Enable G Suite Domain-wide Delegation box.
• Click on Save.

As a result, a new OAuth 2.0 Client was created for the service account that has been created in the previous step.

Creating OAuth 2.0 Client for User Authentication

To allow users to log into MailStore by authenticating with Google, another OAuth 2.0 Client must be created that is suitable for OpenID Connect.

• Click on Credentials' in the left navigation pane.
• Click + Create Credentials and select OAuth client ID from the drop-down list.
• Select Web application as Application type.
• Enter a Name, e.g. MailStore Server OpenID Connect.
• In the Authorized redirect URIs section, click on + Add URI.
• Enter the URI that is reachable by clients in the URIs field in the following scheme:

  https://<host>.<domain.tld>[:<port>]/oidc/signin

Granting Access on G Suite Account to Project

Once created, grant the newly created project fine-grained access to your G Suite account by defining the Google APIs it is allowed to use.

• Open the Google Admin console and log in with a G Suite domain admin.
• Select Security > API controls from the menu.
• Unter Domain wide delegation, click Manage domain wide delegation.
• On the Domain-wide delegation page, click Add new.
• Enter the Client ID of the OAuth 2.0 Client that is linked with the service account.
• Under OAuth Scope, add the following scopes:

  https://mail.google.com/, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.user.readonly

• Click Authorize.

Accessing Directory Service Integration

• Log on to MailStore Client as a MailStore Server administrator.
• Click on Administrative Tools > Users and Archives > Directory Services.
• In the Integration section, change the directory service type to G Suite.

Connection to G Suite

For synchronization MailStore Server requires information on how to connect to the G Suite.

• Key ID
  To import the private key, select the JSON file (e.g. MailStore API Access-e035d2ad4f35.json) that has been generated by Google for the service account.
• Service Account
  The service account is determined automatically from the JSON file.
• User Name
  The email address of a G Suite Administrator (e.g. [email protected]).

User Database Synchronization

After configuring the connection settings as described above, you can specify filter criteria for the G Suite synchronization in this section.

• Sync only these groups
  Choose one or several G Suite groups if you only want their members to be created as MailStore Server users. That way it's possible to exclude certain users from being synchronized to MailStore Server.

Options

• Automatically delete users in MailStore Server
  Here you can choose whether users that have been deleted in the G Suite Account will also be deleted in the MailStore Server user database by the synchronization. Users will also be deleted if they fall out of scope of the configured settings.
  Only MailStore Server users that have their authentication method set to Directory Services will be deleted.
  If the archive folder of such a user already contains archived emails, only the user entry but not its archive folder will be deleted in MailStore Server.

Assigning Default Privileges

By default, users that have been synchronized to MailStore Server from G Suite Account have the privilege to log on to MailStore Server as well as read access to their own user archive.
You can configure those default privileges before synchronization, for example, to assign the privilege Archive E-mail to all new users. To do this, click on Default Privileges...
More information on managing user privileges and their effects is available in the chapter Users, Folders and Settings which also has details on editing existing privileges.

Running Directory Services Synchronization

Click on Test Settings to check synchronization configuration and the results returned by the G Suite Account without any changes to the MailStore Server user database being actually committed.

To finally run the synchronization, click on Synchronize now. The results are shown with any changes committed to the MailStore Server user database.

You can test the authentication for a user by first selecting him from the list and then clicking on the button on the lower left. You will now be asked for that user's password. Upon clicking OK you'll receive a message whether the authentication has been successful.

Important Notice: For authentication with G Suite to work, the setting Allow less secure apps of the respective G Suite user has to turned on if it has not been enforced for all users (see above).

Login with G Suite Account Credentials

After synchronization MailStore users can log on to MailStore Server with their G Suite Account username and G Suite Account password.