-
Notifications
You must be signed in to change notification settings - Fork 42
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
doc: join Autodiscover document from grommunio Knowledge Base
- Loading branch information
Showing
4 changed files
with
161 additions
and
79 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,153 @@ | ||
| .\" SPDX-License-Identifier: CC-BY-SA-4.0 or-later | ||
| .\" SPDX-FileCopyrightText: 2021-2024 grommunio GmbH | ||
| .TH autodiscover 7 "" "Gromox" "Gromox admin reference" | ||
| .SH Name | ||
| autodiscover \(em AutoDiscover protocols | ||
| .SH Description | ||
| .PP | ||
| AutoDiscover is a HTTP-based discovery protocol that helps users configure | ||
| their email client settings automatically. The MS-OXDSCLI specification | ||
| speaks about locating such AutoDiscover service, the MS-OXDISCO specification | ||
| speaks about the XML exchange between such a service and a client. These terms | ||
| are herein used to avoid ambiguity in the "AD" acronym (ActiveDirectory). | ||
| .PP | ||
| Autodiscover V2 is not an improved version, it is an extra layer that warrants | ||
| a disgruntled remark about questionable protocol design. Locating the | ||
| AutoDiscover server still happens via DNS or AD-SCP query. The V2 request | ||
| contains the user identity and the name of a next-level protocol that the | ||
| client seeks, e.g. "ActiveSync", "EWS" or "AutoDiscoverV1". The response is now | ||
| a JSON document and generally contains just one URL, namely for the service | ||
| sought. Indeed there is no way to obtain MAPI, IMAP or SMTP information in | ||
| Autodiscover V2. | ||
| .PP | ||
| Note that Autodiscover is not used exclusively by Microsoft Outlook, | ||
| Autodiscover is the main discovery protocol for any EAS-enabled device and | ||
| application, such as Apple iOS, Android and other applications. | ||
| .SH OXDSCLI summary | ||
| Clients collect one or more AutoDiscover URLs and make HTTP POST requests to | ||
| those endpoints to request server configuration. Among the methods that appear | ||
| in the wild: | ||
| .IP \(bu 4 | ||
| Using an URL from a previous successful run. | ||
| .IP \(bu 4 | ||
| Performing a DNS TXT lookup on the domain name to check for the presence of a | ||
| Microsoft 365 account identifier and, if found, using the URL | ||
| <\fBhttps://outlook.office365.com/autodiscover/autodiscover.xml\fP>. | ||
| .IP \(bu 4 | ||
| When joined to an NT Domain/ActiveDirectory, performing an LDAP lookup for | ||
| service connection points (SCP), i.e. objects matching | ||
| "(&(objectClass=serviceConnectionPoint) | ||
| (serviceClassName=ms-Exchange-AutoDiscover-Service))", and using the URLs | ||
| obtained from "serviceBindingInformation" attributes. | ||
| .IP \(bu 4 | ||
| "Root domain" method: Constructing a string based on the user's e-mail address | ||
| (e.g. u@example.com), | ||
| <\fBhttps://\fIexample.com\fP\fB/autodiscover/autodiscover.xml\fP>. | ||
| .IP \(bu 4 | ||
| "AutoDiscover domain" method: Constructing a string based on the user identity, | ||
| <\fBhttps://autodiscover.\fP\fIexample.com\fP\fB/autodiscover/autodiscover.xml\fP>. | ||
| .IP \(bu 4 | ||
| Performing a DNS lookup of the name \fB_autodiscover._tcp.\fP\fIdomain\fP of | ||
| record type SRV, and from the response data, constructing the string | ||
| \fBhttps://\fP\fIrdata\fP[\fB:\fP\fIport\fP]\fB/autodiscover/autodiscover.xml\fP. | ||
| .IP \(bu 4 | ||
| Utilizing an unspecified "local mechanism" method. (might be the same | ||
| as using lastrun URL?) | ||
| .IP \(bu 4 | ||
| "Redirect" method: Performing an unauthenticated HTTP GET request to | ||
| <\fBhttp://autodiscover.\fP\fIdomain\fP\fB/autodiscover/autodiscover.xml\fP, | ||
| and upon receiving a HTTP 302 response, using the URL in the "Location:" | ||
| response header for AutoDiscover. | ||
| .PP | ||
| Gromox recommends that administrators employ the AutoDiscover Domain method, | ||
| i.e. add a \fBautodiscover.\fP\fIdomain.com\fP entry to their DNS zones. This | ||
| is beneficial over the root domain method, because the host serving up e.g. a | ||
| company's website need not be taught about autodiscover paths. For | ||
| \fBautodiscover.\fP\fIdomain.com\fP, either an AAAA/A pair \fBor\fP CNAME | ||
| resource record can be used. Split-horizon DNS systems \fBmust\fP publish the | ||
| autodiscover DNS record(s) in the publicly visible set. The AutoDiscover URL | ||
| must equally be reachable from any network segment where access is expected | ||
| from \(em if need be, set up HTTP reverse proxies. | ||
| .SH OXDISCO summary | ||
| When a user sets up a new email account or changes their existing email client | ||
| settings, the email client sends an Autodiscover request to the Autodiscover | ||
| server. The Autodiscover request is an HTTP POST request that contains the | ||
| user's email address. The Autodiscover server then responds with an XML | ||
| response that contains the necessary configuration settings. | ||
| .PP | ||
| The Autodiscover XML response contains information such as | ||
| .IP \(bu 4 | ||
| the list of supported mail protocols and transports (e.g. MSRPC/RPCH/MAPIHTTP, | ||
| IMAP, SMTP, etc.) | ||
| .IP \(bu 4 | ||
| the connection parameters for those (e.g. name of the home server, HTTP | ||
| endpoint URLs) | ||
| .IP \(bu 4 | ||
| for MAPI, any extra mailboxes that should be opened unconditionally (e.g. | ||
| delegators, public folder) | ||
| .PP | ||
| The email client uses this information to configure the user's email account | ||
| automatically. | ||
| .SH gromox-dscli notes | ||
| The gromox\-dscli(8) utility can be used to diagnose problems with AutoDiscover | ||
| from a command line prompt. | ||
| .PP | ||
| gromox-dscli's probes and their order is: RootDomain, AutoDiscoverDomain, SRV. | ||
| .SH Outlook notes | ||
| When Outlook is running, there is an Outlook icon in the Windows taskbar's | ||
| notification area. By pressing Ctrl+RightMouseBtn, a service menu can be | ||
| brought up, which offers a "Test AutoDiscover" command for diagnosing problems | ||
| from Windows. Known bugs: The dialog may ignore the contents of the password | ||
| field and instead use a saved password or SSO, leading to potentially | ||
| unanticipated authentication successes or failures. If in doubt, use | ||
| gromox-dscli. | ||
| .PP | ||
| When an AutoDiscover response contains broken information (e.g. unreachable | ||
| endpoints due to a faulty oxdisco_exonym setting on the server), Outlook may | ||
| refuse to open mailboxes and the application may exit prematurely. AutoDiscover | ||
| responses are cached on disk under `%LOCALAPPDATA%/Microsoft/Outlook/* - | ||
| Autodiscover.xml` and/or `%LOCALAPPDATA%/Microsoft/Outlook/16/AutoD.*.xml` and | ||
| can be deleted/diagnosed as needed. | ||
| .PP | ||
| Outlook's probes and primary order: TXT, LDAP-SCP, RootDomain, | ||
| AutoDiscoverDomain, SRV, Local, Redirect. Secondary order observed: TXT, LDAP, | ||
| RootDomain, AutoDiscoverDomain, Local, Redirect, SRV. | ||
| .PP | ||
| Individual probes can be disabled via Windows Registry in | ||
| HKEY_CURRENT_USER\\Software\\Microsoft\\Office\\16.0\\Outlook\\AutoDiscover | ||
| and/or | ||
| HKEY_CURRENT_USER\\Software\\Policies\\Microsoft\\Office\\16.0\\Outlook\\AutoDiscover, | ||
| by setting one or more of ExcludeLastKnownGoodURL=DWORD:1, | ||
| ExcludeExplicitO365Endpoint=DWORD:1, EnableOffice365ConfigService=DWORD:0, | ||
| ExcludeScpLookup=DWORD:1, ExcludeHttpsRootDomain=DWORD:1, | ||
| ExcludeHttpsAutoDiscoverDomain=DWORD:1, ExcludeSrvRecord=DWORD:1, | ||
| ExcludeHttpRedirect=DWORD:1 as desired. For Group Policy ADMX template and ADML | ||
| language packs are available from | ||
| <https://www.microsoft.com/en-us/download/details.aspx?id=49030>. | ||
| .PP | ||
| When a DNS zone is M365-enabled, Outlook opens a mini browser window for | ||
| authenticating with M365. To prevent this, you can set | ||
| ExcludeExplicitO365Endpoint=1 as described. | ||
| .PP | ||
| Outlook stops probing after the first successful AutoDiscover HTTP POST | ||
| request. A non-responsive AutoDiscovery server (firewall DROP policy, or TCP | ||
| RST) is treated the same as a 404 Not Found response. | ||
| .PP | ||
| Known bugs: Outlook ignores the port number in the DNS SRV response. Outlook | ||
| and/or the Windows HTTP libraries also erroneously show a warning popup | ||
| whenever the hostname in the SRV result does not match the e-mail domain (even | ||
| under MS Exchange). Redirection is the key idea of an SRV record and, as far as | ||
| security considerations go, is no more significant than following a CNAME-typed | ||
| autodiscover.example.com record. | ||
| .PP | ||
| Outlook re-runs AutoDiscover periodically in the background. This can cause | ||
| popups such as re-authentication or SRV warnings (particularly after a | ||
| temporary outage). | ||
| .SH Testing scenarios | ||
| To force using a particular Autodiscover server in Windows, such as when Gromox | ||
| is run in a development environment with a fake domain, | ||
| c:\\windows\\system32\\drivers\\etc\\hosts can be populated with a static entry | ||
| for \fBautodiscover.\fP\fIexample.com\fP to get that particular scenario | ||
| working. | ||
| .SH See also | ||
| \fBgromox\fP(7), \fBautodiscover\fP(4gx) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters