Difference between revisions of "Google Workspace Integration"

[unchecked revision][unchecked revision]
Line 2: Line 2:
 
{{Directory Services Preamble|G Suite account}}
 
{{Directory Services Preamble|G Suite account}}
  
== Prepare the G Suite account ==
+
== Register Project with Google ==
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.
+
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 itself.
  
=== Creating a Project ===
+
To register a project for MailStore with Google, proceed as described in the following.
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.
 
  
 +
=== Creating New Project ===
 
* Go to the [https://console.developers.google.com/ Google Developers Console].
 
* Go to the [https://console.developers.google.com/ Google Developers Console].
 
* If prompted, login using a Google Account of you G Suite organization. A user with administrative privileges is highly recommend.  
 
* If prompted, login using a Google Account of you G Suite organization. A user with administrative privileges is highly recommend.  
 
* If no project exists, click ''Create'' on the dashboard. Otherwise open the ''Project'' drop-down list in the header bar and click ''New Project''.
 
* If no project exists, click ''Create'' on the dashboard. Otherwise open the ''Project'' drop-down list in the header bar and click ''New Project''.
* Name the project, e.g. ''MailStore API Access''. By default a random Project ID is assigned, change it if desired. Click ''Create''.
+
* Name the project, e.g. ''MailStore Server''. By default a random Project ID is assigned, which can be changed if desired.  
 +
* Click on ''Create''.
 
* Once the project has been created, ''APIs & Services'' is shown.
 
* Once the project has been created, ''APIs & Services'' is shown.
 
* Make sure that you have selected the newly created project. You can change the project by using the drop-down list.
 
* Make sure that you have selected the newly created project. You can change the project by using the drop-down list.
==== Adding API Libraries ====
+
 
 +
=== Adding API Libraries ===
 +
To specify which Google APIs are used by the application, proceed as follows:
 +
 
 
* Click on ''Library'' in the left navigation pane.
 
* Click on ''Library'' in the left navigation pane.
 
* In the ''API Library'', enable ''Admin SDK'' and ''Gmail API''.  
 
* In the ''API Library'', enable ''Admin SDK'' and ''Gmail API''.  
 
* Return to the project's dashboard by clicking on ''Google APIs'' in the top navigation bar.
 
* Return to the project's dashboard by clicking on ''Google APIs'' in the top navigation bar.
==== Adding Credentials ====
+
 
 +
=== Customizing Consent Screen ===
 +
A consent screen must exist before a domain-wide delegation of authority can be performed.
 +
 
 +
* Click on ''OAuth consent screen'' in the left navigation pane.
 +
* Select ''Internal'' as ''User Type''.
 +
* Click on ''Create''
 +
* Fill in the following information:
 +
** '''Application name'''<br/>Enter a meaningful Name that helps user to identify the application, e.g. ''MailStore''
 +
** '''Authorized domains'''<br/>Enter the domain under which the MailStore Server is located, e.g. <tt>example.com</tt> if MailStore Server is accessible through <tt>mailstore.example.com</tt>.
 +
* Click on ''Save''.
 +
 
 +
=== Creating Service Account ===
 +
The following steps create a service account and its credentials which are used by MailStore to login to Google APIs.
 +
 
 
* Click on ''Credentials''' in the left navigation pane.
 
* Click on ''Credentials''' in the left navigation pane.
 
* Click ''Create Credentials'' and select ''Service account'' from the drop-down list.
 
* Click ''Create Credentials'' and select ''Service account'' from the drop-down list.
Line 29: Line 47:
 
* Select the ''JSON'' as key type and click on ''Create''.
 
* Select the ''JSON'' as key type and click on ''Create''.
 
* The JSON file will be downloaded automatically. Save the JSON file (e.g. <tt>MailStore API Access-e035d2ad4f35.json</tt>) in a secure location as it allows access to cloud resources of your organization.
 
* The JSON file will be downloaded automatically. Save the JSON file (e.g. <tt>MailStore API Access-e035d2ad4f35.json</tt>) in a secure location as it allows access to cloud resources of your organization.
* Click on ''Close'' and then on ''Done'' to finish the creation of credentials.  
+
* Click on ''Close'' and then on ''Done'' to finish the creation of credentials.
* Click on the newly created service account to access details.
+
 
 +
===
 +
To grant MailStore domain-wide access to your G Suite account, domain-wide delegation must be enabled as described in the steps below.
 +
 
 +
* Click on the newly created service account to access its details.
 
* Click on ''Show Domain-wide Delegation''.
 
* Click on ''Show Domain-wide Delegation''.
 
* Check the ''Enable G Suite Domain-wide Delegation'' box.
 
* Check the ''Enable G Suite Domain-wide Delegation'' box.
 
* Click on ''Save''.
 
* Click on ''Save''.
==== Customize Consent Screen ====
 
* Click on ''OAuth consent screen'' in the left navigation pane.
 
* Select ''Internal'' as ''User Type''.
 
* Click on ''Create''
 
* Fill in the following information:
 
** '''Application name'''<br/>Enter a meaningful Name that helps user to identify the application, e.g. ''MailStore''
 
** '''Authorized domains'''<br/>Enter the domain under which the MailStore Server is located, e.g. <tt>example.com</tt> if MailStore Server is accessible through <tt>mailstore.example.com</tt>.
 
* Click on ''Save''.
 
  
=== Grant access to the required APIs ===
+
As a result, a new ''OAuth 2.0 Client'' was created for the service account that has been created in the previous step.
Once created, grant the project access to the APIs used by MailStore Server's Directory Services module.
+
 
 +
== Granting Access on G Suite ==
 +
Once created, grant the newly created project fine grained access to your G Suite tenant by defining the Google APIs it is allowed to use.
  
 
* Go to your G Suite domain’s [https://admin.google.com/ Admin console].
 
* Go to your G Suite domain’s [https://admin.google.com/ Admin console].

Revision as of 10:05, 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, 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 itself.

To register a project for MailStore with Google, proceed as described in the following.

Creating New Project

  • Go to the Google Developers Console.
  • If prompted, login using a Google Account of you G Suite organization. A user with administrative privileges is highly recommend.
  • If no project exists, click Create on the dashboard. Otherwise open the Project drop-down list in the header bar and click New Project.
  • Name the project, e.g. MailStore Server. By default a random Project ID is assigned, which can be changed if desired.
  • Click on Create.
  • Once the project has been created, APIs & Services is shown.
  • Make sure that you have selected the newly created project. You can change the project by using the drop-down list.

Adding API Libraries

To specify which Google APIs are used by the application, proceed as follows:

  • Click on Library in the left navigation pane.
  • In the API Library, enable Admin SDK and Gmail API.
  • Return to the project's dashboard by clicking on Google APIs in the top navigation bar.

Customizing Consent Screen

A consent screen must exist before a domain-wide delegation of authority can be performed.

  • Click on OAuth consent screen in the left navigation pane.
  • Select Internal as User Type.
  • Click on Create
  • Fill in the following information:
    • Application name
      Enter a meaningful Name that helps user to identify the application, e.g. MailStore
    • Authorized domains
      Enter the domain under which the MailStore Server is located, e.g. example.com if MailStore Server is accessible through mailstore.example.com.
  • Click on Save.

Creating Service Account

The following steps create a service account and its credentials which are used by MailStore to login to Google APIs.

  • Click on Credentials' in the left navigation pane.
  • Click Create Credentials and select Service account from the drop-down list.
  • On the Create service account screen, enter a name for the service account. The Service account ID gets updated automatically based on the service account name, but can be changed if desired.
  • Click on Continue.
  • The service account does not require permissions on project level, therefore do not select a role.
  • Click on Continue.
  • Only grant other users access to this service account if absolutely necessary, which is typically not the case.
  • Click on Create Key in the Keys section.
  • Select the JSON as key type and click on Create.
  • The JSON file will be downloaded automatically. Save the JSON file (e.g. MailStore API Access-e035d2ad4f35.json) in a secure location as it allows access to cloud resources of your organization.
  • Click on Close and then on Done to finish the creation of credentials.

=

To grant MailStore domain-wide access to your G Suite account, domain-wide delegation must be enabled as described in the steps below.

  • 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.

Granting Access on G Suite

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

  • Go to your G Suite domain’s Admin console.
  • 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.
  • Select API reference from the list of options.
  • Enable the API access and save the changes.
  • Select Advanced settings from the list of options. If this section is not visible, click on Show more first.
  • Select Manage API client access in the Authentication section.
  • 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:
    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.
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. [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.

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