Implementing an Autodiscover Client in Microsoft Exchange
Last modified: September 15, 2009
Applies to: Exchange Server 2010
In this article
Basic Security Considerations
Trying an Autodiscover Endpoint
Information Required to Call the Autodiscover Service
Calling Autodiscover
Redirections and When to Stop Following Them
Validating a Secure Redirection URL
Validating a Potentially Unsafe Redirection URL
Discovering the Autodiscover Endpoint via Active Directory SCP Record Lookup
By David Claux
The Exchange Autodiscover service provides a mechanism that enables you to automatically configure Microsoft Exchange Server 2007 or Microsoft Exchange Server 2010 client applications to access the Client Access server. To use the Autodiscover service, clients must perform the following actions:
Determine the URL of the Autodiscover service for a given domain (that is, discover the Autodiscover endpoint for the domain).
Post a request to the Autodiscover service and receive a response back in return.
This article defines the steps that a client application takes to determine the Autodiscover service endpoint and successfully retrieve Exchange configuration settings for a specific user.
Note
This article does not cover the following:
-
How to configure the Autodiscover service. For information about how to properly set up Autodiscover, see the Exchange 2007 Autodiscover Service on Microsoft TechNet.
-
HTTP authentication and SSL certificate validation concepts and how to perform authentication and validate certificates. For information about HTTP authentication, see W3C Security Home and Authentication in WinHTTP.
-
How to query a domain name server (DNS).
-
How to interpret or otherwise use the Exchange configuration settings that are returned by the Autodiscover service. For more information about this, see Autodiscover Reference on MSDN.
Basic Security Considerations
Discovering the Autodiscover endpoint for a given domain may involve authenticating and sending POST requests to multiple URLs. An Autodiscover client should not send credentials or post private information to an untrusted server. This means that before sending credentials and/or posting information, an Autodiscover client must make sure that the URL that it is about to contact is trustworthy. Generally, a client determines that a URL is trustworthy by validating the following:
That the endpoint is an HTTPS endpoint. Autodiscover clients should not authenticate or send data to a non-SSL endpoint.
That the certificate that is presented by the server is valid.
Trying an Autodiscover Endpoint
Throughout the rest of this article, I will refer to "trying a URL" multiple times. By "trying a URL," I mean doing the following:
Validating that the URL is an HTTPS endpoint.
Validating the certificate that is presented by the server.
Sending an authenticated POST request to the URL.
The following example shows a valid Autodiscover request.
<Autodiscover
xmlns="https://schemas.microsoft.com/exchange/autodiscover/outlook/requestschema/2006">
<Request>
<EMailAddress>user@contoso.com</EMailAddress>
<AcceptableResponseSchema>
https://schemas.microsoft.com/exchange/autodiscover/outlook/responseschema/2006a
</AcceptableResponseSchema>
</Request>
</Autodiscover>
"Trying a URL" succeeds if a valid Autodiscover response is returned, or if an HTTP 302 redirect response is returned. Otherwise, the request failed.
The following example shows a valid Autodiscover response.
<Autodiscover xmlns="https://schemas.microsoft.com/exchange/autodiscover/responseschema/2006">
<Response
xmlns="https://schemas.microsoft.com/exchange/autodiscover/outlook/responseschema/2006a">
<User>
<DisplayName>First Last</DisplayName>
<LegacyDN>/o=contoso/ou=First Administrative Group/cn=Recipients/cn=iuser885646</LegacyDN>
<DeploymentId>644560b8-a1ce-429c-8ace-23395843f701</DeploymentId>
</User>
<Account>
<AccountType>email</AccountType>
<Action>settings</Action>
<Protocol>
<Type>EXCH</Type>
<Server>MBX-SERVER.mail.internal.contoso.com</Server>
<ServerDN>(abbreviated for clarity)</ServerDN>
<ServerVersion>72008287</ServerVersion>
<MdbDN>(abbreviated for clarity)</MdbDN>
<ASUrl>https://mail.contoso.com/ews/exchange.asmx</ASUrl>
<OOFUrl>https://mail.contoso.com/ews/exchange.asmx</OOFUrl>
<UMUrl>https://mail.contoso.com/unifiedmessaging/service.asmx</UMUrl>
<OABUrl>https://mail.contoso.com/OAB/d29844a9-724e-468c-8820-0f7b345b767b/</OABUrl>
</Protocol>
<Protocol>
<Type>EXPR</Type>
<Server>Exchange.contoso.com</Server>
<ASUrl>https://mail.contoso.com/ews/exchange.asmx</ASUrl>
<OOFUrl>https://mail.contoso.com/ews/exchange.asmx</OOFUrl>
<UMUrl>https://mail.contoso.com/unifiedmessaging/service.asmx</UMUrl>
<OABUrl>https://mail.contoso.com/OAB/d29844a9-724e-468c-8820-0f7b345b767b/</OABUrl>
</Protocol>
<Protocol>
<Type>WEB</Type>
<Internal>
<OWAUrl AuthenticationMethod="Ntlm, WindowsIntegrated">
https://cas-01-server.mail.internal.contoso.com/owa
</OWAUrl>
<OWAUrl AuthenticationMethod="Ntlm, WindowsIntegrated">
https://cas-02-server.mail.internal.contoso.com/owa
</OWAUrl>
<OWAUrl AuthenticationMethod="Basic">
https://cas-04-server.mail.internal.contoso.com/owa
</OWAUrl>
<OWAUrl AuthenticationMethod="Ntlm, WindowsIntegrated">
https://cas-05-server.mail.internal.contoso.com/owa
</OWAUrl>
</Internal>
</Protocol>
</Account>
</Response>
</Autodiscover>
Information Required to Call the Autodiscover Service
To successfully call the Autodiscover service, a client application needs the following:
The e-mail address of the user for whom Exchange configuration settings are requested. This e-mail address is also used as the basis to determine the Autodiscover service endpoint.
Credentials (user name and password) to authenticate against the Autodiscover service. The credentials usually are those of the user for whom configuration information is requested.
Important
A user’s e-mail address is not necessarily also their user name. Therefore, a client application should collect both the e-mail address and the user name when it uses Autodiscover.
Calling Autodiscover
Let’s look at an example in which an application needs to retrieve configuration information for a user whose e-mail address is someone@contoso.com. The application needs to contact the Autodiscover service for the contoso.com domain. The following list describes the steps that the client application performs to determine the Autodiscover endpoint for the contoso.com domain and retrieve the configuration settings.
The application obtains a list of Autodiscover URLs by performing an Active Directory Service Connection Point (SCP) record lookup.
If the lookup succeeds for any URL, it proceeds to step 6.
If the lookup fails for all URLs, it proceeds to step 2.
Note
This step is optional, but we recommend that client applications implement it. For details about this process and the benefits of implementing SCP record lookup, see "Discovering the Autodiscover Endpoint Via Active Directory Service Connection Point Record Lookup" later in this article.
The application tries https://contoso.com/autodiscover/autodiscover.xml.
If the attempt succeeds, it proceeds to step 6.
If the attempt fails, it proceeds to step 3.
The application tries https://autodiscover.contoso.com/autodiscover/autodiscover.xml.
If the attempt succeeds, it proceeds to step 6.
If the attempt fails, it proceeds to step 4.
The application sends an unauthenticated GET request to http://autodiscover.contoso.com/autodiscover/autodiscover.xml. (Note that this is a non-SSL endpoint).
If the GET request returns a 302 redirect response, it gets the redirection URL from the Location HTTP header, and validates it as described in the section "Validating a Potentially Unsafe Redirection URL" later in this article.
If the redirection URL is valid, the application tries the URL.
If the attempt succeeds, it proceeds to step 6.
If the attempt fails, it proceeds to step 5.
If the redirection URL is not valid, it proceeds to step 5.
If the GET request does not return a 302 redirect response, it proceeds to step 5.
Note
It is not necessary to send an unauthenticated GET request to https://contoso.com/autodiscover/autodiscover.xml because such an endpoint is not defined as a deployment option for Autodiscover.
The application performs a DNS query for an SRV record for _autodiscover._tcp.contoso.com. The query might return multiple records. The application selects only records that point to an SSL endpoint and that have the highest priority and weight.
If no such records are returned, Autodiscover cannot be contacted.
Otherwise, the application randomly chooses a record in the list, and validates the endpoint that it points to by following the process described in the section "Validating a Potentially Unsafe Redirection URL" later in this article.
If the redirection URL is valid, it tries the URL.
If the attempt succeeds, it proceeds to step 6.
If the attempt fails, Autodiscover cannot be contacted.
If the redirection URL is not valid, Autodiscover cannot be contacted.
When a valid Autodiscover request succeeds, the following takes place:
If the server responds with an HTTP 302 redirect, the application validates the redirection URL according to the process defined in the section "Validating a Secure Redirection URL" later in this article.
If the redirection URL is valid, the application tries the URL.
If the attempt succeeds, the application resumes step 6 from the beginning.
If the attempt fails, Autodiscover cannot be contacted.
If the redirection URL is not valid, Autodiscover cannot be contacted.
If the server responds with a valid Autodiscover response, the application does one of the following:
If the value of the Action element is redirectAddr, it gets the redirection e-mail address from the RedirectAddr element, and returns to step 1 using this new e-mail address.
If the value of the Action element is redirectUrl, it gets the redirection URL from the RedirectUrl element, and validates it according to the process described in the section "Validating a Secure Redirection URL" later in this article.
If the URL is valid, it tries the URL.
If the attempt succeeds, it resumes step 6 from the beginning.
If the attempt fails, Autodiscover cannot be contacted.
If the URL is not valid, Autodiscover cannot be contacted.
If the value of the Action element is settings, the client has successfully received the requested configuration settings for the specified user.
Redirections and When to Stop Following Them
As described earlier in this article, contacting the Autodiscover service involves following redirections. To prevent a circular redirection, a client should never follow more than ten redirections.
Additionally, a client application should detect circular redirections to e-mail addresses and URLs. When a circular redirection is detected, the application should advance to the next step.
Validating a Secure Redirection URL
A redirection URL is considered secure if it has been retrieved from a trusted source. For example, if a client application authenticates against a given Autodiscover endpoint, sends a POST request to it, and gets an HTTP 302 redirect response, the Location of the redirection is deemed secure because the Autodiscover endpoint was trusted.
Validating a secure redirection URL therefore involves verifying the following:
That the endpoint is an HTTPS endpoint.
That the certificate that is presented by the server is valid.
Validating a Potentially Unsafe Redirection URL
As described earlier in this article, the Autodiscover discovery process might involve an unauthenticated GET request to a non-SSL endpoint, or a DNS lookup for an SRV record. Because both of these redirection mechanisms are potentially unsafe (they are DNS-based and can be spoofed), validating a redirection URL obtained via these means involves the following:
Verifying that the endpoint is an HTTPS endpoint.
Verifying that the certificate that is presented by the server is valid.
Validating the redirection via a prompt to the end user. We recommended that a client application implement this prompt by presenting information that is extracted from the server’s certificate to the end user. For example, in the following figure, "outlook.com" and "Microsoft Corporation" are extracted from the server’s certificate; if the user clicks either link, a dialog opens that shows the full details of the certificate.
.gif "Security Warning prompt")
Note
An alternative implementation of the prompt is to present the URL to the end user, as Microsoft Office Outlook does.
Discovering the Autodiscover Endpoint via Active Directory SCP Record Lookup
For applications that run on-premise (that is, from a computer that has access to the company’s Active Directory Domain Services or Active Directory directory service), SCP record lookup is a secure way to discover the Autodiscover endpoint without Autodiscover having to be accessible from the Internet. It is secure in the sense that URLs that are found in the Active Directory database can generally be trusted, for the following reasons:
The URLs were configured by a trustworthy source (the Exchange administrator).
The application has to authenticate against the Active Directory server to be able to query it.
Because URLs that are discovered via SCP lookup are trustworthy, a client application does not have to validate the certificate that is presented by the server. As long as a certificate exists, the application can send a POST request to the endpoint.
Although we generally recommend that customers buy and deploy valid certificates, the Exchange installer by default installs self-signed certificates on Autodiscover virtual directories. For this reason, performing an SCP record-based discovery of the Autodiscover endpoint is a great way to support an out-of-the-box Exchange installation that improves the end user experience by removing the need for a security prompt.
Another benefit of SCP lookup is that it helps distribute Autodiscover load. Because SCP URLs are scoped to Active Directory sites (as described in the section "Performing SCP Record Lookup" later in this article), it is possible for administrators to force Autodiscover clients to connect to servers that are dedicated to the site they are running in. Using URLs discovered via SCP lookup also reduces connection latencies and thus improves overall performance, because clients are connecting to servers that are in closer proximity to them.
Finally, any client application that wants complete feature parity with Outlook should implement SCP record lookup.
Performing SCP Record Lookup
There are two types of Autodiscover SCP records:
SCP pointers: Records that are used to support cross-forest Exchange deployments. SCP pointers are stamped with the following GUID: 67661d7F-8FC4-4fa7-BFAC-E1D7794C1F68.
SCP URLs: Records that represent Autodiscover service URLs, scoped to Active Directory sites. SCP URLs are stamped with the following GUID: 77378F46-2C66-4aa9-A6A6-3E7A48B19596.
The following are the steps that are involved in looking up SCP records in the Active Directory database:
Note
Client applications must be able to authenticate against AD DS or Active Directory in order to perform SCP record lookup.
The application determines the configuration naming context by reading the configurationNamingContext property of the Root DSE entry. For the current forest, the Root DSE entry is at LDAP://RootDSE. If this value cannot be found, it abandons SCP record lookup and proceeds to step 2 of the Autodiscover discovery process, as described in the section "Calling Autodiscover" earlier in this article.
The application searches for SCP records under the configuration entry, LDAP://<value of configurationNamingContext>. It searches by using the following filter: (&(objectClass=serviceConnectionPoint)(|(keywords=67661d7F-8FC4-4fa7-BFAC-E1D7794C1F68)(keywords=77378F46-2C66-4aa9-A6A6-3E7A48B19596))).
This returns a list of all SCP records, pointers, and URLs. If no records are returned, the application abandons SCP record lookup and proceeds to step 2 of the Autodiscover discovery process, as described in "Calling Autodiscover" earlier in this article.
The application tries to find an SCP pointer that is scoped to the domain of the user for whom configuration settings are to be retrieved. SCP pointer records may be stamped with a keyword that reads Domain=<domain>. For example, if the e-mail address of the user for whom the application is trying to get configuration settings is someone@contoso.com, it looks for an SCP pointer record with a keyword that reads Domain=contoso.com.
If such a record is found, it proceeds to step 5.
If no SCP pointer record that is scoped to the domain is found, but at least one SCP pointer record with no domain scoping (a wildcard pointer) exists, it does the following:
Tries the SCP URLs, as described in step 4.
If none of the SCP URL attempts are successful, it falls back to following any one of the wildcard SCP pointers, as described in step 5.
To try SCP URLs, the application does the following:
It determines the name of the Active Directory site to which the computer that is running the Autodiscover client belongs. Let’s call this value siteName.
Each SCP URL may be scoped to a specific Active Directory site. The application tries SCP URLs in the following order:
Priority 1 (Exact match – the URL is scoped to the same site as that of the client computer)
The SCP URL record has at least one keyword that reads Site=siteName in its keywords property.Priority 2 (Wildcard – the URL is not scoped to any particular site)
The SCP URL record does not have any keywords that start with Site=.Priority 3 (No match – the URL is scoped to a site that is not that of the client computer)
The SCP URL record contains at least one keyword that starts with Site= but none of these keywords read Site=siteName.
Note
The application tries an SCP URL as it does any other URL, as described in the section "Trying an Autodiscover Endpoint" earlier in this article.
An SCP pointer indicates that an LDAP server in another forest is to be used to look up SCP URLs. To follow an SCP pointer, the application reads the serviceBindingInformation property and restarts the SCP Record Lookup process from step 1, using <value of serviceBindingInformation>/RootDSE as the Root DSE path.