Autodiscover for Exchange ActiveSync developers

  • Article

In this article
Introduction
Finding and calling the Autodiscover service
Autodiscover requests and responses
When should the client perform an Autodiscover operation?
Related resources

Introduction

Autodiscovery is a process by which a Microsoft Exchange Server client can determine the URL of a particular Microsoft Exchange ActiveSync endpoint by using only a mailbox SMTP address and user credentials. During the Autodiscover process, the client uses the mailbox Simple Mail Transfer Protocol (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 it also gives the client a mechanism by which to recover from errors and respond to changes in the Microsoft Exchange environment automatically.

In this article, I describe the Autodiscover process from the perspective of an Exchange ActiveSync client developer, including the following aspects of autodiscovery:

  • 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 the Autodiscover service

Note

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

  • Full implementation of the Autodiscover algorithm

  • The use of the Autodiscover service 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 by 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 asking only for the email address and password in step 1. If the user account is not provisioned for a user principal name (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 then 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 then 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 http://autodiscover.woodgrovebank.com/autodiscover/autodiscover.xml. (Note that this is a non-Secure Sockets Layer (SSL) endpoint).The client then 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 "Redirect responses" section. The client then does one of the following:

      • If the redirection URL is valid, the client tries the URL and then 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 Domain Name System (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 actions then 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 "Redirect Response" section. The client then does one of the following:

      • If the redirection URL is valid, the client tries the URL and then does one of the following:

        • 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 sequence occurs:

    • If the server responds with an HTTP 302 redirect, the client validates the redirection URL according to the process defined in the "Redirect responses" and then does one of the following:

      • If the redirection URL is valid, the client tries the URL and then does one of the following:

        • If the attempt succeeds, the client repeats 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", the client gets the redirection email address from the Redirect element and then 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: http:// servername/Microsoft-Server-ActiveSync. The client should try to use this URL for future requests.

Tip

The client can perform steps 1 through 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 the Autodiscover service, 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, as shown in the following example. 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 FoundLocation: 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 "Finding and calling the Autodiscover service" section 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 but 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 of them.

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. In this event, the client can choose to present the user an opportunity to enter credentials again.

Error responses from the Autodiscover service 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 was a server error, 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.

<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 an Autodiscover operation?

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

Tip

Although 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 every 24 hours. Performing autodiscovery at regular intervals ensures that the client is using the most efficient Microsoft Exchange URL for a particular mailbox.

Autodiscovery 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, time-outs, or any response that indicates a DNS lookup failure, it should run the Autodiscover process to see whether 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.5.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 autodiscovery to get the new URL; instead, 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 autodiscovery to get a new Exchange ActiveSync URL. The following example shows a 451 error response.

HTTP/1.1 451Date: Tue, 08 Dec 2009 19:43:24 GMTServer: Microsoft-IIS/7.0X-Powered-By: ASP.NETX-AspNet-Version: 2.0.50727X-MS-Location: https://mail.woodgrovebank .com/Microsoft-Server-ActiveSyncCache-Control: privateContent-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 autodiscovery 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 autodiscovery, determine whether the URL that is retrieved is different from the URL that was cached before the error, try the new URL if it is different, and then — if the new URL works — replace the cached URL with the new one. This ensures that the client maintains a URL to retry in the event that autodiscovery 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