Difference between revisions of "Synchronizing User Accounts with Microsoft 365 (Modern Authentication)"

[unchecked revision][unchecked revision]
(Created page with "{{Directory Services Preamble|Microsoft 365 tenant|Microsoft 365}} == Prerequisites, Recommendations and Limitations == * For best user experience, the certificate used by Ma...")
 
Line 8: Line 8:
 
== Connecting MailStore Server and Microsoft 365 ==
 
== Connecting MailStore Server and Microsoft 365 ==
 
In order to synchronize user information from Microsoft 365, MailStore Server has to be connected to your Microsoft 365 tenant and been granted the required permissions. Microsoft 365 relies on Azure Active Directory as directory service. Each Microsoft 365 tenant corresponds to an Azure AD tenant that stores its user information.
 
In order to synchronize user information from Microsoft 365, MailStore Server has to be connected to your Microsoft 365 tenant and been granted the required permissions. Microsoft 365 relies on Azure Active Directory as directory service. Each Microsoft 365 tenant corresponds to an Azure AD tenant that stores its user information.
 +
 
=== Registering of MailStore Server as App in Azure AD ===
 
=== Registering of MailStore Server as App in Azure AD ===
 
Through registration, MailStore Server gets an identity in Azure AD that makes it possible to authenticate to the tenant's services and use their resources.
 
Through registration, MailStore Server gets an identity in Azure AD that makes it possible to authenticate to the tenant's services and use their resources.
Line 18: Line 19:
 
* Click on ''Register''. If the registration has been successful, you are shown the overview page of the newly registered app.
 
* Click on ''Register''. If the registration has been successful, you are shown the overview page of the newly registered app.
 
The ''Application (client) ID'' shown on this page identifies MailStore Server in your Azure AD tenant and has to be copied into MailStore Server next, together with the ''Directory (tenant) ID''. Therefore, for the following steps, leave the overview page open in your web browser.
 
The ''Application (client) ID'' shown on this page identifies MailStore Server in your Azure AD tenant and has to be copied into MailStore Server next, together with the ''Directory (tenant) ID''. Therefore, for the following steps, leave the overview page open in your web browser.
 +
 
=== Creating Credentials in MailStore Server ===
 
=== Creating Credentials in MailStore Server ===
 
Credentials for Microsoft 365 consist of the aforementioned IDs and a secret that MailStore Server uses to proof its identity to Azure AD. Microsoft recommends using certificates as secrets to identify apps in Azure AD. When creating credentials, such a certificate is generated automatically by MailStore Server but can also be recreated later on.
 
Credentials for Microsoft 365 consist of the aforementioned IDs and a secret that MailStore Server uses to proof its identity to Azure AD. Microsoft recommends using certificates as secrets to identify apps in Azure AD. When creating credentials, such a certificate is generated automatically by MailStore Server but can also be recreated later on.
Line 24: Line 26:
 
* In the ''Credential Manager'' that appears, click on ''Create…''
 
* In the ''Credential Manager'' that appears, click on ''Create…''
 
* In the ''Azure AD App Credentials'' dialog, enter the following information in the ''Settings'' section:
 
* In the ''Azure AD App Credentials'' dialog, enter the following information in the ''Settings'' section:
** '''Name'''<br> A meaningful display name for the credentials, e.g. the name of your Microsoft 365 tenant.
+
** '''Name'''<br/> A meaningful display name for the credentials, e.g. the name of your Microsoft 365 tenant.
** '''Application (client) ID'''<br> The value of the corresponding field that you can copy from the Azure AD app overview page in your web browser.
+
** '''Application (client) ID'''<br/> The value of the corresponding field that you can copy from the Azure AD app overview page in your web browser.
** '''Directory (tenant) ID'''<br> The value of the corresponding field that you can copy from the Azure AD app overview page in your web browser.
+
** '''Directory (tenant) ID'''<br/> The value of the corresponding field that you can copy from the Azure AD app overview page in your web browser.
 
[[File:placeholder.png|center|450px]]
 
[[File:placeholder.png|center|450px]]
 
* In the ''Authentication'' section, click on the drop-down button next to the ''Certificate'' text box und select ''Download Certificate''. Save the certificate on your hard drive.
 
* In the ''Authentication'' section, click on the drop-down button next to the ''Certificate'' text box und select ''Download Certificate''. Save the certificate on your hard drive.
Line 33: Line 35:
 
* Leave the ''Credential Manager'' by clicking ''Close''.
 
* Leave the ''Credential Manager'' by clicking ''Close''.
 
* The newly created credentials are selected in the corresponding drop-down list by default.
 
* The newly created credentials are selected in the corresponding drop-down list by default.
=== Publishing the Credentials in Azure AD ===
+
 
 +
=== Publishing Credentials in Azure AD ===
 
For Azure AD to validate the identity of MailStore Server, the created certificate needs to be published in Azure AD.
 
For Azure AD to validate the identity of MailStore Server, the created certificate needs to be published in Azure AD.
 
* Switch to the Azure AD app overview page in your web browser.
 
* Switch to the Azure AD app overview page in your web browser.
Line 39: Line 42:
 
* Click on ''Upload certificate'' in the ''Certificates'' section. Select the certificate file that you have saved previously and upload it to Azure AD by clicking ''Add''.
 
* Click on ''Upload certificate'' in the ''Certificates'' section. Select the certificate file that you have saved previously and upload it to Azure AD by clicking ''Add''.
 
* If uploading has been successful, the certificate's thumbprint as well as its start and expiry dates appear in the certificates list. You can compare the thumbprint and expiry date with those listed in the MailStore Credential Manager to check that you've uploaded the correct certificate.
 
* If uploading has been successful, the certificate's thumbprint as well as its start and expiry dates appear in the certificates list. You can compare the thumbprint and expiry date with those listed in the MailStore Credential Manager to check that you've uploaded the correct certificate.
 +
 +
=== Configuring App Authentication in Azure AD ===
 +
For Azure AD to return the result of a user's authentication request to MailStore Server, the endpoint where MailStore Server expects authentication responses, the so-called ''Redirect URI'', has to be conveyed to Azure AD.
 +
* In the Azure Portal in the web browser, select ''Authentication'' in the ''Manage'' section of the left navigation menu.
 +
* Select ''Add a platform'' in the ''Platform configurations'' section of the ''Authentication'' page.
 +
* Select ''Web'' in the ''Web applications'' section of the ''Configure platforms'' menu.
 +
* In the field ''Redirect URI'', enter a URI in the format (without brackets)
 +
*: <code>https://<fqdn>[:<port>]/oidc/signin</code>
 +
*; with the following components<nowiki>:</nowiki>
 +
*: '''https://'''<br/> Specifying the <code>https://</code> protocol is obligatory. To avoid certificate warnings during user logon, the web browsers on the client machines must trust the [[MailStore_Server_Service_Configuration#Certificate|certificate used by MailStore Server]].
 +
*: '''FQDN'''<br/>The Fully Qualified Domain Name (FQDN) of your MailStore Server that consists of the machine name and the DNS domain, e.g. <code>mailstore.example.com</code>. This name must be resolvable by all clients from which users shall be able to log on to MailStore Server.
 +
*: '''Port'''<br/>The TCP port of the MailStore Web Access (<code>8462</code> by default). This value must be equal to the port configured in the section ''Base Configuration > Network Settings > MailStore Web Access / Outlook Add-in (HTTPS)'' of the [[MailStore_Server_Service_Configuration#Services|MailStore Server Service Configuration]]. The TCP port has to be specified only if it is different from the default port of the HTTPS protocol (<code>443</code>).
 +
*: '''/oidc/signin'''<br/>The endpoint where MailStore Server expects the authentication responses of Azure AD. This path has to be specified exactly as stated here at the end of the redirect URI.
 +
::{| class="wikitable"
 +
|+ Examples for valid redirect URIs
 +
|-
 +
! style="width:90px;" | Machine Name
 +
! style="width:90px;" | DNS Domain
 +
! style="width:60px;" | TCP Port
 +
! Resulting Redirect URI
 +
|-
 +
| align="center"| mailstore
 +
| align="center"| example.com
 +
| 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 Access default  port
 +
|-
 +
| align="center"| mailstore
 +
| align="center"| example.com
 +
| align="center"| 443
 +
| <code><nowiki>https://mailstore.example.com/oidc/signin</nowiki></code><br/><br/>The port can be ommited if the HTTPS default port 443 has been configured for MailStore Web Access or as source port of a port-forwarding on the firewall or router.
 +
|-
 +
|}
 +
:: <p class="msnote">'''Important Notice:''' Please note that the redirect URI is case-sensitive. Also review the requirements on resolving URIs in the [[#Prerequisites, Recommendations and Limitations|Prerequisites, Recommendations and Limitations]] section.</p>
 +
* Leave the field ''Logout URL'' blank.
 +
* Enable the ''ID tokens'' option in the ''Implicit grant'' section.
 +
* Click on ''Configure'' to finish the configuration of the app authentication in Azure AD.

Revision as of 09:53, 16 June 2020

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

During synchronization, user information, such as user names and email addresses, is copied from the Microsoft 365 tenant into MailStore Server's user database. That way, users can use their Microsoft 365 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 Microsoft 365 tenant itself by MailStore Server. The scope of the synchronization can be limited through filters.


Prerequisites, Recommendations and Limitations

  • For best user experience, the certificate used by MailStore Server should be trusted by all clients 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 log in 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 Microsoft 365 to authenticate users at login, accessing the archive via IMAP is not possible for technical reasons.

Connecting MailStore Server and Microsoft 365

In order to synchronize user information from Microsoft 365, MailStore Server has to be connected to your Microsoft 365 tenant and been granted the required permissions. Microsoft 365 relies on Azure Active Directory as directory service. Each Microsoft 365 tenant corresponds to an Azure AD tenant that stores its user information.

Registering of MailStore Server as App in Azure AD

Through registration, MailStore Server gets an identity in Azure AD that makes it possible to authenticate to the tenant's services and use their resources.

  • Sign in to the Azure Portal as a Global Administrator for your Microsoft 365 tenant.
  • In the navigation menu (☰), select the option Azure Active Directory.
  • On the next page, select App registrations in the Manage section of the left navigation menu.
  • Select New Registration. The Register an application page appears.
  • In the Name field, enter a meaningful display name, e.g. MailStore Server. This name will be shown to users on logon later on, for example.
  • Leave all other settings on this page to their defaults.
  • Click on Register. If the registration has been successful, you are shown the overview page of the newly registered app.

The Application (client) ID shown on this page identifies MailStore Server in your Azure AD tenant and has to be copied into MailStore Server next, together with the Directory (tenant) ID. Therefore, for the following steps, leave the overview page open in your web browser.

Creating Credentials in MailStore Server

Credentials for Microsoft 365 consist of the aforementioned IDs and a secret that MailStore Server uses to proof its identity to Azure AD. Microsoft recommends using certificates as secrets to identify apps in Azure AD. When creating credentials, such a certificate is generated automatically by MailStore Server but can also be recreated later on.

  • 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 Microsoft 365 (Modern Authentication).
Placeholder.png
  • In the Connection section, click on the button (…) next to the Credentials drop-down list.
  • In the Credential Manager that appears, click on Create…
  • In the Azure AD App Credentials dialog, enter the following information in the Settings section:
    • Name
      A meaningful display name for the credentials, e.g. the name of your Microsoft 365 tenant.
    • Application (client) ID
      The value of the corresponding field that you can copy from the Azure AD app overview page in your web browser.
    • Directory (tenant) ID
      The value of the corresponding field that you can copy from the Azure AD app overview page in your web browser.
Placeholder.png
  • In the Authentication section, click on the drop-down button next to the Certificate text box und select Download Certificate. Save the certificate on your hard drive.
  • Confirm your entries by clicking OK.
  • The newly created credentials are listed in the Credential Manager under the name you have entered with the type Microsoft 365. Here you can also edit or delete existing credentials if necessary.
  • Leave the Credential Manager by clicking Close.
  • The newly created credentials are selected in the corresponding drop-down list by default.

Publishing Credentials in Azure AD

For Azure AD to validate the identity of MailStore Server, the created certificate needs to be published in Azure AD.

  • Switch to the Azure AD app overview page in your web browser.
  • Select Certificates & secrets in the Manage section of the left navigation menu.
  • Click on Upload certificate in the Certificates section. Select the certificate file that you have saved previously and upload it to Azure AD by clicking Add.
  • If uploading has been successful, the certificate's thumbprint as well as its start and expiry dates appear in the certificates list. You can compare the thumbprint and expiry date with those listed in the MailStore Credential Manager to check that you've uploaded the correct certificate.

Configuring App Authentication in Azure AD

For Azure AD to return the result of a user's authentication request to MailStore Server, the endpoint where MailStore Server expects authentication responses, the so-called Redirect URI, has to be conveyed to Azure AD.

  • In the Azure Portal in the web browser, select Authentication in the Manage section of the left navigation menu.
  • Select Add a platform in the Platform configurations section of the Authentication page.
  • Select Web in the Web applications section of the Configure platforms menu.
  • In the field Redirect URI, enter a URI in the format (without brackets)
    https://<fqdn>[:<port>]/oidc/signin
    with the following components:
    https://
    Specifying the https:// protocol is obligatory. To avoid certificate warnings during user logon, the web browsers on the client machines must trust the certificate used by MailStore Server.
    FQDN
    The Fully Qualified Domain Name (FQDN) of your MailStore Server that consists of the machine name and the DNS domain, e.g. mailstore.example.com. This name must be resolvable by all clients from which users shall be able to log on to MailStore Server.
    Port
    The TCP port of the MailStore Web Access (8462 by default). This value must be equal to the port configured in the section Base Configuration > Network Settings > MailStore Web Access / Outlook Add-in (HTTPS) of the MailStore Server Service Configuration. The TCP port has to be specified only if it is different from the default port of the HTTPS protocol (443).
    /oidc/signin
    The endpoint where MailStore Server expects the authentication responses of Azure AD. This path has to be specified exactly as stated here at the end of the redirect URI.
Examples for valid redirect URIs
Machine Name DNS Domain TCP Port Resulting Redirect URI
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 example.com 443 https://mailstore.example.com/oidc/signin

The port can be ommited if the HTTPS default port 443 has been configured for MailStore Web Access or as source port of a port-forwarding on the firewall or router.

Important Notice: Please note that the redirect URI is case-sensitive. Also review the requirements on resolving URIs in the Prerequisites, Recommendations and Limitations section.

  • Leave the field Logout URL blank.
  • Enable the ID tokens option in the Implicit grant section.
  • Click on Configure to finish the configuration of the app authentication in Azure AD.