Difference between revisions of "G Suite Integration"

Jump to: navigation, search
[unchecked revision][pending revision]
 
(9 intermediate revisions by 2 users not shown)
Line 2: Line 2:
 
{{Directory Services Preamble|G Suite account}}
 
{{Directory Services Preamble|G Suite account}}
  
== Prepare the G Suite account ==
+
<p class=msnote>Please note that on December 16th 2019 [https://go.mailstore.com/?lang=en&target=gsuite-lsa-restriction Google announced] to limit access to G Suite for less secure apps in the future.  This includes any MailStore Server version prior to 13, which therefore will no longer be able to authenticate users against G Suite when trying to log into MailStore Server.
In order to synchronize account information from G Suite, MailStore Server requires a service account which has been granted permission to access the G Suite account. The same service account is later used for archiving email from G Suite, too.
 
  
=== Creating a Project ===
+
In MailStore Server 13, support for modern authentication methods via OAuth 2.0 & OpenID Connect as per Google's recommendation was introduced. Although MailStore Server 13 still comes with support for IMAP-based authentication, this document only covers the setup using modern authentication methods as required by Google in the future.</p>
Before MailStore is able to connect to G Suite accounts, a project has to be created. In Google's terminology, a project is the collection of all settings, credentials and meta data of an application that uses Google Developer APIs or Google Cloud resources.
 
  
* Go to the [https://console.developers.google.com/ Google Developers Console].
+
== Prerequisites and Recommendations ==
* If prompted, login using a Google Account with administrative rights.
+
* To comply with Google's requirements for ''Authorized redirect URIs'' of  OAuth 2.0 clients, MailStore Server must be accessible via an URI that ends with a public top-level domain. Google uses the list from https://publicsuffix.org for validation.
* If no project exists, click ''Create'' on the dashboard. Otherwise open the ''Project'' drop-down list in the header bar and click ''New Project''.
+
* For best user experience, the certificate used by MailStore Server should be trusted by all client and the used Web Browsers. Using a certificate that is signed by an trusted certificate authority or [[Using_Lets_Encrypt_Certificates|using Let's Encrypt certificates]] is highly recommended.
* Name the project, e.g. ''MailStore API Access''. By default a random Project ID is assigned, change it if desired. Click ''Create''.
 
* Once the project has been created, ''APIs & Services'' is shown.
 
* Make sure you have selected the newly created project. You can change the project by using the drop-down list.
 
* Navigate to the ''API library''.
 
* In the library, enable ''Admin SDK'' and ''Gmail API''. You can navigate back to the overview by clicking ''Google APIs'' in the top navigation bar.
 
* In ''Credentials'', click ''Create Credentials'' then select ''Service account key'' from the drop-down list.
 
* Select ''New service account'' from the ''Service account'' drop-down list.
 
* Enter a name for the service account key. The service account does not require permissions on project level, therefore do not select a role.
 
* Select the ''JSON'' key type and click on ''Create''.
 
* Acknowledge the next dialog by clicking ''Create without role''.
 
* The JSON file will be downloaded. Save the JSON file (e.g. <tt>MailStore API Access-e035d2ad4f35.json</tt>) to a folder on the MailStore Server.
 
* Close the ''Private key saved to your computer'' dialog.
 
* Click on ''Manage service accounts''.
 
* Click on the 3-dots-drop-down list and select "Edit".
 
* In the "Edit service account" dialog, click ''Show domain-wide delegation'' and check the box ''Enable G Suite Domain-wide Delegation''.
 
* Enter ''MailStore'' as ''Product name for the consent screen''.
 
* Click on ''Save''.
 
* Click on the service account to see its service account details. Note the unique ID (Client ID) and the email address shown for use in the next step.
 
  
=== Grant access to the required APIs ===
+
== Register Project with Google ==
Once created, grant the project access to the APIs used by MailStore Server's Directory Services module.
+
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.
  
* Go to your G Suite domain’s [https://admin.google.com/ Admin console].
+
=== Create New Project ===
* Select ''Security'' from the list of controls. If you don't see ''Security'' listed, select ''More controls'' from the gray bar at the bottom of the page, then select ''Security'' from the list of controls. If you can't see the controls, make sure you're signed in as an administrator for the domain.
+
To register a project  for MailStore Server with Google, proceed as follows:
* Click on ''Basic Settings''.
+
 
* Make sure that the setting under ''Less secure apps'' is '''not''' set to ''Disable access to less secure apps for all users (Recommended)''. If it is, choose one of the other options and save the changes.
+
* Go to the [https://console.developers.google.com Google Developers Console].
* Navigate back to ''Security''.
+
* If prompted, login using a Google account of you G Suite organization. Logging in with a user that has admin privileges is highly recommend.
* Select ''API reference'' from the list of options.
+
* 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''.
* Enable the ''API access'' and save the changes.
+
* Type in a meaningful name into the ''Project name'' field, e.g. "MailStore Server".
* Select ''Advanced settings'' from the list of options. If this section is not visible, click on ''Show more'' first.
+
* Verify that ''Organization'' matches the desired organization and adjust the ''Location'' if needed.
* Select ''Manage API client access'' in the ''Authentication'' section.
+
* Click on ''Create''.
* In the ''Client name'' field enter the service account's ''Unique ID (Client ID)'' (e.g. ''108878593494909748351'').
+
 
* In the ''One or More API Scopes'' field enter the following scopes:
+
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:
 +
*: <tt>Admin SDK</tt>
 +
*: <tt>Gmail API</tt>
 +
 
 +
==== 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 to synchronize users and group, and to access user mailboxes. 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 ''Close'' and then ''Done''.
 +
* Edit the details of the newly created service account by clicking on the corresponding pencil icon.
 +
* Click ''Show Domain-wide Delegation''.
 +
* Tick the ''Enable G Suite Domain-wide Delegation'' box.
 +
* Click ''Save''.
 +
 
 +
On the ''Credentials'' page, there should be a service account listed under ''Service Accounts'' with a corresponding client listed under ''OAuth 2.0 Client IDs''.
 +
 
 +
=== Create OAuth 2.0 Client for  ===
 +
To allow users to log in to MailStore by authenticating with Google, an OAuth 2.0 Client must be created as described below.
 +
 
 +
* Open the ''Navigation menu'' and select ''APIs & Services'' > '''Credentials''.
 +
* 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".
 +
* Click ''+ Add URI'' under ''Authorized redirect URIs''.
 +
* Enter the URI that is reachable by clients in the ''URIs'' using the the following scheme:
 +
*:<tt>https://<host>.<domain.tld>[:<port>]/oidc/signin</tt>
 +
 
 +
 
 +
== Grant 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 [https://admin.google.com/ 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:
 
*: <tt><nowiki>https://mail.google.com/, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.user.readonly</nowiki></tt>
 
*: <tt><nowiki>https://mail.google.com/, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.user.readonly</nowiki></tt>
 
* Click ''Authorize''.
 
* Click ''Authorize''.

Latest revision as of 17:17, 28 May 2020

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 are read from the G Suite account and recorded in MailStore Server's user database. No changes are made to the G Suite account itself by MailStore Server. The scope of the synchronization can be limited through filters.

Please note that on December 16th 2019 Google announced to limit access to G Suite for less secure apps in the future. This includes any MailStore Server version prior to 13, which therefore will no longer be able to authenticate users against G Suite when trying to log into MailStore Server. In MailStore Server 13, support for modern authentication methods via OAuth 2.0 & OpenID Connect as per Google's recommendation was introduced. Although MailStore Server 13 still comes with support for IMAP-based authentication, this document only covers the setup using modern authentication methods as required by Google in the future.

Prerequisites and Recommendations

  • To comply with Google's requirements for Authorized redirect URIs of OAuth 2.0 clients, MailStore Server must be accessible via an URI that ends with a public top-level domain. Google uses the list from https://publicsuffix.org for validation.
  • For best user experience, the certificate used by MailStore Server should be trusted by all client and the used Web Browsers. Using a certificate that is signed by an trusted certificate authority or using Let's Encrypt certificates is highly recommended.

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 to synchronize users and group, and to access user mailboxes. 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 Close and then Done.
  • Edit the details of the newly created service account by clicking on the corresponding pencil icon.
  • Click Show Domain-wide Delegation.
  • Tick the Enable G Suite Domain-wide Delegation box.
  • Click Save.

On the Credentials page, there should be a service account listed under Service Accounts with a corresponding client listed under OAuth 2.0 Client IDs.

Create OAuth 2.0 Client for

To allow users to log in to MailStore by authenticating with Google, an OAuth 2.0 Client must be created as described below.

  • Open the Navigation menu and select APIs & Services > 'Credentials.
  • 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".
  • Click + Add URI under Authorized redirect URIs.
  • Enter the URI that is reachable by clients in the URIs using the the following scheme:
    https://<host>.<domain.tld>[:<port>]/oidc/signin


Grant 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 Privileges and then on Directory Services.
  • In the Integration section, change the directory service type to G Suite.
Gapps sync 01.png


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. admin@example.com).

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 user database by the synchronization. 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. Additionally, only MailStore users that have their authentication method set to Directory Services will be deleted.

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.

ApplicationIntegration sync 02.png


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 via Standard Authentication with their G Suite Account username and G Suite Account password.

Navigation
Tools
Print/export
About MailStore

  • MailStore Server is one of the leading email archiving solutions for SMB.
  • For private use there is a free tool for email archiving furthermore: MailStore Home.