Implementing an Autodiscover Client in Microsoft Exchange

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.

1. 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.

2. 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.

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.

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.

5. 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.

6. 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.

  

  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