Setup Active Directory Federation Services - Revision history

Ltalaschus at 14:04, 24 May 2022

2022-05-24T14:04:24Z

Bmeyn at 14:16, 26 April 2021

2021-04-26T14:16:57Z

Bmeyn at 16:20, 23 April 2021

2021-04-23T16:20:44Z

Ltalaschus at 16:26, 22 April 2021

2021-04-22T16:26:21Z

Ltalaschus at 15:43, 22 April 2021

2021-04-22T15:43:25Z

Ltalaschus at 15:16, 22 April 2021

2021-04-22T15:16:19Z

Ltalaschus: Created page with "MailStore Server can be configured to authenticate against Active Directory Federation Services (AD FS) when using the Active Directory or G..."

2021-04-22T09:45:30Z

Created page with "MailStore Server can be configured to authenticate against Active Directory Federation Services (AD FS) when using the Active Directory or G..."

New page

MailStore Server can be configured to authenticate against Active Directory Federation Services (AD FS) when using the [[Active Directory Integration|Active Directory]] or [[Generic LDAP Integration|LDAP Generic]] directory service connectors. This guide assumes that you already have AD FS installed and configured and only describes the parts specific to MailStore Server.

To allow MailStore Server to request OIDC tokens from AD FS, you have to create an ''Application Group'' in AD FS. This ''Application Groups'' has to be referenced in MailStore Server to establish a trust erlationship 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''.
[[File:Adfs_setup_01.png|center|550px]]
* Click ''Next''.
* The ''Client Identifier'' of this application group is shown. Copy its value, since it is required later in MailStore Server.
* 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://''' 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''' 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''' 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''' 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:80px;" | Product
! style="width:80px;" | Machine Name
! style="width:90px;" | DNS Domain
! style="width:40px;" | TCP Port
! Resulting Redirect URI
|-
| align="center"| MailStore Server
| align="center"| mailstore
| align="center"| example.com
| align="center"| 8462
| <code><nowiki>https://mailstore.example.com:8462/oidc/signin</nowiki></code> Redirect URI with Fully Qualified Domain Name and MailStore Web Access default port
|-
| align="center"| MailStore Server
| align="center"| mailstore
| align="center"| example.com
| align="center"| 443
| <code><nowiki>https://mailstore.example.com/oidc/signin</nowiki></code> 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.
|-
| align="center"| MailStore SPE
| align="center"| archive
| align="center"| example.com
| align="center"| 443
| <code><nowiki>https://archive.example.com/<instanceid>/oidc/signin</nowiki></code> The ''instanceid'' of the instance is part of the Redirect URI.
|-
|}
[[File:Adfs_setup_02.png|center|550px]]
* Copy the ''Redirect URI'' into the clipboard.
* Click ''Add'' to add the ''Redirect URI'' to the list of allowed URIs.
* Click ''Next'' to continue.
[[File:Adfs_setup_03.png|center|550px]]
* Paste the ''Redirect URI'' into the ''Identifier'' field of the ''Web API'' configuration.
* Click ''Add''.
* Click ''Next'' to continue.
[[File:Adfs_setup_04.png|center|550px]]
* Choose an ''Access Control Policy'' for this ''Application Group''.
* Click ''Next'' to continue.
[[File:Adfs_setup_05.png|center|550px]]
* Select the scopes ''allatclaims'', ''openid'' and ''profile''.
* Click ''Next'' to continue.
[[File:Adfs_setup_06.png|center|550px]]
* A summary of the configuration is shown.
* Click next to create the ''Application Group''.
[[File:Adfs_setup_08.png|center|550px]]
* A success message is shown.
[[File:Adfs_setup_08b.png|center|550px]]
* Close the dialog.

=== Optional: 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 user name, then 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 the users are unable to login.

If you have configured MailStore Server to use the user principal name (UPN) or the local part of the user principal name, then these configuration steps are not required.

* Right click on the newly created ''Application Group'' and select ''Properties''.
[[File:Adfs_setup_09.png|center|550px]]
* Select the ''Web API'' application and click ''Edit...''.
* Open the tab ''Issuance Transform Rule''.
[[File:Adfs_setup_10.png|center|550px]]
* Click ''Add Rule...''.
* Select ''Send LDAP Attribute as Claims'' from the ''Claim rule template'' drop down menu.
* Click ''Next'' to continue.
[[File:Adfs_setup_11.png|center|550px]]
* Enter a ''Claim rule name''.
* Select ''Active Directory'' from the ''Attribute store'' drop down menu.
* Select ''SAM-Account-Name'' in the ''LDAP Atrribute'' column of the mapping table.
* Enter ''sAMAccountName'' in the ''Outgoing Claim Type'' column.
* Click ''Finish''.
[[File:Adfs_setup_12.png|center|550px]]
* Have the ''Client Identifier'' and the ''Redirect URI'' available and return to MailStore Server to proceed with the configuration of the [[Active Directory Integration|Active Directory]] or [[Generic LDAP Integration|LDAP Generic]] directory service connectors.
<noinclude>
[[de:Vorlage:Einrichtung_von_Active_Directory_Federation_Services]]
[[en:Template:Setup_Active_Directory_Federation_Services]]
</noinclude>

@@ Line 25: / Line 25: @@
 *: '''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 AD&nbsp;FS. This path has to be specified exactly as stated here at the end of the redirect URI.
-::{| class="wikitable"
+{| class="wikitable" style="font-size: 81%;"
 |+ Examples for valid redirect URIs
 |-

@@ Line 17: / Line 17: @@
 *: '''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.
+*: '''/oidc/signin'''<br/>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.
 ::{| class="wikitable"
 |+ Examples for valid redirect URIs

@@ Line 17: / Line 17: @@
 [[File:Adfs_setup_01.png|center|550px]]
 * Click ''Next''.
-* The ''Client Identifier'' of this application group is shown. Copy this value since it is required later in MailStore Server.
+* 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)
 *: <code>https://<fqdn>[:<port>]/oidc/signin</code>
@@ Line 54: / Line 54: @@
 |}
 [[File:Adfs_setup_02.png|center|550px]]
-* Copy the ''Redirect URI'' into the clipboard.
+* 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.
@@ Line 75: / Line 75: @@
 * Close the dialog.
-=== Optional: sAMAccountName as user name ===
+If the ''User Principal Name (UPN)'' or its local part should be used as user name in MailStore Server, configuration of AD&nbsp;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 Integration#Authentication|Active Directory]] or [[Generic LDAP Integration#Authentication|LDAP Generic]] directory service connectors in MailStore Server.
 The OIDC token issued by AD&nbsp;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&nbsp;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''.
@@ Line 95: / Line 97: @@
 * Click ''Finish''.
 [[File:Adfs_setup_12.png|center|550px]]
-* Have the ''Client Identifier'' and the ''Redirect URI'' available and return to MailStore Server to proceed with the configuration of the [[Active Directory Integration|Active Directory]] or [[Generic LDAP Integration|LDAP Generic]] directory service connectors.
 <noinclude>
 [[de:Einrichtung_von_Active_Directory_Federation_Services]]
 [[en:Setup_Active_Directory_Federation_Services]]
 </noinclude>

@@ Line 1: / Line 1: @@
-MailStore Server can be configured to authenticate against Active Directory Federation Services (AD FS) when using the [[Active Directory Integration|Active Directory]] or [[Generic LDAP Integration|LDAP Generic]] directory service connectors. This guide assumes that you already have AD FS installed and configured and only describes the parts specific to MailStore Server.
+MailStore Server can be configured to authenticate against Active Directory Federation Services (AD&nbsp;FS) when using the [[Active Directory Integration|Active Directory]] or [[Generic LDAP Integration|LDAP Generic]] directory service connectors.
-To allow MailStore Server to request OIDC tokens from AD FS, you have to create an ''Application Group'' in AD FS. This ''Application Groups'' has to be referenced in MailStore Server to establish a trust erlationship between those two systems.
+== Prerequisites, Recommendations and Limitations ==
-* Login to your AD FS server system.
+== Creating an AD&nbsp;FS Application Group ==
-* Open the AD FS management console.
+To allow MailStore Server to request OpenID Connect (OIDC) tokens from AD&nbsp;FS, you have to create an ''Application Group'' in AD&nbsp;FS. This ''Application Group'' has to be referenced in MailStore Server to establish a trust relationship between those two systems.
 * Navigate to ''Application Groups''.
-* Right click on ''Application Groups'' and select ''Add Application Group..'' or click ''Add Application Group..'' in the '''Actions''' pane.
+* 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''.
 [[File:Adfs_setup_01.png|center|550px]]
 * Click ''Next''.
-* The ''Client Identifier'' of this application group is shown. Copy its value, since it is required later in MailStore Server.
+* The ''Client Identifier'' of this application group is shown. Copy this value since it is required later in MailStore Server.
 * In the field ''Redirect URI'', enter a URI in the format (without brackets)
 *: <code>https://<fqdn>[:<port>]/oidc/signin</code>
@@ Line 17: / Line 24: @@
 *: '''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 AD FS. This path has to be specified exactly as stated here at the end of the redirect URI.
+*: '''/oidc/signin'''<br/>The endpoint where MailStore Server expects the authentication responses of AD&nbsp;FS. This path has to be specified exactly as stated here at the end of the redirect URI.
 ::{| class="wikitable"
 |+ Examples for valid redirect URIs
@@ Line 69: / Line 76: @@
 === Optional: 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 user name, then 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 the users are unable to login.
+The OIDC token issued by AD&nbsp;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&nbsp;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.
-If you have configured MailStore Server to use the user principal name (UPN) or the local part of the user principal name, then these configuration steps are not required.
+If you have configured MailStore Server to use the ''User Principal Name (UPN)'' or its local part, these configuration steps are not required.
 * Right click on the newly created ''Application Group'' and select ''Properties''.
 [[File:Adfs_setup_09.png|center|550px]]
-* Select the ''Web API'' application and click ''Edit...''.
+* Select the ''Web API'' application and click ''Edit...''
 * Open the tab ''Issuance Transform Rule''.
 [[File:Adfs_setup_10.png|center|550px]]
-* Click ''Add Rule...''.
+* Click ''Add Rule...''
 * Select ''Send LDAP Attribute as Claims'' from the ''Claim rule template'' drop down menu.
 * Click ''Next'' to continue.

@@ Line 84: / Line 84: @@
 * Enter a ''Claim rule name''.
 * Select ''Active Directory'' from the ''Attribute store'' drop down menu.
-* Select ''SAM-Account-Name'' in the ''LDAP Atrribute'' column of the mapping table.
+* Select ''SAM-Account-Name'' in the ''LDAP Attribute'' column of the mapping table.
 * Enter ''sAMAccountName'' in the ''Outgoing Claim Type'' column.
 * Click ''Finish''.