Setup Active Directory Federation Services

MailStore Server can be configured to authenticate against Active Directory Federation Services (AD FS) when using the Active Directory or LDAP Generic directory service connectors.

Prerequisites, Recommendations and Limitations

• This guide assumes that you already have AD FS installed and configured and only describes the parts specific to MailStore Server.
• 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 AD FS to authenticate users at login, accessing the archive via IMAP is not possible for technical reasons.

Creating an AD FS Application Group

To allow MailStore Server to request OpenID Connect (OIDC) tokens from AD FS, you have to create an Application Group in AD FS. This Application Group has to be referenced in MailStore Server to establish a trust relationship between those two systems.

• Login to your AD FS server system.
• Open the AD FS management console.
• Navigate to Application Groups.
• Right click on Application Groups and select Add Application Group... or click Add Application Group... in the Actions pane.
• Enter a Name, e.g. MailStore, and select the template Native application acessing a web API.

• Click Next.
• The Client Identifier of this application group is shown. Note this value since it is required later for configuring MailStore Server.
• 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 AD FS. This path has to be specified exactly as stated here at the end of the redirect URI.

Examples for valid redirect URIs

Product	Machine Name	DNS Domain	TCP 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 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.
MailStore SPE	archive	example.com	443	https://archive.example.com/<instanceid>/oidc/signin The instanceid of the instance is part of the Redirect URI.

• Copy the Redirect URI into the clipboard and note this value, too, since it is also required later for configuring MailStore Server.
• Click Add to add the Redirect URI to the list of allowed URIs.
• Click Next to continue.

• Paste the Redirect URI into the Identifier field of the Web API configuration.
• Click Add.
• Click Next to continue.

• Choose an Access Control Policy for this Application Group.
• Click Next to continue.

• Select the scopes allatclaims, openid and profile.
• Click Next to continue.

• A summary of the configuration is shown.
• Click next to create the Application Group.

• A success message is shown.

• Close the dialog.

If the User Principal Name (UPN) or its local part should be used as user name in MailStore Server, configuration of AD FS is now complete and you can enter the Client Identifier and the Redirect URI that you have noted before in the configuration of the Active Directory or LDAP Generic directory service connectors in MailStore Server.

If, however, the sAMAccountName should be used as user name in MailStore Server, please follow the steps in the next section.

Adding sAMAccountName as User Name

The OIDC token issued by AD FS does not include the sAMAccountName property of the users by default. If you have configured MailStore Server to use the sAMAccountName as user name, you have to configure the AD FS application group to include that property in the token. Otherwise MailStore Server is unable to associate the token with a user and users are unable to login.

• Right click on the newly created Application Group and select Properties.

• Select the Web API application and click Edit...
• Open the tab Issuance Transform Rule.

• Click Add Rule...
• Select Send LDAP Attribute as Claims from the Claim rule template drop down menu.
• Click Next to continue.

• Enter a Claim rule name.
• Select Active Directory from the Attribute store drop down menu.
• Select SAM-Account-Name in the LDAP Attribute column of the mapping table.
• Enter sAMAccountName in the Outgoing Claim Type column.
• Click Finish.

Configuration of AD FS is now complete and you can enter the Client Identifier and the Redirect URI that you have noted before in the configuration of the Active Directory or LDAP Generic directory service connectors in MailStore Server.