Autodiscover for Exchange ActiveSync developers

  • Article

This post is part of an ongoing series that covers Microsoft Exchange ActiveSync for developers.

Autodiscover is a process by which a Microsoft Exchange Server client can determine the URL of the Microsoft Exchange ActiveSync endpoint by using only a mailbox SMTP address and user credentials. During the Autodiscover process, the client uses the mailbox SMTP address to determine the Autodiscover service endpoint URL and sends a request to the Autodiscover service that includes the mailbox SMTP address. A successful call to the Autodiscover service results in a response that contains the Exchange ActiveSync endpoint URL that the client will use to access the mailbox. This not only simplifies initial client configuration for the end user, but also gives the client a mechanism by which to recover from errors and respond to changes in the Microsoft Exchange environment automatically.

In this blog post, I describe the Autodiscover process from the perspective of an Exchange ActiveSync client developer, including the following:

  • The process of finding and calling the Autodiscover service.
  • The specific requests and responses that are used during the Autodiscover process.
  • When clients should call Autodiscover. 

 

Note

The following information, covered in this blog post, is important for the Exchange ActiveSync Logo Program:

· Full implementation of the Autodiscover algorithm

· The use of Autodiscover to recover from transient connection errors

· The handling of the X-MS-Location header in 451 redirect responses

· The handling of 302 redirect responses

 

For more information about the logo program, see Exchange ActiveSync Logo Program on Microsoft TechNet.

 

Finding and calling the Autodiscover service

A client needs only an email address and user credentials to successfully find and call the Autodiscover service. The client should parse the email address to get the domain information, which is everything to the right of the “@” character.

In the following procedure, woodgrovebank.com is the domain from the email address chris@woodgrovebank.com. If the domain information includes a subdomain, such as sales.woodgrovebank.com, the client should use the sales.woodgrovebank.com subdomain first and then, if the procedure fails, try again using the domain woodgrovebank.com. The client uses this domain to construct the Autodiscover service endpoint URLs.

The following procedure describes the Autodiscover process for Exchange ActiveSync clients.

Tip

A client can minimize the user input needed by only asking for the email address and password in step 1. If the user account is not provisioned for a UPN logon, more input may be required. In this case, a 401 error response will be returned, and the client should collect the domain and user name from the user and resubmit the request.

1. The client sends an Autodiscover request to https://woodgrovebank.com/autodiscover/autodiscover.xml and does one of the following:

  • If the Autodiscover attempt succeeds, the client proceeds to step 5.
  • If the Autodiscover attempt fails, the client proceeds to step 2.

2. The client sends an Autodiscover request to https://autodiscover.woodgrovebank.com/autodiscover/autodiscover.xml, and does one of the following:

  • If the Autodiscover attempt succeeds, the client proceeds to step 5.
  • If the Autodiscover attempt fails, the client proceeds to step 3.

3. The client sends an unauthenticated GET method request to https://autodiscover.woodgrovebank.com/autodiscover/autodiscover.xml. (Note that this is a non-SSL endpoint).The client does one of the following:

  • 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 “Redirect responses”. The client then does one of the following:
    • If the redirection URL is valid, the client tries the URL, and does one of the following:
      • If the attempt succeeds, the client proceeds to step 5.
      • If the attempt fails, the client proceeds to step 4.
    • If the redirection URL is not valid, the client proceeds to step 4.
  • If the GET request does not return a 302 redirect response, the client proceeds to step 4.

4. The client performs a DNS query for an SRV record for _autodiscover._tcp.woodgrovebank.com. The query might return multiple records. The client selects only records that point to an SSL endpoint and that have the highest priority and weight. One of the following occurs:

  • If no such records are returned, the client proceeds to step 6.
  • If records are returned, 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 “Redirect Response”. The client then does one of the following:
    • If the redirection URL is valid, it tries the URL, and one of the following occurs:
      • If the attempt succeeds, the client proceeds to step 5.
      • If the attempt fails, the client proceeds to step 6.
    • If the redirection URL is not valid, the client proceeds to step 6.

5. When a valid Autodiscover request succeeds, the following takes place:

  • If the server responds with an HTTP 302 redirect, the client validates the redirection URL according to the process defined in the section “Redirect responses”, and does one of the following:
    • If the redirection URL is valid, the client tries the URL, and does one of the following:
      • If the attempt succeeds, the client resumes step 5 from the beginning.
      • If the attempt fails, the client proceeds to step 6.
    • If the redirection URL is not valid, the client proceeds to step 6.
  • If the server responds with a valid Autodiscover response, the client does one of the following:
    • If the value of the Action element is "Redirect", it gets the redirection email address from the Redirect element, and returns to step 1 using this new email address.
    • If the value of the Action element is "Settings", the client has successfully received the requested configuration settings for the specified user. The client does not need to proceed to step 6.

6. If the client cannot contact the Autodiscover service, the client should ask the user for the Exchange server name and use it to construct an Exchange ActiveSync URL, similar to the following: https://servername/Microsoft-Server-ActiveSync. The client should try to use this URL for future requests.

Tip

The client can perform steps 1-4 in any order or in parallel to expedite the process, but it must wait for responses to finish at each step before proceeding. Given that many organizations prefer to use the URL in step 2 to set up Autodiscover, the client might try this step first.

 

 

 

Autodiscover requests and responses

The preceding procedure mentions Autodiscover requests and responses. Microsoft Exchange publishes a "plain old XML" (POX) endpoint for the Autodiscover service. (For more information, see Autodiscover Reference (POX) on MSDN.) These responses can be quite large. Because Exchange ActiveSync is a mobile protocol, a more concise Autodiscover schema called "mobilesync" is defined specifically for Exchange ActiveSync clients.

The following is an example of an Exchange ActiveSync Autodiscover request.

<?xml version="1.0" encoding="utf-8"?>

<Autodiscover xmlns="https://schemas.microsoft.com/exchange/autodiscover/mobilesync/requestschema/2006">

  <Request>

   <EMailAddress>chris@woodgrovebank.com</EMailAddress>

   <AcceptableResponseSchema>

  https://schemas.microsoft.com/exchange/autodiscover/mobilesync/

   responseschema/2006

   </AcceptableResponseSchema>

  </Request>

</Autodiscover>

 

Successful response

A successful Exchange ActiveSync response contains URL settings for Exchange ActiveSync. Settings in the Exchange ActiveSync Autodiscover response can contain two server sections: one with the type “MobileSync”, which is the Exchange ActiveSync endpoint URL, and one with the type “CertEnroll”, which is used to obtain a client certificate for SSL negotiation. (For more information about this response, see [MS-ASCMD] ActiveSync Command Reference Protocol Specification section 4.2.4.)

<?xml version="1.0" encoding="utf-8"?>

<Autodiscover

xmlns:autodiscover="https://schemas.microsoft.com/exchange/autodiscover/mobilesync/responseschema/2006">

    <autodiscover:Response>

        <autodiscover:Culture>en:us</autodiscover:Culture>

        <autodiscover:User>

            <autodiscover:DisplayName>Chris Gray</autodiscover:DisplayName>

            <autodiscover:EMailAddress>chris@woodgrovebank.com</autodiscover:EMailAddress>

        </autodiscover:User>

        <autodiscover:Action>

            <autodiscover:Settings>

                <autodiscover:Server>

                    <autodiscover:Type>MobileSync</autodiscover:Type>

                    <autodiscover:Url>

                        https://loandept.woodgrovebank.com/Microsoft-Server-ActiveSync

                    </autodiscover:Url>

                    <autodiscover:Name>

                 https://loandept.woodgrovebank.com/Microsoft-Server-ActiveSync

             </autodiscover:Name>

                </autodiscover:Server>

                <autodiscover:Server>

                    <autodiscover:Type>CertEnroll</autodiscover:Type>

                    <autodiscover:Url>https://cert.woodgrovebank.com/CertEnroll</autodiscover:Url>

                    <autodiscover:Name />

                   <autodiscover:ServerData>CertEnrollTemplate</autodiscover:ServerData>

                </autodiscover:Server>

            </autodiscover:Settings>

        </autodiscover:Action>

    </autodiscover:Response>

</Autodiscover>

Redirect responses

Redirection to a different URL can be in the form of an HTTP 302 response. In the following example, an Autodiscover request is being redirected to a different URL. The client should try to send an Autodiscover request to the URL in the response. If the request sent to the redirect location fails, the client should stop and inform the user that Autodiscover has failed.

HTTP/1.1 302 Found

Location: https://autodiscover.us.woodgrovebank .com/autodiscover/autodiscover.xml

Important

The client should always validate the URL received in the redirect response to ensure that it does not redirect to non-SSL endpoints or SSL endpoints with invalid certificates.

Steps 3 and 4 in the procedure in the section "Finding and calling the Autodiscover service" describe an unauthenticated, non-SSL, GET request and a DNS lookup, respectively. Because both of these redirection mechanisms can be spoofed, it is important for the Exchange ActiveSync client to properly validate the redirection. Beyond the validation described, in this case the client should also prompt the user to validate the service provider and name on the certificate of the endpoint.

 

For more information, see Implementing an Autodiscover Client in Microsoft Exchange on MSDN.

 

 

 

Redirects can also come from within the details of an Autodiscover response, as shown in the following example. In this case, the client is being directed to start the Autodiscover process over with a new email address.

<?xml version="1.0" encoding="utf-8"?>

<Autodiscover xmlns:autodiscover="https://schemas.microsoft.com/exchange/autodiscover/mobilesync/responseschema/2006">

    <autodiscover:Response>

        <autodiscover:Culture>en:us</autodiscover:Culture>

        <autodiscover:User>

           <autodiscover:DisplayName>Chris Gray</autodiscover:DisplayName>

           <autodiscover:EMailAddress>chris@woodgrovebank.com</autodiscover:EMailAddress>

        </autodiscover:User>

        <autodiscover:Action>

           <autodiscover:Redirect>chris@loandept.woodgrovebank.com </autodiscover:Redirect>

        </autodiscover:Action>

    </autodiscover:Response>

</Autodiscover>

The client should start from step 1 in the procedure with the email address from the redirect response, chris@loandept.woodgrovebank.com.

Important

The client should look out for redirections to the same email or URL that it is already using – also known as “circular” redirections. If a circular redirection is detected, the client should not follow it and instead should move to the next step. To avoid getting into an infinite “redirection loop”, the client should also track the total number of redirections and fail after 10.

 

Error responses

Errors can come in the form of HTTP 403 or 404 error responses, or in the Error section of an Autodiscover response. The client should consider these errors permanent and move on to the next step in the Autodiscover URL location process. An HTTP 401 response indicates that authentication failed. The client can choose to present the user an opportunity to enter credentials again.

Error responses from Autodiscover can indicate a problem with the request the client sent or a problem on the server side. In the following example, there was a problem contacting the directory service on the server side. Because this error is on the server side, the client should continue on to the next step in the Autodiscover URL location process. The client can also choose to retry this request, as the error might be transient.

<?xml version="1.0" encoding="utf-8"?>

<Autodiscover xmlns:autodiscover="https://schemas.microsoft.com/exchange/autodiscover/mobilesync/responseschema/2006">

    <autodiscover:Response>

        <autodiscover:Culture>en:us</autodiscover:Culture>

        <autodiscover:User>

           <autodiscover:EMailAddress>chris@woodgrovebank.com</autodiscover:EMailAddress>

       </autodiscover:User>

       <autodiscover:Action>

           <autodiscover:Error>

               <Status>1</Status>

               <Message>The directory service could not be reached</Message>

               <DebugData>MailUser</DebugData>

           </autodiscover:Error>

       </autodiscover:Action>

    </autodiscover:Response>

</Autodiscover>

Error responses can also indicate problems with the Autodiscover request sent by the client. The following example shows an error code 600 response, which indicates an invalid request. A 601 response would indicate that the requested schema version is not supported by the server.

<?xml version="1.0" encoding="utf-8"?>

<Autodiscover

xmlns:autodiscover="https://schemas.microsoft.com/exchange/autodiscover/mobilesync/responseschema/2006">

   <autodiscover:Response>

      <autodiscover:Error Time="16:56:32.6164027" Id="1054084152">

          <autodiscover:ErrorCode>600</autodiscover:ErrorCode>

          <autodiscover:Message>Invalid Request</autodiscover:Message>

          <autodiscover:DebugData />

      </autodiscover:Error>

   </autodiscover:Response>

</Autodiscover>

When should the client perform Autodiscover?

Because Autodiscover requires only an email address and password, using Autodiscover can make the initial configuration of an email account easy for a user. After performing Autodiscover in an initial account configuration, the device should cache the Exchange ActiveSync URL that is returned in the successful response.

Tip

While the client should cache the Exchange ActiveSync URL that is retrieved through the Autodiscover process, we recommend that, regardless of any error responses, the URL be refreshed once every 24 hours. Performing Autodiscover periodically ensures that the client is using the most efficient Microsoft Exchange URL for a given mailbox.

Autodiscover is equally important after the initial configuration of the email client as a method for recovering from transient errors. If the client receives HTTP 401, 403, 404, or 500 responses, timeouts, or any response that indicates a DNS lookup failure, it should run Autodiscover to see if it gets a new URL. For more information, see [MS-ASHTTP] ActiveSync HTTP Protocol Specification section 3.1.5.2.1.

The client can also receive an HTTP 451 redirect response, as specified in [MS-ASHTTP] ActiveSync HTTP Protocol Specification section 3.1.4.2.2. This response indicates that the client sent a request to a URL that is no longer the optimum endpoint URL for the mailbox the client is trying to access. This can occur when a mailbox moves from one Active Directory site to another. For more information, see Understanding Proxying and Redirection on Microsoft TechNet. The client will continue to receive the 451 error until it sends requests to the new endpoint.

Typically, the 451 response contains an X-MS-Location header that indicates the new Exchange ActiveSync URL for the client to use. When this header is present, the client does not need to use Autodiscover to get the new URL; it can use the URL from the header. However, the X-MS-Location header is optional. If the header is not present, the client should perform Autodiscover to get a new Exchange ActiveSync URL. The following example shows a 451 error response.

HTTP/1.1 451

Date: Tue, 08 Dec 2009 19:43:24 GMT

Server: Microsoft-IIS/7.0

X-Powered-By: ASP.NET

X-AspNet-Version: 2.0.50727

X-MS-Location: https://mail.woodgrovebank .com/Microsoft-Server-ActiveSync

Cache-Control: private

Content-Length: 0

A 302 redirect response is expected and should be followed only during the Autodiscover process. If the client receives a 302 redirect in response to a command, such as FolderSync, it should not follow the redirect. Instead, the client should go through the Autodiscover process again to get a new URL.

Important

When the client performs Autodiscover to attempt to recover from a transient error condition, it should not discard the original Exchange ActiveSync URL that is stored in the cache until it confirms that the new URL works. We recommend that the client perform Autodiscover, determine whether the URL that is retrieved is different than the URL that was cached before the error, try the new URL if it is different, and if the URL works, replace the cached URL with the new URL. This ensures that the client maintains a URL to retry in the event that Autodiscover fails.

 

[MS-ASCMD]: ActiveSync Command Reference Protocol Specification

[MS-ASHTTP]: ActiveSync HTTP Protocol Specification

Understanding Proxying and Redirection

Understanding the Autodiscover Service

Understanding Exchange ActiveSync Autodiscover

Autodiscover and Exchange 2007

 

Post written by: Matt Stehle, Microsoft Corporation