Outlook Sync Proxy setup (for SSO functionality)

This document aims to shed some light on the new feature of Outlook Sync, which supports SSO and how to configure Outlook sync and Outlook itself. Unfortunately, Outlook does not support GSSAPI protocol natively; therefore, some changes were made to Outlook sync, and thus some settings need to be reconfigured (especially after implementing SSO after previously using Outlook sync in a regular manner) - and that's what this document is aimed at - explaining all the different settings. When using SSO from the very beginning, it's recommended to start the installation with the parameter "-sso" from the command line and that sets up the profile for SSO without an issue.

This document assumes that you have already created relevant keytabs for SSO on your domain controller for all related services (SMTP and IMAP protocols in this case), SSO and GSSAPI protocol is enabled on Icewarp server. If you haven't, please follow this document: Configuring SSO for Icewarp server

The scope of this document is focused purely on SSO setup rather than explaining all the settings of Outlook sync. For all such information, please see this document: Outlook sync guide

In order for Outlook Sync to work without an Exchange server it does one important thing - it creates a local proxy which imitates POP3 of Exchange which sends response to Outlook stating, that there are no new emails - this is key for Outlook to work without Exchange server (also, that is the reason why, when using Outlook sync, the profile created uses PST rather than OST - it's, in fact, a POP3 account, and it is the correct setting, IMAP account is not supported with Outlook sync - you can still add more IMAP accounts to Outlook via Outlook's account settings, but only one POP3 account is allowed with Outlook sync and its profile manager). We expanded the existing proxy in such manner that other mail protocols can be proxied via Outlook sync as well and thus enabling the Single Sign-on.

Note that there are two layers of settings that need to be configured - first is how Outlook sync connects to Icewarp server and the second is how Outlook connects to Outlook sync (as stated previously, Outlook sync behaves like a proxy in SSO mode).

Let's have a look at the main window of Outlook Sync.

Fig. 1

Let's skip the Login part for now and let's focus on the Connection section. This section states how Outlook sync connects to Icewarp server, so this is where you set up the information about what is the hostname of Icewarp (internal or external DNS A record) and what ports should be used for the connection to SMTP and IMAP (this is usually based on the settings of the company's firewall, so not all protocol's ports might be available). The best practice is to set up SSL or TLS encryption rather than unsecured connection - unless Outlook is used only from local area network without any access from the internet - but using encrypted connection is generally a good idea to avoid sending passwords over the network in plain text.

The next step is to check if the proxy is running. This can be found on the second tab of Outlook sync settings - Advanced. The only thing we are interested in this tab is the "Local Server" section. For Outlook sync to function in SSO mode, it is necessary to have the proxy running, therefore if it's disabled, enabled it by pressing "Start".

Fig. 2

Note that the ports can be adjusted to random port numbers (maximum of 5 digits are supported in these fields - please note that maximum port number possible is limited to 65535). Outlook sync should be able to detect any available ports for the proxy communication so it shouldn't be necessary to tamper with the pre-generated ports. In case you want to change them, stop the proxy, change ports and then start it again. Try to avoid using ports that are by default used by other services - 25, 465, 587, 143, 993, 80, 443 etc. Higher port numbers (5 digits) are generally a good idea to avoid binding the proxy to a port that a web browser might want to use.

Once this is set up, we can move to the next step, which is settings up Outlook's account - (e.g. how Outlook connects to Outlook sync).

Open Start > Control Panel > Mail > Show profiles and choose the corresponding profile used with Outlook sync. Open the Properties > Email Accounts and Choose Change. You should arrive at the window "Change Account" as shown in the screenshot below:

Fig. 3

As you can see, the settings of localhost - 127.0.0.1 are in place for IMAP and SMTP protocols. This is correct (and also a requirement) to be able to use SSO configuration.

It is important to remember that currently, we are adjusting settings of how Outlook communicates, not Outlook sync. For SSO to work, Outlook MUST communicate on both protocols with localhost (e.g. Outlook sync - that's why we are setting up 127.0.0.1 for both - we will need to adjust the ports as well, but we'll get to that later).

Note that Incoming mail server address MUST always be set to 127.0.0.1 whether we want to use SSO or not. In case we are not using SSO, the Incoming mail server remains at 127.0.0.1, but the Outgoing mail server (SMTP) can be set up directly to Icewarp address, but if that is the case, the "Local Server" (as shown in figure no.2) has to be stopped.

The Logon Information should be kept, as shown in the screenshot. The User Name has to be "Connector" and the password can be anything, except empty string, but there shouldn't be any need to change the User Name or Password.

Next click on "More Settings.." and switch to "Outgoing server" tab. Put the bullet point to the option "Log on using" and supply login information of your account and tick "Remember password".

Fig. 4

Next, select the "Advanced" tab.

Fig. 5

In order for SSO to work, the corresponding ports from the "Local Server" from figure 2 need to be supplied for POP3 and SMTP, and in both cases any encryption needs to be disabled - do not mistake this with Outlook sync's encrypted connection towards Icewarp - we are now configuring ports for localhost, and by encrypting the communication between Outlook and Outlook Sync the communication would not get through. Save the setting by pressing OK.

Now untick the box to automatically test account settings and press "Next" to save all the settings (the reason is that the settings, while invalid for now, would not be kept due to the test not going through).

Press OK or Close on all the Windows opened, return to Outlook Sync and switch the "Authentication type" to "Single Sign-on".

Fig. 6

Once you supply your domain credentials, the SSO should be working fine.