Evolution Connector for Microsoft Exchange Programmer’s Reference Manual |
---|
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
orhttps
).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/
rather than justmailbox-name
http://example.com/exchange/
).
Using that, Connector tries to log in to OWA and fetch the HTML data. There are various results possible:
|
The hostname can't be resolved. Connector will suggest that the user check for typos and try again. |
||||||
|
Can't connect to server. Connector suggests the
user check that the hostname is correct, and also suggests
toggling |
||||||
|
There are three possibilities, depending on the final component of the redirect URL:
|
||||||
|
Again, there are several possibilities:
Of course, it is also always possible that the user just typed their password wrong, so we suggest that too. |
||||||
|
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. |
||||||
|
If we are certain that we are talking to an
Exchange server (because the
response also included a " On the other hand, if we didn't see a
" |
||||||
Any |
We parse the returned HTML and see if it looks
like OWA. For Exchange
2000 or Exchange
2003, we expect to see a
|
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
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.
",
which should give us the GC server name.
domain-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
.
It consists of a series of lines such as:
$PREFIX
/etc/connector.conf
OWA-URL: https://exchange.rupertcorp.com/exchange/ Disable-Plaintext: true
The available hints are:
|
The default OWA URL to suggest at the beginning of autoconfiguration. |
|
The Global Catalog server to use. |
|
The Windows NT
domain name (eg, |
|
The Windows 2000
domain name (eg, |
|
If |