Difference between revisions of "Google Workspace Integration"

[unchecked revision][checked revision]
 
(31 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:Synchronizing User Accounts with G Suite}}
+
{{DISPLAYTITLE:Synchronizing User Accounts with Google Workspace}}
{{Directory Services Preamble|G Suite account}}
+
{{Directory Services Preamble|Google Workspace account|Google Workspace}}
  
<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 accounts for less secure apps in the future.  This affects 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.
+
<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 Google Workspace accounts for less secure apps in the future.  This affects any MailStore Server version prior to 13, which therefore will no longer be able to authenticate users against Google Workspace when trying to log into MailStore Server.
 
<br/>
 
<br/>
 
<br/>
 
<br/>
Line 9: Line 9:
 
== Prerequisites, Recommendations, Limitations ==
 
== Prerequisites, Recommendations, Limitations ==
 
* 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. This does not necessarily mean that it must  indeed be accessible from the Internet. Google uses the list from https://publicsuffix.org for validation.
 
* 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. This does not necessarily mean that it must  indeed be accessible from the Internet. 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_Lets_Encrypt_Certificates|using Let's Encrypt certificates]] is highly recommended.
+
* 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.
* If users are supposed to login to MailStore Server from outside the organization's network without a VPN, using [[Accessing_the_Archive_with_the_MailStore_Client_software|MailStore Client]], [[Accessing_the_Archive_with_the_Microsoft_Outlook_integration|MailStore Outlook Add-in]], or the [[Accessing_the_Archive_with_MailStore_Web_Access|Web Access]], the URIs mentioned in this article must be resolvable via DNS on the Internet and port-forwardings to the MailStore Server computer must be setup on the firewall or router if necessary.  
+
* If users are supposed to login to MailStore Server from outside the organization's network without a VPN, using [[Accessing_the_Archive_with_the_MailStore_Client_software|MailStore Client]], [[Accessing_the_Archive_with_the_Microsoft_Outlook_integration|MailStore Outlook Add-in]] or the [[Accessing_the_Archive_with_MailStore_Web_Access|Web Access]], the URIs mentioned in this article must be resolvable via DNS on the Internet and port-forwardings to the MailStore Server computer must be set up on the firewall or router if necessary.  
 
* When using Google to authenticate users at login, [[Accessing_the_Archive_via_Integrated_IMAP_Server|accessing the archive via IMAP]] is not possible for technical reasons.
 
* When using Google to authenticate users at login, [[Accessing_the_Archive_via_Integrated_IMAP_Server|accessing the archive via IMAP]] is not possible for technical reasons.
  
 
== Register Project with Google ==
 
== 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 necessary  minimum and that each application uses its own set of credentials to authenticate with Google.
+
Regardless of whether own or third-party applications such as MailStore Server are supposed to interact with a Google Workspace 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 necessary  minimum and that each application uses its own set of credentials to authenticate with Google.
  
 
=== Create New Project ===
 
=== Create New Project ===
 
To register a project  for MailStore Server with Google, proceed as follows:
 
To register a project  for MailStore Server with Google, proceed as follows:
  
* Go to the [https://console.developers.google.com Google Developers Console].
+
* Go to the [https://console.cloud.google.com Google Cloud Platform 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 prompted, login using a Google account of you Google Workspace organization. Logging in with a user that has admin privileges is highly recommended.  
* 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''.
+
* 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".
+
* Type in a meaningful name into the ''Project name'' field, e.g. <tt>MailStore Server</tt>.
 
* Verify that ''Organization'' matches the desired organization and adjust the ''Location'' if needed.
 
* Verify that ''Organization'' matches the desired organization and adjust the ''Location'' if needed.
 
* Click on ''Create''.
 
* Click on ''Create''.
Line 29: Line 29:
  
 
==== Add API Libraries ====
 
==== Add API Libraries ====
* Open the ''Navigation menu (☰)''  and select ''APIs & Services'' > ''Library''.
+
* Open the ''Navigation menu'' (☰) and select ''APIs & Services'' > ''Library''.
 
* In the ''API Library'', search and enable the following APIs and services:
 
* In the ''API Library'', search and enable the following APIs and services:
*: <tt>Admin SDK</tt>
+
*: <tt>Admin SDK API</tt>
 
*: <tt>Gmail API</tt>
 
*: <tt>Gmail API</tt>
  
 
==== Customize Consent Screen ====
 
==== Customize Consent Screen ====
* Open the ''Navigation menu'' and select ''APIs & Services'' > ''OAuth consent screen''.
+
* Open the ''Navigation menu'' (☰) and select ''APIs & Services'' > ''OAuth consent screen''.
 
* Under ''User Type'' select ''Internal''.
 
* Under ''User Type'' select ''Internal''.
* Click ''Create''
+
* Click ''Create''.
* Type in a meaningful name into the ''Application name'' field, e.g. "MailStore Server"
+
* Enter a meaningful name into the ''App name'' field, e.g. <tt>MailStore Server</tt>.
* Click ''Save''.
+
* Fill out the other fields according to the policies of your organization.
 +
* Click ''Save and Continue''.
 +
* In the next steps, directly click ''Save and Continue'' again as MailStore Server does not need users to authorize any scopes.
  
 
=== Create Service Account ===
 
=== 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.
+
A service account is required for MailStore Server to authenticate with Google and request authorization to use certain Google APIs for synchronizing users and accessing mailboxes. Follow these steps to create such a service account.
  
 
* Open the ''Navigation menu'' (☰) and select ''APIs & Services'' > ''Credentials''.
 
* Open the ''Navigation menu'' (☰) and select ''APIs & Services'' > ''Credentials''.
 
* Click ''+ Create Credentials'' and select ''Service account'' from the drop-down list.
 
* 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".
+
* On the ''Create service account'' page, enter a name for the service account, e.g. <tt>MailStore Server Service</tt>.
* Enter a description such as "Service account for MailStore Server to synchronize users and access mailboxes"
+
* You can leave the the service account id at default settings or customize it.
* Click ''Create''.
+
* Enter a description such as: <tt>Service account for MailStore Server to synchronize users and access mailboxes</tt>.
* The service account does not require permissions on project level, therefore do not select a role.
+
* Click ''Create and Continue''.
* Click ''Continue''.
+
* The service account does not require permissions on project level, therefore do not select a role. Also, users do not need access to the service account, so no changes are needed in the ''Grant users access to this service account'' step.
* Users do not need access to the service account, so no changes are needed in the ''Grant users access to this service account'' step.
+
* Click ''Done''.
* Click ''Done''
+
* In the list of service accounts that is now displayed, click on the newly created service account to open its properties.
* Back on the ''Credentials'' page, click on the newly created service account to open its properties.
 
 
* Under ''Keys'' click on ''Add Key'' and select ''Create new key''.
 
* Under ''Keys'' click on ''Add Key'' and select ''Create new key''.
 
* Select ''JSON'' as key type and click ''Create''.
 
* 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.
 
* 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''.
 
* Click ''Close''.
* Click ''Show Domain-wide Delegation''.
+
* Back under ''Details'', click ''Show Advanced Settings''.
* Tick the ''Enable G Suite Domain-wide Delegation'' box.
+
* In the ''Domain-wide Delegation'' section, copy the ''Client ID'' to the clipboard.
* Click ''Save''.
+
* Open the [https://admin.google.com/ Google Workspace Admin Console] by clicking on the button and log in with your Google Workspace domain admin credentials.
 
+
* Open the ''Navigation menu'' (☰) and select ''Security'' > ''Access and data control'' > ''API controls''.
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''.
+
* Under ''Domain wide delegation'', click ''Manage domain wide delegation''.
 +
* On the ''Domain-wide delegation'' page, click ''Add new''.
 +
* Copy the ''Client ID'' of the OAuth 2.0 Client that is linked with the service account from the clipboard.
 +
* 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>
 +
* Click ''Authorize''.
  
 
=== Create OAuth 2.0 Client for User Authentication ===
 
=== Create OAuth 2.0 Client for User Authentication ===
To allow users to log in to MailStore by authenticating with Google using the OpenID Connect mechanism, an OAuth 2.0 Client must be created as described below.
+
To allow users to log in to MailStore Server by authenticating with Google using the OpenID Connect mechanism, another OAuth 2.0 client must be created as described below.
  
 +
* Go to the [https://console.cloud.google.com Google Cloud Platform Console].
 
* Open the ''Navigation menu'' (☰) and select ''APIs & Services'' > ''Credentials''.
 
* Open the ''Navigation menu'' (☰) and select ''APIs & Services'' > ''Credentials''.
 
* Click ''+ Create Credentials'' and select ''OAuth client ID'' from the drop-down list.
 
* Click ''+ Create Credentials'' and select ''OAuth client ID'' from the drop-down list.
 
* Select ''Web application'' as ''Application type''.
 
* Select ''Web application'' as ''Application type''.
* Enter a ''Name'', e.g. "MailStore Server OpenID Connect".
+
* Enter a ''Name'', e.g. <tt>MailStore Server OpenID Connect</tt>.
 
* Click ''+ Add URI'' under ''Authorized redirect URIs''.
 
* Click ''+ Add URI'' under ''Authorized redirect URIs''.
 
* Enter the URI that is reachable by clients in the ''URIs'' field using the the following scheme:
 
* Enter the URI that is reachable by clients in the ''URIs'' field using the the following scheme:
 
*:<tt>https://<fqdn>[:<port>]/oidc/signin</tt>
 
*:<tt>https://<fqdn>[:<port>]/oidc/signin</tt>
 
*; with the following components:
 
*; with the following components:
*: '''https://'''<br/>Specifying the protocol ''https://'' is mandatory. To prevent certificate warnings later at login, the [[MailStore_Server_Service_Configuration#Certificate|certificate used by MailStore Server]] must be trusted by all client and the used Web Browsers.  
+
*: '''https://'''<br/>Specifying the protocol ''https://'' is mandatory. To prevent certificate warnings later at login, the [[MailStore_Server_Service_Configuration#Certificate|certificate used by MailStore Server]] must be trusted by all client and the used web browsers.  
 
*: '''FQDN'''<br/>The fully qualified domain name of the MailStore Server computer, e.g. <tt>mailstore.example.com</tt>. This must be resolvable from all clients, from where users are supposed to log in to MailStore Server.
 
*: '''FQDN'''<br/>The fully qualified domain name of the MailStore Server computer, e.g. <tt>mailstore.example.com</tt>. This must be resolvable from all clients, from where users are supposed to log in to MailStore Server.
*: '''Port'''<br/>The TCP port of MailStore Web Access (default: <tt>8462</tt>). This must match the port configured in [[MailStore Server Service Configuration#Services]] at ''Network Settings'' > ''Services'' > ''MailStore Web Access / Outlook Add-in (HTTPS)''. The TCP port is only required, if it different from the default port of the HTTPS protocol (443).
+
*: '''Port'''<br/>The TCP port of MailStore Web Access (default: <tt>8462</tt>). This must match the port configured in the [[MailStore Server Service Configuration#Services|MailStore Server Service Configuration]] at ''Network Settings'' > ''Services'' > ''MailStore Web Access / Outlook Add-in (HTTPS)''. The TCP port is only required if it is different from the default port of the HTTPS protocol (443).
*: '''/oidc/signin'''<br/>The path at which MailStore Server expects to receive then authentication response from Google via the web browser.
+
*: '''/oidc/signin'''<br/>The path at which MailStore Server expects to receive the authentication response from Google via the web browser.
 
+
* Click ''Create'' to finish.
::{| class="wikitable"
+
* Copy the client ID and client secret from the ''Your Client ID'' and ''Your Client Secret'' fields to a safe place (e.g. password safe or similar) and click ''OK''.
 +
<div class="resp-table">
 +
{| class="wikitable" style="font-size: 85%;"
 
|+ Examples of valid redirect URIs
 
|+ Examples of valid redirect URIs
 
|-
 
|-
! Computername
+
! style="width:80px;" | Product
! style="width:90px;" | DNS Domain
+
! style="width:80px;" | FQDN
! style="width:60px;" | TCP Port
+
! style="width:40px;" | Port
 
! Resulting Redirect URI
 
! Resulting Redirect URI
 
|-
 
|-
| align="center"| mailstore
+
| align="center"| MailStore Server
| align="center"| example.com
+
| align="center"| mailstore.example.com
 
| align="center"| 8462
 
| align="center"| 8462
| <code><nowiki>https://mailstore.example.com:8462/oidc/signin</nowiki></code><br/><br/>Redirect URI with fully qualified domain name and MailStore Web Acces default port.
+
| <code><nowiki>https://mailstore.example.com:8462/oidc/signin</nowiki></code><br/><br/>Redirect URI with fully qualified domain name and MailStore Web Access default port.
 
|-
 
|-
| align="center"| mailstore
+
| align="center"| MailStore Server
| align="center"| example.com
+
| align="center"| mailstore.example.com
 
| align="center"| 443
 
| align="center"| 443
 
| <code><nowiki>https://mailstore.example.com/oidc/signin</nowiki></code><br/><br/>If the HTTPS default port 443 is used for MailStore Web Access or as source of a port forwarding rule on a firewall, specifying the port as part of the redirect URI can be omitted.
 
| <code><nowiki>https://mailstore.example.com/oidc/signin</nowiki></code><br/><br/>If the HTTPS default port 443 is used for MailStore Web Access or as source of a port forwarding rule on a firewall, specifying the port as part of the redirect URI can be omitted.
 +
|-
 +
| align="center"| MailStore SPE
 +
| align="center"| archive.example.com
 +
| align="center"| 443
 +
| <code><nowiki>https://archive.example.com/<instanceid>/oidc/signin</nowiki></code><br/><br/>The ''instanceid'' of the instance is part of the Redirect URI.
 
|-
 
|-
 
|}
 
|}
* Click ''Create'' to finish.
+
</div>
* Copy the client ID and client secret from the ''Your Client ID'' and ''Your Client Secret'' fields to a safe place (e.g. password safe or similar) and click ''OK''.
 
 
 
== Grant Access on G Suite Account to Project ==
 
Once created, grant the new 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.
 
* Open the ''Navigation menu'' (☰) and select ''Security'' > ''API controls''.
 
* 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>
 
* Click ''Authorize''.
 
  
 
== Configure MailStore Server ==
 
== Configure MailStore Server ==
After the project has been successfully set up on the Google side, MailStore Server can now be configured to synchronize and authenticate users with G Suite.
+
After the project has been successfully set up on the Google side, MailStore Server can now be configured to synchronize and authenticate users with Google Workspace.
  
{{Directory Services Accessing Configuration|G Suite|gapps_sync_01.png}}
+
{{Directory Services Accessing Configuration|Google Workspace|gapps_sync_01.png}}
  
==== Connection ====
+
=== Connection ===
For synchronization MailStore Server requires information on how to connect to the G Suite.
+
For synchronization, MailStore Server requires information on how to connect to the Google Workspace.
  
 
* '''Key ID'''<br/>To import the private key, select the JSON file hat has been generated by Google for the service account in the [[#Create_Service_Account|Create Service Account]] step.
 
* '''Key ID'''<br/>To import the private key, select the JSON file hat has been generated by Google for the service account in the [[#Create_Service_Account|Create Service Account]] step.
 
* '''Service Account'''<br/>The service account is determined automatically from the JSON file.
 
* '''Service Account'''<br/>The service account is determined automatically from the JSON file.
* '''User Name'''<br/>The email address of a G Suite Administrator (e.g. [email protected]).
+
* '''User Name'''<br/>The email address of a Google Workspace Administrator (e.g. [email protected]).
  
 
=== User Database Synchronization ===
 
=== User Database Synchronization ===
After configuring the connection settings as described above, you can specify filter criteria for the G Suite synchronization in this section.
+
After configuring the connection settings as described above, you can specify filter criteria for the Google Workspace synchronization in this section.
  
* '''Sync only these groups'''<br/>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.
+
* '''Sync only these groups'''<br/>Choose one or several Google Workspace 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.
  
 
=== Authentication ===
 
=== Authentication ===
The authentication settings define how MailStore Server should authenticate users at login, that have been synchronized from G Suite.
+
The authentication settings define how MailStore Server should authenticate users at login, that have been synchronized from Google Workspace.
  
 
* '''Method'''<br/>Ensure that ''OpenID Connect'' is selected. As mentioned in the introduction, the ''IMAP'' option is only available for backward compatibility.
 
* '''Method'''<br/>Ensure that ''OpenID Connect'' is selected. As mentioned in the introduction, the ''IMAP'' option is only available for backward compatibility.
* '''Client ID'''<br/>Enter the client ID from the [[#Create_OAuth_2.0_Client_for_User_Authentication|Create_OAuth_2.0 Client…]] step.
+
* '''Client ID'''<br/>Enter the client ID from the [[#Create_OAuth_2.0_Client_for_User_Authentication|Create OAuth_2.0 Client…]] step.
* '''Client Secret'''<br/>Enter the client secret from the [[#Create_OAuth_2.0_Client_for_User_Authentication|Create_OAuth_2.0 Client…]] step.  
+
* '''Client Secret'''<br/>Enter the client secret from the [[#Create_OAuth_2.0_Client_for_User_Authentication|Create OAuth_2.0 Client…]] step.  
* '''Redirect Url'''<br/>Enter the same redirect URI as defined in the [[#Create_OAuth_2.0_Client_for_User_Authentication|Create_OAuth_2.0 Client…]] step .
+
* '''Redirect URI'''<br/>Enter the same redirect URI as defined in the [[#Create_OAuth_2.0_Client_for_User_Authentication|Create OAuth 2.0 Client…]] step .
  
{{Directory Services Options|G Suite Account}}
+
{{Directory Services Options|Google Workspace Account}}
{{Directory Services Assign Default Privileges|G Suite Account}}
+
{{Directory Services Assign Default Privileges|Google Workspace Account}}
{{Directory Services Run Synchronization|G Suite Account}}
+
{{Directory Services Run Synchronization|Google Workspace Account}}
 
[[File:ApplicationIntegration_sync_02.png|450px|center]]
 
[[File:ApplicationIntegration_sync_02.png|450px|center]]
 
  
 
{{Directory Services Test Authentication}}
 
{{Directory Services Test Authentication}}
{{Directory Services Login with Directory Services Credentials|G Suite Account|mads_ldapauth_01.png}}
+
[[de:Google Workspace-Integration]]
[[de:G Suite-Integration]]
+
[[en:Google Workspace Integration]]
[[en:G Suite Integration]]
 

Latest revision as of 10:31, 14 May 2022

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

During synchronization, user information, such as user names and email addresses, is copied from the Google Workspace account into MailStore Server's user database. That way, users can use their Google Workspace 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 Google Workspace 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 Google Workspace accounts for less secure apps in the future. This affects any MailStore Server version prior to 13, which therefore will no longer be able to authenticate users against Google Workspace 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, Recommendations, Limitations

  • 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. This does not necessarily mean that it must indeed be accessible from the Internet. 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.
  • If users are supposed to login to MailStore Server from outside the organization's network without a VPN, using MailStore Client, MailStore Outlook Add-in or the Web Access, the URIs mentioned in this article must be resolvable via DNS on the Internet and port-forwardings to the MailStore Server computer must be set up on the firewall or router if necessary.
  • When using Google to authenticate users at login, accessing the archive via IMAP is not possible for technical reasons.

Register Project with Google

Regardless of whether own or third-party applications such as MailStore Server are supposed to interact with a Google Workspace 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 necessary 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 Cloud Platform Console.
  • If prompted, login using a Google account of you Google Workspace organization. Logging in with a user that has admin privileges is highly recommended.
  • 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 API
    Gmail API

Customize Consent Screen

  • Open the Navigation menu (☰) and select APIs & Services > OAuth consent screen.
  • Under User Type select Internal.
  • Click Create.
  • Enter a meaningful name into the App name field, e.g. MailStore Server.
  • Fill out the other fields according to the policies of your organization.
  • Click Save and Continue.
  • In the next steps, directly click Save and Continue again as MailStore Server does not need users to authorize any scopes.

Create Service Account

A service account is required for MailStore Server to authenticate with Google and request authorization to use certain Google APIs for synchronizing users and accessing mailboxes. Follow these steps to create 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.
  • You can leave the the service account id at default settings or customize it.
  • Enter a description such as: Service account for MailStore Server to synchronize users and access mailboxes.
  • Click Create and Continue.
  • The service account does not require permissions on project level, therefore do not select a role. Also, users do not need access to the service account, so no changes are needed in the Grant users access to this service account step.
  • Click Done.
  • In the list of service accounts that is now displayed, click on the newly created service account to open its properties.
  • Under Keys click on Add Key and select Create new 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.
  • Back under Details, click Show Advanced Settings.
  • In the Domain-wide Delegation section, copy the Client ID to the clipboard.
  • Open the Google Workspace Admin Console by clicking on the button and log in with your Google Workspace domain admin credentials.
  • Open the Navigation menu (☰) and select Security > Access and data control > API controls.
  • Under Domain wide delegation, click Manage domain wide delegation.
  • On the Domain-wide delegation page, click Add new.
  • Copy the Client ID of the OAuth 2.0 Client that is linked with the service account from the clipboard.
  • 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.

Create OAuth 2.0 Client for User Authentication

To allow users to log in to MailStore Server by authenticating with Google using the OpenID Connect mechanism, another OAuth 2.0 client must be created as described below.

  • Go to the Google Cloud Platform Console.
  • 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 field using the the following scheme:
    https://<fqdn>[:<port>]/oidc/signin
    with the following components
    https://
    Specifying the protocol https:// is mandatory. To prevent certificate warnings later at login, the certificate used by MailStore Server must be trusted by all client and the used web browsers.
    FQDN
    The fully qualified domain name of the MailStore Server computer, e.g. mailstore.example.com. This must be resolvable from all clients, from where users are supposed to log in to MailStore Server.
    Port
    The TCP port of MailStore Web Access (default: 8462). This must match the port configured in the MailStore Server Service Configuration at Network Settings > Services > MailStore Web Access / Outlook Add-in (HTTPS). The TCP port is only required if it is different from the default port of the HTTPS protocol (443).
    /oidc/signin
    The path at which MailStore Server expects to receive the authentication response from Google via the web browser.
  • Click Create to finish.
  • Copy the client ID and client secret from the Your Client ID and Your Client Secret fields to a safe place (e.g. password safe or similar) and click OK.
Examples of valid redirect URIs
Product FQDN Port Resulting Redirect URI
MailStore Server mailstore.example.com 8462 https://mailstore.example.com:8462/oidc/signin

Redirect URI with fully qualified domain name and MailStore Web Access default port.
MailStore Server mailstore.example.com 443 https://mailstore.example.com/oidc/signin

If the HTTPS default port 443 is used for MailStore Web Access or as source of a port forwarding rule on a firewall, specifying the port as part of the redirect URI can be omitted.
MailStore SPE archive.example.com 443 https://archive.example.com/<instanceid>/oidc/signin

The instanceid of the instance is part of the Redirect URI.

Configure MailStore Server

After the project has been successfully set up on the Google side, MailStore Server can now be configured to synchronize and authenticate users with Google Workspace.

  • 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 Google Workspace.
Gapps sync 01.png


Connection

For synchronization, MailStore Server requires information on how to connect to the Google Workspace.

  • Key ID
    To import the private key, select the JSON file hat has been generated by Google for the service account in the Create Service Account step.
  • Service Account
    The service account is determined automatically from the JSON file.
  • User Name
    The email address of a Google Workspace Administrator (e.g. [email protected]).

User Database Synchronization

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

  • Sync only these groups
    Choose one or several Google Workspace 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.

Authentication

The authentication settings define how MailStore Server should authenticate users at login, that have been synchronized from Google Workspace.

Options

  • Automatically delete users in MailStore Server
    Here you can choose whether users that have been deleted in the Google Workspace 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 Google Workspace 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 Google Workspace 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.