|
| 1 | +.\" SPDX-License-Identifier: CC-BY-SA-4.0 or-later |
| 2 | +.\" SPDX-FileCopyrightText: 2021-2024 grommunio GmbH |
| 3 | +.TH autodiscover 7 "" "Gromox" "Gromox admin reference" |
| 4 | +.SH Name |
| 5 | +autodiscover \(em AutoDiscover protocols |
| 6 | +.SH Description |
| 7 | +.PP |
| 8 | +AutoDiscover is a HTTP-based discovery protocol that helps users configure |
| 9 | +their email client settings automatically. The MS-OXDSCLI specification |
| 10 | +speaks about locating such AutoDiscover service, the MS-OXDISCO specification |
| 11 | +speaks about the XML exchange between such a service and a client. These terms |
| 12 | +are herein used to avoid ambiguity in the "AD" acronym (ActiveDirectory). |
| 13 | +.PP |
| 14 | +Autodiscover V2 is not an improved version, it is an extra layer that warrants |
| 15 | +a disgruntled remark about questionable protocol design. Locating the |
| 16 | +AutoDiscover server still happens via DNS or AD-SCP query. The V2 request |
| 17 | +contains the user identity and the name of a next-level protocol that the |
| 18 | +client seeks, e.g. "ActiveSync", "EWS" or "AutoDiscoverV1". The response is now |
| 19 | +a JSON document and generally contains just one URL, namely for the service |
| 20 | +sought. Indeed there is no way to obtain MAPI, IMAP or SMTP information in |
| 21 | +Autodiscover V2. |
| 22 | +.PP |
| 23 | +Note that Autodiscover is not used exclusively by Microsoft Outlook, |
| 24 | +Autodiscover is the main discovery protocol for any EAS-enabled device and |
| 25 | +application, such as Apple iOS, Android and other applications. |
| 26 | +.SH OXDSCLI summary |
| 27 | +Clients collect one or more AutoDiscover URLs and make HTTP POST requests to |
| 28 | +those endpoints to request server configuration. Among the methods that appear |
| 29 | +in the wild: |
| 30 | +.IP \(bu 4 |
| 31 | +Using an URL from a previous successful run. |
| 32 | +.IP \(bu 4 |
| 33 | +Performing a DNS TXT lookup on the domain name to check for the presence of a |
| 34 | +Microsoft 365 account identifier and, if found, using the URL |
| 35 | +<\fBhttps://outlook.office365.com/autodiscover/autodiscover.xml\fP>. |
| 36 | +.IP \(bu 4 |
| 37 | +When joined to an NT Domain/ActiveDirectory, performing an LDAP lookup for |
| 38 | +service connection points (SCP), i.e. objects matching |
| 39 | +"(&(objectClass=serviceConnectionPoint) |
| 40 | +(serviceClassName=ms-Exchange-AutoDiscover-Service))", and using the URLs |
| 41 | +obtained from "serviceBindingInformation" attributes. |
| 42 | +.IP \(bu 4 |
| 43 | +"Root domain" method: Constructing a string based on the user's e-mail address |
| 44 | + |
| 45 | +<\fBhttps://\fIexample.com\fP\fB/autodiscover/autodiscover.xml\fP>. |
| 46 | +.IP \(bu 4 |
| 47 | +"AutoDiscover domain" method: Constructing a string based on the user identity, |
| 48 | +<\fBhttps://autodiscover.\fP\fIexample.com\fP\fB/autodiscover/autodiscover.xml\fP>. |
| 49 | +.IP \(bu 4 |
| 50 | +Performing a DNS lookup of the name \fB_autodiscover._tcp.\fP\fIdomain\fP of |
| 51 | +record type SRV, and from the response data, constructing the string |
| 52 | +\fBhttps://\fP\fIrdata\fP[\fB:\fP\fIport\fP]\fB/autodiscover/autodiscover.xml\fP. |
| 53 | +.IP \(bu 4 |
| 54 | +Utilizing an unspecified "local mechanism" method. (might be the same |
| 55 | +as using lastrun URL?) |
| 56 | +.IP \(bu 4 |
| 57 | +"Redirect" method: Performing an unauthenticated HTTP GET request to |
| 58 | +<\fBhttp://autodiscover.\fP\fIdomain\fP\fB/autodiscover/autodiscover.xml\fP, |
| 59 | +and upon receiving a HTTP 302 response, using the URL in the "Location:" |
| 60 | +response header for AutoDiscover. |
| 61 | +.PP |
| 62 | +Gromox recommends that administrators employ the AutoDiscover Domain method, |
| 63 | +i.e. add a \fBautodiscover.\fP\fIdomain.com\fP entry to their DNS zones. This |
| 64 | +is beneficial over the root domain method, because the host serving up e.g. a |
| 65 | +company's website need not be taught about autodiscover paths. For |
| 66 | +\fBautodiscover.\fP\fIdomain.com\fP, either an AAAA/A pair \fBor\fP CNAME |
| 67 | +resource record can be used. Split-horizon DNS systems \fBmust\fP publish the |
| 68 | +autodiscover DNS record(s) in the publicly visible set. The AutoDiscover URL |
| 69 | +must equally be reachable from any network segment where access is expected |
| 70 | +from \(em if need be, set up HTTP reverse proxies. |
| 71 | +.SH OXDISCO summary |
| 72 | +When a user sets up a new email account or changes their existing email client |
| 73 | +settings, the email client sends an Autodiscover request to the Autodiscover |
| 74 | +server. The Autodiscover request is an HTTP POST request that contains the |
| 75 | +user's email address. The Autodiscover server then responds with an XML |
| 76 | +response that contains the necessary configuration settings. |
| 77 | +.PP |
| 78 | +The Autodiscover XML response contains information such as |
| 79 | +.IP \(bu 4 |
| 80 | +the list of supported mail protocols and transports (e.g. MSRPC/RPCH/MAPIHTTP, |
| 81 | +IMAP, SMTP, etc.) |
| 82 | +.IP \(bu 4 |
| 83 | +the connection parameters for those (e.g. name of the home server, HTTP |
| 84 | +endpoint URLs) |
| 85 | +.IP \(bu 4 |
| 86 | +for MAPI, any extra mailboxes that should be opened unconditionally (e.g. |
| 87 | +delegators, public folder) |
| 88 | +.PP |
| 89 | +The email client uses this information to configure the user's email account |
| 90 | +automatically. |
| 91 | +.SH gromox-dscli notes |
| 92 | +The gromox\-dscli(8) utility can be used to diagnose problems with AutoDiscover |
| 93 | +from a command line prompt. |
| 94 | +.PP |
| 95 | +gromox-dscli's probes and their order is: RootDomain, AutoDiscoverDomain, SRV. |
| 96 | +.SH Outlook notes |
| 97 | +When Outlook is running, there is an Outlook icon in the Windows taskbar's |
| 98 | +notification area. By pressing Ctrl+RightMouseBtn, a service menu can be |
| 99 | +brought up, which offers a "Test AutoDiscover" command for diagnosing problems |
| 100 | +from Windows. Known bugs: The dialog may ignore the contents of the password |
| 101 | +field and instead use a saved password or SSO, leading to potentially |
| 102 | +unanticipated authentication successes or failures. If in doubt, use |
| 103 | +gromox-dscli. |
| 104 | +.PP |
| 105 | +When an AutoDiscover response contains broken information (e.g. unreachable |
| 106 | +endpoints due to a faulty oxdisco_exonym setting on the server), Outlook may |
| 107 | +refuse to open mailboxes and the application may exit prematurely. AutoDiscover |
| 108 | +responses are cached on disk under `%LOCALAPPDATA%/Microsoft/Outlook/* - |
| 109 | +Autodiscover.xml` and/or `%LOCALAPPDATA%/Microsoft/Outlook/16/AutoD.*.xml` and |
| 110 | +can be deleted/diagnosed as needed. |
| 111 | +.PP |
| 112 | +Outlook's probes and primary order: TXT, LDAP-SCP, RootDomain, |
| 113 | +AutoDiscoverDomain, SRV, Local, Redirect. Secondary order observed: TXT, LDAP, |
| 114 | +RootDomain, AutoDiscoverDomain, Local, Redirect, SRV. |
| 115 | +.PP |
| 116 | +Individual probes can be disabled via Windows Registry in |
| 117 | +HKEY_CURRENT_USER\\Software\\Microsoft\\Office\\16.0\\Outlook\\AutoDiscover |
| 118 | +and/or |
| 119 | +HKEY_CURRENT_USER\\Software\\Policies\\Microsoft\\Office\\16.0\\Outlook\\AutoDiscover, |
| 120 | +by setting one or more of ExcludeLastKnownGoodURL=DWORD:1, |
| 121 | +ExcludeExplicitO365Endpoint=DWORD:1, EnableOffice365ConfigService=DWORD:0, |
| 122 | +ExcludeScpLookup=DWORD:1, ExcludeHttpsRootDomain=DWORD:1, |
| 123 | +ExcludeHttpsAutoDiscoverDomain=DWORD:1, ExcludeSrvRecord=DWORD:1, |
| 124 | +ExcludeHttpRedirect=DWORD:1 as desired. For Group Policy ADMX template and ADML |
| 125 | +language packs are available from |
| 126 | +<https://www.microsoft.com/en-us/download/details.aspx?id=49030>. |
| 127 | +.PP |
| 128 | +When a DNS zone is M365-enabled, Outlook opens a mini browser window for |
| 129 | +authenticating with M365. To prevent this, you can set |
| 130 | +ExcludeExplicitO365Endpoint=1 as described. |
| 131 | +.PP |
| 132 | +Outlook stops probing after the first successful AutoDiscover HTTP POST |
| 133 | +request. A non-responsive AutoDiscovery server (firewall DROP policy, or TCP |
| 134 | +RST) is treated the same as a 404 Not Found response. |
| 135 | +.PP |
| 136 | +Known bugs: Outlook ignores the port number in the DNS SRV response. Outlook |
| 137 | +and/or the Windows HTTP libraries also erroneously show a warning popup |
| 138 | +whenever the hostname in the SRV result does not match the e-mail domain (even |
| 139 | +under MS Exchange). Redirection is the key idea of an SRV record and, as far as |
| 140 | +security considerations go, is no more significant than following a CNAME-typed |
| 141 | +autodiscover.example.com record. |
| 142 | +.PP |
| 143 | +Outlook re-runs AutoDiscover periodically in the background. This can cause |
| 144 | +popups such as re-authentication or SRV warnings (particularly after a |
| 145 | +temporary outage). |
| 146 | +.SH Testing scenarios |
| 147 | +To force using a particular Autodiscover server in Windows, such as when Gromox |
| 148 | +is run in a development environment with a fake domain, |
| 149 | +c:\\windows\\system32\\drivers\\etc\\hosts can be populated with a static entry |
| 150 | +for \fBautodiscover.\fP\fIexample.com\fP to get that particular scenario |
| 151 | +working. |
| 152 | +.SH See also |
| 153 | +\fBgromox\fP(7), \fBautodiscover\fP(4gx) |
0 commit comments