Autodiscover for Exchange ActiveSync developers
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 redirection URL is valid, the client tries the URL, and does one of the following:
- 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.
- If the redirection URL is valid, it tries the URL, and one of the following occurs:
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 redirection URL is valid, the client tries the URL, and does one of the following:
- 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. |
Related Resources
[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
Comments
Anonymous
July 13, 2011
Sweet - this is a more digestible format than the MS-ASxxx specs in the MSDN Library. (They get the job done, but are in a more reference style format rather than a tutorial style.) I've been considering adding EAS Autodiscover testing/verification to a diagnostic utility I've made (available from my blog for those who are interested) and this might be what I need to finally get around implementing it. You say this is part of an ongoing series - is there an overview of what's in store for us in this series?Anonymous
July 15, 2011
Hello Andreas. I am glad to hear that you find these helpful. Regarding our article series, we are working on articles describing best practices on calendaring: meeting requests, responses, recurrence, delegation; as well as other areas of Exchange ActiveSync such as provisioning, remote wipe, and others. Are there any particular areas that you would like us to write about?Anonymous
July 17, 2011
Calendars are a tricky thing indeed so I can picture that being a good candidate for a walkthrough. Some of the challenges with calendars aren't necessarily an Exchange challenge though, as there's different ways to hook into the calendar of different mobile operating systems, (which would be one of the primary motivations for implementing EAS in the first place I suppose). Not expecting you to cover that side of it of course. Personally I feel I've got the provisioning and remote wipe under control. (Let me know if you need a contribution on those articles - I've covered parts of it already in blog posts.) But I have gotten the impression that people are unsure as to how this actually works. A lot of third-party EAS clients are downright lousy at doing policy provisioning (could be a deliberate choice for all I know). I would like to see covering wbxml on a more general level as well. Your samples are plain xml, which is readable and mostly understandable, but that's not the actual bytes sent to the Exchange server. I've certainly done a couple of errors in the conversion, and don't think I'm the only one :) The FolderSync command, while not necessarily cryptic by itself, is a natural place to start out when you're trying to learn EAS so maybe that's a good candidate for "a primer of MS-ASCMD operations" and building something basic? Anyway, that's just two cents from me, I'll probably read your articles if they cover any other parts of EAS as well :)Anonymous
August 01, 2011
Quick question for anyone that knows. I have an interesting autodiscover issue (or at least I think it is): Our SMTP domain: company.com our internal domain: myorg.local our username's to log into pc's are first initialLastname so for John Smith, it would be: myorgJSmith John's email address is: John.Smith@company.com when we run a test for autodiscover, the autodiscover test says John's 'Login Name' is: John.Smith Which is the wrong username. Where/how do we fix this? I have searched everywhere and have not seen any documentation on this. THx.Anonymous
August 01, 2011
It would probably be better suited for a question over at the TechNet forums, but I'll try to provide two cents since it is related to Autodiscover. Autodiscover as implemented in Outlook, (if you code your own Autodiscover you get to decide), attempts to do the lookup with the email address and provided password since this would require the least amount of input from the user. As described above building the urls for lookup is easy enough, but since you have a mismatch between the full account name, and the email address you'll get a 401 unauthorized in your logs. You can change this in AD on the user object. On the tab "Account" you can change @domain.local to @domain.com instead. (Domain.com needs to be added as a valid domain using "Active Directory Domains and Trusts" to show up.) Now it should be able to authenticate properly without you having to type in the domainuser instead. It will still say the user name is john.smith though. Hope that makes sense and answers your question :)Anonymous
August 18, 2011
I've started a coding tutorial on Exchange ActiveSync, along with working C# code. This post was an inspiration and helped providing background for the first post: mobilitydojo.net/.../exchange-activesync-building-blocks-autodiscoverAnonymous
January 22, 2012
MSG to EML Convertor tool spicily developed with make conversion in between Outlook MSG file convert into Outlook Express (.eml) file. It converts complete data of MSG file. This tool accept all the version of Outlook like outlook 2010(32 bit), 2007, 2003, 98, 97 etc. and mandatory of versioning problem. For more info:- www.msgtoemlconversion.in