autodiscover(7)

📦
version 3.6 · 2 versions
, in alpine 3.24

🦋 autodiscover(7) — the Gromox admin reference, but make it make sense

okay so real talk, bestie, this is the autodiscover(7) page from the Gromox admin reference and it's literally all about AutoDiscover. strap in 💖

✨ Name ✨

autodiscover — the AutoDiscover protocols. yes, plural, there are two of them and we're gonna talk about both 🎀

🌸 Description 🌸

So AutoDiscover is an HTTP-based discovery protocol — originally a thing Microsoft dropped for Exchange 2007 — and its whole job is helping users configure their email client settings automatically. like, you don't hand-type server names, it just knows. iconic behavior honestly 👑

Two specs run this show, and I'm naming them upfront so we don't get confused:

  • MS-OXDSCLI — this one's about locating the AutoDiscover service
  • MS-OXDISCO — this one's about the XML exchange between that service and a client

We use these terms on purpose, btw, so the acronym "AD" doesn't get messy — because "AD" could mean two things and we are not doing that ambiguity today. (AD here does not mean ActiveDirectory, kthx 💅)

Now. Autodiscover V2. Bestie. Sit down. Autodiscover V2 is not an improved version — it's an extra layer on top, and the manpage itself straight-up warrants a disgruntled remark about questionable protocol design 💀. Locating the AutoDiscover server still happens via DNS or AD-SCP query, same as ever. The V2 request contains the user identity plus the name of a next-level protocol that the client seeks — think "ActiveSync", "EWS" or "AutoDiscoverV1". The response is now a JSON document and generally contains just one URL, namely for the service sought. And fr fr: there is no way to obtain MAPI, IMAP or SMTP information in Autodiscover V2. none. zero. 🌈

Heads up: Autodiscover is not used exclusively by Microsoft Outlook. It's the main discovery protocol for any EAS-enabled device and application — Apple iOS, Android, and other applications too. so yeah, wider reach than you'd think 🫶

🧚 OXDSCLI summary — how clients find the server

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:

  • Using an URL from a previous successful run. (the "it worked last time" classic)
  • 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 https://outlook.office365.com/autodiscover/autodiscover.xml.
  • 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.
  • "Root domain" method: Constructing a string based on the user's e-mail address (e.g. u@example.com), https://example.com/autodiscover/autodiscover.xml.
  • "AutoDiscover domain" method: Constructing a string based on the user identity, https://autodiscover.example.com/autodiscover/autodiscover.xml.
  • Performing a DNS lookup of the name _autodiscover._tcp.domain of record type SRV, and from the response data, constructing the string https://rdata[:port]/autodiscover/autodiscover.xml.
  • Utilizing an unspecified "local mechanism" method. (might be the same as using lastrun URL? 😭 the mystery continues)
  • "Redirect" method: Performing an unauthenticated HTTP GET request to http://autodiscover.domain/autodiscover/autodiscover.xml, and upon receiving a HTTP 302 response, using the URL in the "Location:" response header for AutoDiscover.

👑 the Gromox recommendation (aka what you should actually do)

Gromox recommends that administrators employ the AutoDiscover Domain method — i.e. add a autodiscover.domain.com 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. slay, less work for everyone ✨

For autodiscover.domain.com, either an AAAA/A pair or CNAME resource record can be used.

🚨 Split-horizon DNS systems must 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 — if need be, set up HTTP reverse proxies.

💜 OXDISCO summary — the XML part

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. That request is an HTTP POST request containing the user's email address. The Autodiscover server then responds with an XML response that contains the necessary configuration settings. simple as that, main character energy 🎀

The Autodiscover XML response contains information such as:

  • the list of supported mail protocols and transports (e.g. MSRPC/RPCH/MAPIHTTP, IMAP, SMTP, etc.)
  • the connection parameters for those (e.g. name of the home server, HTTP endpoint URLs)
  • for MAPI, any extra mailboxes that should be opened unconditionally (e.g. delegators, public folder)

The email client uses this information to configure the user's email account automatically. no cap, that's the whole magic trick 🌟

🍓 gromox-dscli notes

The gromox-dscli(8) utility can be used to diagnose problems with AutoDiscover from a command line prompt. so if things are acting up, that's your girl 🫶

gromox-dscli's probes and their order is: RootDomain, AutoDiscoverDomain, SRV.

🔥 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.

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.

Outlook's probes and primary order: TXT, LDAP-SCP, RootDomain, AutoDiscoverDomain, SRV, Local, Redirect. Secondary order observed: TXT, LDAP, RootDomain, AutoDiscoverDomain, Local, Redirect, SRV.

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 the Group Policy editor, ADMX template and ADML language packs are available from https://www.microsoft.com/en-us/download/details.aspx?id=49030. go off, group policy 🌈

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. bye popup 👋

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.

💀 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. so like… chill, Windows 🙈

Outlook re-runs AutoDiscover periodically in the background. This can cause popups such as re-authentication or SRV warnings (particularly after a temporary outage). not the surprise popups bestie 😭

🧪 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 autodiscover.example.com to get that particular scenario working. dev-environment hack, we love a classic 💅

⭐ See also

okay that's the whole page, you're officially AutoDiscover-literate, I'm so proud 🥹💖 this was Gromox documenting autodiscover(7) — go be iconic with your DNS zones, mwah 🎀🦋

📦 where this page comes from