Account Autoconfiguration

Because Exchange wasn't really designed for what Connector tries to do with it, there are a lot of different configuration possibilities that Connector needs to deal with. Autoconfiguration attempts to figure all of these out automatically so that the user doesn't need to enter in any more information than is absolutely necessary.

The Initial WebDAV Connection

To start things off, the user must provide three pieces of information: an OWA URL, a username, and a password. The OWA URL is used because it encodes several important pieces of information, and the user should already know what it is (and if not, it should be easy for them to find out by asking someone).

If the provided URL doesn't start with "http://" or "https://", Connector prepends that. From the URL we get:

Whether or not to use SSL (based on whether the provided URL is http or https).
The name of the Exchange server to connect to (which may just be a front-end OWA server).
The port number to use, if non-standard
The OWA path
Possibly the user's mailbox name (if they provided a URL like http://example.com/exchange/mailbox-name rather than just http://example.com/exchange/).

Using that, Connector tries to log in to OWA and fetch the HTML data. There are various results possible:

E2K_HTTP_CANT_RESOLVE

The hostname can't be resolved. Connector will suggest that the user check for typos and try again.

E2K_HTTP_CANT_CONNECT

Can't connect to server. Connector suggests the user check that the hostname is correct, and also suggests toggling http/https, since it's possible the server may only be listening on one port.

302 Moved Temporarily

There are three possibilities, depending on the final component of the redirect URL:

`/logon.asp`	The server is actually Exchange 5.5. (Many users are quite convinced that their site uses Exchange 2000, when in fact, they are still running 5.5.)
`/owalogon.asp`	The server is using Exchange 2003 forms-based authentication. We attempt to authenticate via that, and try again.
anything else	The server is redirecting us to another URL, so we try again there. This could happen if the administrator created a redirect from an easy-to-remember URL to the actual OWA URL. Or it could mean that the user provided the wrong Exchange server name, and the server is telling us to log in on a different machine instead.

401 Unauthorized

Again, there are several possibilities:

If we were trying to use NTLM authentication, but the server didn't offer NTLM, we can try falling back to Basic auth.
Likewise, if we were trying to use Basic authentication, but the server didn't offer it, we can try NTLM.
If we tried to use Basic auth, and didn't provide an explicit domain name as part of the username, then we can suggest that the user try that.

Of course, it is also always possible that the user just typed their password wrong, so we suggest that too.

403 Forbidden

If the server requires SSL, it will sometimes be configured to return this error code on the standard HTTP port. The body of the response includes a message telling the user to use SSL, so we look for that, and try again with SSL if appropriate.

404 Not Found

If we are certain that we are talking to an Exchange server (because the response also included a "MS-WebStorage" header), then this means that the user doesn't have a mailbox on that server, and the server doesn't know where he does have a mailbox.

On the other hand, if we didn't see a "MS-WebStorage" header, it probably means this isn't an Exchange server.

Any 2xx

We parse the returned HTML and see if it looks like OWA. For Exchange 2000 or Exchange 2003, we expect to see a <FRAMESET> containing the main OWA frames. If we get back bad HTML, non-HTML, or HTML that looks like Exchange 5.5, we return an error.

Further WebDAV Probes

At this point, we should have the HTML of the OWA frame. (If we used NTLM authentication, we may also have managed to extract the NT and Windows 2000 domain names from the NTLM challenge, which may be needed later.) We extract the BASE element from the HTML, and consider that to be the canonical form of the OWA URI. Because of how OWA works, this URI will have the user's mailbox name in it, even if the URI we started with did not.

The next thing we do is find the name of the server to use to access public folders, by finding the "Public Folders" link in OWA. This is in a different location in Exchange 2000 and Exchange 2003, but hopefully we know which one we are talking at this point, from looking at the "MS-WebStorage" header. So we fetch the appropriate pane of OWA (the content pane for Exchange 2000, or the navigation bar for Exchange 2003), walk through the HTML looking for the link, and remember the URI.

Then we do a BPROPFIND on the top level of the mailbox to find the PR_STORE_ENTRYID (which can be used to find the user's "Exchange 5.5 DN", which can be used to uniquely identify the user in Active Directory later), and the time zone that the user selected in OWA. The time zone is mapped from an Exchange time zone to one of Evolution's.

The use of BPROPFIND here is also for autodetection purposes: if it fails, we return an error to the user explaining about the IIS Lockdown BPROPFIND problem.

Another possibility is that we will get an authentication error here even though we had successfully authenticated before. This can happen if we are using NTLM authentication, and the user's HTTP traffic is being intercepted by a transparent web proxy that doesn't understand NTLM (for reasons explained in the NTLM notes). So if this happens, we start over using Basic authentication instead.

The Global Catalog Server

At the moment, we can only autodetect the Global Catalog server if we are using NTLM authentication and managed to autodetect the Windows 2000 domain name before. In that case, we do a DNS query for a service (SRV) record for _gc._tcp.domain-name", which should give us the GC server name.

There are other possibilities we should try if we don't have the domain name though: in almost all cases, the Exchange server hostname will be "something.domain-name", so we could also try that.

Given a connection to the Global Catalog, we use the Exchange 5.5 DN detected earlier to find the user and look up their full name and email address, and autodetection is complete.

Autoconfiguration Hints

It is possible for a system administrator to provide hints to the autoconfig process, to make things easier on users. This is done by creating a configuration file, which presumably would be installed along with the Connector binary on each machine.

The configuration file can be stored in /etc/ximian/connector.conf, or in $PREFIX/etc/connector.conf. It consists of a series of lines such as:

1 2	OWA-URL: https://exchange.rupertcorp.com/exchange/ Disable-Plaintext: true

The available hints are:

`OWA-URL`	The default OWA URL to suggest at the beginning of autoconfiguration.
`Global-Catalog`	The Global Catalog server to use.
`NT-Domain`	The Windows NT domain name (eg, `RUPERTCORP`), to be prefixed to the username when authenticating).
`Domain`	The Windows 2000 domain name (eg, `rupertcorp.com`).
`Disable-Plaintext`	If `true`, NTLM authentication will be required. Autoconfiguration will not fall back to Basic auth, even if NTLM fails.