Internet-Draft DNS Issuer Discovery June 2026
Canning Expires 18 December 2026 [Page]
Workgroup:
Web Authorization Protocol
Internet-Draft:
draft-canning-oauth-dns-issuer-discovery-latest
Published:
Intended Status:
Standards Track
Expires:
Author:
S. Canning
Canva

DNS-Based Discovery of OAuth Authorization Servers for Email Domains

Abstract

This document defines a mechanism by which an OAuth 2.0 client can discover the OAuth 2.0 Authorization Server (the "issuer") associated with an email domain, without prior bilateral configuration between the client and the issuer. Two discovery sources are defined: a DNS TXT record at an underscore-prefixed name beneath the email domain, and an HTTPS well-known URI at the email-domain apex. A precedence ordering across these sources and the existing WebFinger-based mechanism in OpenID Connect Discovery 1.0 is specified, together with deterministic rules for handling disagreement among sources.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on 18 December 2026.

▲

Table of Contents

1. Introduction

OAuth 2.0 [RFC6749] and OpenID Connect both presume that a client has, in advance, an identifier for the Authorization Server it intends to use. In enterprise SSO scenarios where a Software-as-a-Service (SaaS) application authenticates a user against the user's enterprise Identity Provider (IdP), the application typically discovers the IdP from the domain part of the user's email address. OpenID Connect Discovery 1.0 [OIDC-Discovery] §2 defines this mapping via WebFinger [RFC7033].

In practice, WebFinger-based issuer discovery is effectively undeployed:

The operational reality is that the people who control the DNS zone for an organisation's email domain already publish records that govern email security posture, including MX, SPF, DKIM, and DMARC. Adding one more record to point at the OAuth issuer for the same domain matches that operational model. This document specifies that record.

A second mechanism, an HTTPS well-known URI [RFC8615] at the email-domain apex, is also defined; it serves as a fallback when DNS is unavailable to the client and as a point of compatibility for deployments that prefer to publish discovery information over HTTPS.

When two or more discovery sources are queried for the same email domain, they MAY disagree. This document defines a deterministic precedence ordering, and a stop-on-first-validated-result rule, that together yield consistent client behaviour in the face of incomplete deployment, staged migration, and partial misconfiguration.

This document does not address how the discovered issuer's authority over the email domain is to be established once known. The work required to bind an issuer to an email domain in a way the Relying Party can verify is the subject of a companion draft [I-D.canning-oauth-issuer-domain-binding].

1.1. Editor's note: running-code basis

  • This draft is motivated by, and tracks, two concrete gaps recorded in the spec/GAPS.md file of the zeroconf-sso prototype [ZEROCONF-SSO] [GAPS]:

    • GAP-1 — "DNS-based issuer discovery is unstandardized".

    • GAP-5 — "Discovery source conflict handling".

    The Relying Party component of that prototype implements §3 and §4 of this document. Implementer feedback from that prototype, including the choice of underscore prefix for the DNS owner name and the choice to stop at the first validated source rather than require source agreement, is the running-code basis for the rules in this draft.

1.2. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

The following terms are used throughout:

End-User:

The natural person whose authentication is being requested.

Email domain:

The substring of the End-User's email address after the final @ character.

Relying Party (RP):

The OAuth client initiating the authentication request, typically a SaaS application.

Issuer:

The OAuth 2.0 Authorization Server identifier, as defined in [RFC8414] §2: an https URL with no query component and no fragment component.

Discovery source:

One of the three mechanisms defined in this document for resolving an email domain to an issuer identifier: DNS TXT (§3), HTTPS well-known URI (§4), and WebFinger (§5).

2. Discovery Procedure

2.1. Input

The Relying Party MUST accept an End-User-supplied email address as input to discovery. The Relying Party MUST extract the email domain as the substring after the final @ character. The Relying Party MUST NOT transmit the End-User's full email address to any party during discovery, except for the WebFinger source (§5), which by construction requires an acct: URI containing the local part.

2.2. Precedence and stop-on-first-validated-result

The Relying Party MUST attempt the discovery sources in the following order and MUST stop at the first source whose response contains a candidate issuer identifier that passes validation per §6:

  1. DNS TXT record at _openid-issuer.<email-domain> (§3).

  2. HTTPS well-known URI /.well-known/openid-issuer at the email domain (§4).

  3. WebFinger discovery as in [OIDC-Discovery] §2 (§5).

A candidate that fails validation MUST NOT cause the discovery to fail overall; the Relying Party MUST fall through to the next source.

If no source returns a candidate that passes validation, the Relying Party MUST surface a non-fatal error to the End-User. The Relying Party MUST NOT fall back to a default issuer chosen by the Relying Party.

The Relying Party MUST NOT continue to query lower-precedence sources after a higher-precedence source has returned a validated result, even if the higher-precedence source's issuer subsequently fails Authorization Server Metadata retrieval [RFC8414] §3.

The rationale for stop-on-first-validated-result, as opposed to requiring agreement among multiple sources, is operational: during staged rollouts a deployer will commonly add a new source (the DNS TXT record) before retiring an older one (a WebFinger response); requiring agreement would force a flag-day cutover.

2.3. Discovery results and source disagreement

Two distinct sources MAY return validated candidates whose values differ. Per §2.2 this disagreement does not affect the Relying Party's choice of issuer — the higher-precedence source's value is used. The Relying Party SHOULD log the disagreement and the values returned by each source.

The Relying Party MUST NOT treat agreement between two sources as a trust uplift, e.g. as licence to relax authorization, scope, or consent policy.

3. DNS TXT Discovery

3.1. Owner name

The owner name for the discovery TXT record is _openid-issuer.<email-domain>, where <email-domain> is the email domain. The leading underscore-prefixed label MUST be exactly _openid-issuer.

The underscore prefix follows the convention used by other discovery and policy DNS records (e.g. _dmarc, _mta-sts, _acme-challenge) and prevents collision with any user-facing hostname.

3.2. Record format

A discovery TXT record consists of a single RDATA string of the form:

iss=<issuer-url>

where <issuer-url> is an issuer identifier as defined in [RFC8414] §2 and validated per §6 of this document. The token iss= MUST be present, in lower case, and MUST be followed immediately (no whitespace) by the issuer URL.

A record whose RDATA does not begin with iss= MUST be ignored.

3.3. Lookup

To query the DNS TXT discovery source, the Relying Party issues a DNS query of type TXT for the owner name defined in §3.1 over its normal recursive resolver path. No special transport (e.g. DoH [RFC8484] or DoT [RFC7858]) is mandated by this document; see §8 for security considerations.

3.4. Multiple records

If multiple TXT records are returned at the discovery owner name, the Relying Party:

  • MUST treat all returned records whose RDATA begins with iss= as candidate records.

  • MUST reject (treat as if no record were returned) the set if more than one such record is present and the records differ in RDATA byte content.

  • MUST accept the record set if all candidate records are byte-identical (this case arises in some DNS hosting infrastructures that return duplicates).

TXT records at the same owner name not beginning with iss= MUST be ignored for the purposes of this document.

3.5. Validation

The Relying Party MUST parse the candidate record per §3.2, MUST validate the parsed issuer URL per §6, and MUST reject the record on any failure. A rejected DNS TXT record causes fall-through per §2.2.

3.6. Caching

The Relying Party SHOULD cache the result of a DNS TXT lookup for the TTL of the returned record set, subject to an implementation-defined upper bound. The RECOMMENDED upper bound is 24 hours.

A negative result (no record, or no record passing validation) SHOULD also be cached, for an implementation-defined duration. The RECOMMENDED upper bound for negative caching is 15 minutes; this is short enough that newly published records appear without operator intervention but long enough to avoid repeated lookups during a login burst.

4. Well-Known URI Discovery

4.1. URI

This document defines a new well-known URI [RFC8615] suffix openid-issuer, served at the email-domain apex over HTTPS:

GET https://<email-domain>/.well-known/openid-issuer

4.2. Response

A successful response MUST be HTTP 200 OK, MUST carry Content-Type: application/json, and MUST parse to a JSON object containing at minimum a single member named issuer whose value is an issuer identifier as defined in [RFC8414] §2 and validated per §6 of this document:

{
  "issuer": "https://idp.example.com"
}

The response body MAY contain additional members; the Relying Party MUST ignore members not defined by this document or by a later extension.

The response MAY be cached by the Relying Party in accordance with HTTP caching rules [RFC9110], subject to implementation-defined minimum and maximum bounds. RECOMMENDED bounds are 5 minutes and 24 hours respectively.

4.3. Failure modes

Any of the following conditions MUST cause the Relying Party to treat the well-known URI source as not having returned a candidate, and to fall through per §2.2:

  • DNS resolution failure of <email-domain>.

  • TLS handshake failure, including certificate validation failure.

  • HTTP status code other than 200 OK.

  • Content-Type other than application/json (case-insensitive).

  • JSON parse failure.

  • Absence of the issuer member.

  • Failure of issuer validation per §6.

The Relying Party MUST NOT follow HTTP redirects when fetching the well-known URI: a 3xx response is a failure per the second-to-last bullet above, with one exception — the Relying Party MAY follow a redirect only if the redirect target is itself the /.well-known/openid-issuer path at the same host (this accommodates trailing-slash normalisation). Cross-host or cross-scheme redirects MUST cause fall-through.

5. WebFinger Discovery

WebFinger-based discovery is performed as defined in [OIDC-Discovery] §2 with:

The Relying Party MUST extract the href of the matching link as the candidate issuer identifier and MUST validate it per §6. Per [OIDC-Discovery] §2 the Relying Party MAY follow HTTP-layer redirects performed before the JRD is returned, but MUST NOT treat the WebFinger response itself as containing further discovery indirection beyond the single link relation specified above.

The WebFinger source is RETAINED in this profile as the lowest-priority source for backwards compatibility with existing OpenID Connect deployments that publish WebFinger records.

6. Issuer Identifier Validation

A candidate issuer identifier produced by any of §§3, 4, or 5 is valid if and only if all of the following hold (combining the requirements of [RFC8414] §2 and [OIDC-Discovery] §3):

A candidate URL that fails any of these checks MUST be rejected. The Relying Party MUST NOT attempt to repair an invalid URL (e.g. by stripping a query component); it MUST treat the candidate as if the source had returned no record at all.

7. Operational Considerations

7.1. Migrations and dual-publication

A deployer migrating from WebFinger to a DNS-based source SHOULD publish both for an overlap period. Per §2.2, Relying Parties will prefer the higher-precedence DNS-based source as soon as it appears without action by the deployer. Once Relying Party deployments are known to be honouring the new record, the older source MAY be removed.

A deployer simultaneously publishing the DNS TXT record (§3) and the well-known URI (§4) MUST publish identical issuer values across both. If the two values diverge, Relying Parties that consult only one of the sources will reach different conclusions; this is operationally indistinguishable from a misconfiguration and SHOULD be detected by deployer-side monitoring.

7.2. Multi-issuer email domains

A single email domain that fronts multiple distinct issuers (e.g. a parent organisation that has acquired a subsidiary mid-migration) is out of scope for this revision; see Open Issues (§A.3).

8. Security Considerations

8.1. DNS as a trust anchor

The DNS TXT source defined in §3 places trust in the integrity of the DNS resolution path between the Relying Party's recursive resolver and the authoritative nameservers for the email domain. An attacker able to substitute the TXT record for an attacker-controlled value can cause the Relying Party to perform OAuth flows against an attacker-controlled Authorization Server.

The downstream consequences of such substitution are partially mitigated by other parts of the broader profile:

  • The Relying Party validates the Authorization Server's issuer field against the discovered issuer URL during Authorization Server metadata retrieval per [RFC8414] §3.3.

  • The Relying Party validates the iss authorization response parameter [RFC9207] against the discovered issuer URL, defeating mix-up attacks that swap the issuer mid-flow.

  • In the broader zeroconf-sso profile [ZEROCONF-SSO], the Authorization Server's authority over the email domain is intended to be verified by a separate domain-binding mechanism [I-D.canning-oauth-issuer-domain-binding]; until that mechanism is in place, DNS substitution remains a complete compromise of the authentication flow against that single email domain.

Implementers SHOULD ensure that the resolver path used for the §3 lookup is at least as trusted as the resolver path used for SPF, DKIM, and DMARC lookups on the same domain. A deployment that uses a DNSSEC [RFC4035]-validating resolver gains commensurate protection against on-path substitution; this document does not mandate DNSSEC because DNSSEC deployment on email-bearing domains remains incomplete and mandating it would prevent discovery for the majority of domains today. See Open Issues (§A.1).

8.2. TLS as a trust anchor

The well-known URI source defined in §4 places trust in the integrity of the TLS connection to the email domain. The Relying Party MUST validate the server certificate against the email domain per [RFC9110] and reject the connection on any validation failure (no candidate is returned and §2.2 fall-through applies).

8.3. Per-user information disclosure to the WebFinger source

WebFinger queries carry the full email address (as an acct: URI) in the resource parameter. Per §5 this is unavoidable for that source. The Relying Party SHOULD prefer §3 and §4 over §5 in part for this reason; per §2.2 it will, by virtue of the precedence ordering.

8.4. Email domain ≠ enterprise authority

Possession of a DNS zone for an email domain demonstrates the ability to direct messages to that domain. It does not, by itself, demonstrate that the IdP discovered through that domain is authoritative for the identities asserted under that domain (i.e. entitled to assert email_verified for accounts at that domain). The companion draft [I-D.canning-oauth-issuer-domain-binding] addresses this gap.

A Relying Party that relies solely on this document for issuer discovery and does not implement the companion mechanism MUST limit the trust it places in the resulting ID Token, and SHOULD treat the discovered issuer as carrying enterprise-tier authority over only those user accounts the Relying Party has otherwise verified by out-of-band means (e.g. a confirmed-email link to the End-User's email address).

8.5. Negative caching and downgrade

A cached negative result (per §3.6) can mask the subsequent publication of a discovery record. An attacker who can briefly DoS the DNS query path for an email domain at the moment of the first lookup can cause a Relying Party to cache a negative result for the duration of the negative-cache TTL. The RECOMMENDED 15-minute upper bound on negative caching limits the duration of this denial-of-service amplification.

8.6. Source-disagreement masking

The stop-on-first-validated-result rule of §2.2 means that a Relying Party will not detect disagreement between, e.g., a DNS TXT record asserting one issuer and a well-known URI asserting another, unless it explicitly queries both. §2.3 RECOMMENDS that disagreement, where observed, be logged. Whether disagreement-on-purpose is a permitted configuration (e.g. for staged migration where the lower-precedence source is the prior issuer) versus an attack signal is operationally ambiguous; the prototype [ZEROCONF-SSO] treats it as the former and logs but does not alert. See Open Issues (§A.4).

9. IANA Considerations

9.1. Well-Known URI Registration

This document registers the openid-issuer well-known URI in the "Well-Known URIs" registry established by [RFC8615].

URI suffix:

openid-issuer

Change controller:

IETF

Specification document:

This document

Related information:

None

9.2. DNS Underscored Node Name

This document registers the _openid-issuer node name in the "Underscored and Globally Scoped DNS Node Names" registry established by [RFC8552].

RR Type:

TXT

_NODE NAME:

_openid-issuer

Reference:

This document

9.3. No new OAuth registrations

This document defines no new OAuth-related registries and registers no new values in existing OAuth registries.

10. References

10.1. Normative References

[OIDC-Discovery]
OpenID Foundation, "OpenID Connect Discovery 1.0 incorporating errata set 2", , <https://openid.net/specs/openid-connect-discovery-1_0.html>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
[RFC3986]
Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, , <https://www.rfc-editor.org/rfc/rfc3986>.
[RFC7033]
Jones, P., Salgueiro, G., Jones, M., and J. Smarr, "WebFinger", RFC 7033, DOI 10.17487/RFC7033, , <https://www.rfc-editor.org/rfc/rfc7033>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.
[RFC8414]
Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, , <https://www.rfc-editor.org/rfc/rfc8414>.
[RFC8615]
Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, , <https://www.rfc-editor.org/rfc/rfc8615>.

10.2. Informative References

[CIMD]
Parecki, A. and E. Smith, "OAuth Client ID Metadata Document", , <https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/>.
[GAPS]
"zeroconf-sso: standards gaps log (spec/GAPS.md)", , <https://github.com/scanning/zeroconf-sso/blob/main/spec/GAPS.md>.
[I-D.canning-oauth-issuer-domain-binding]
Canning, S., "Issuer-to-Domain Authority Binding for OAuth", , <https://github.com/scanning/zeroconf-sso/blob/main/drafts/draft-canning-oauth-issuer-domain-binding-00.md>.
[RFC4035]
Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, "Protocol Modifications for the DNS Security Extensions", RFC 4035, DOI 10.17487/RFC4035, , <https://www.rfc-editor.org/rfc/rfc4035>.
[RFC6749]
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <https://www.rfc-editor.org/rfc/rfc6749>.
[RFC7858]
Hu, Z., Zhu, L., Heidemann, J., Mankin, A., Wessels, D., and P. Hoffman, "Specification for DNS over Transport Layer Security (TLS)", RFC 7858, DOI 10.17487/RFC7858, , <https://www.rfc-editor.org/rfc/rfc7858>.
[RFC8484]
Hoffman, P. and P. McManus, "DNS Queries over HTTPS (DoH)", RFC 8484, DOI 10.17487/RFC8484, , <https://www.rfc-editor.org/rfc/rfc8484>.
[RFC8552]
Crocker, D., "Scoped Interpretation of DNS Resource Records through "Underscored" Naming of Attribute Leaves", BCP 222, RFC 8552, DOI 10.17487/RFC8552, , <https://www.rfc-editor.org/rfc/rfc8552>.
[RFC9110]
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, , <https://www.rfc-editor.org/rfc/rfc9110>.
[RFC9207]
Meyer zu Selhausen, K. and D. Fett, "OAuth 2.0 Authorization Server Issuer Identification", RFC 9207, DOI 10.17487/RFC9207, , <https://www.rfc-editor.org/rfc/rfc9207>.
[ZEROCONF-SSO]
"zeroconf-sso prototype and profile (running code)", , <https://github.com/scanning/zeroconf-sso>.

Appendix A. Open Issues

This appendix lists open questions that remain unresolved in this revision and that any future revision will need to address. They are the residue of the corresponding entries in spec/GAPS.md of the zeroconf-sso prototype [ZEROCONF-SSO][GAPS] that were not foreclosed in the body of this document.

A.1. A.1 DNSSEC posture

This document does not mandate DNSSEC [RFC4035] for the DNS TXT source. The argument for mandating is straightforward: DNS without DNSSEC is, in the general case, on-path-attacker-modifiable. The argument against mandating is operational: DNSSEC deployment on email-bearing domains is incomplete, and mandating it would prevent this discovery mechanism from working in the majority of cases today. A future revision MAY require DNSSEC for the §3 source, MAY require that Relying Parties surface DNSSEC validation status to the End-User, or MAY define a separate iss-secure= token in the RDATA to indicate that a deployer assertively wishes only DNSSEC-validated lookups to be honoured.

A.2. A.2 Caching numerics

The 24-hour upper bound on positive caching (§3.6, §4.2) and the 15-minute upper bound on negative caching (§3.6) are RECOMMENDED rather than MUSTs. The right values depend on observed operator publication patterns, which are not yet established. A future revision SHOULD either narrow these to fixed values or remove them in favour of a deployer-side Cache-Control header (already in scope for §4.2; absent for §3 where DNS TTL is the only signal).

A.3. A.3 Multi-issuer email domains

A parent organisation that holds multiple OAuth deployments — for example, due to an acquisition that has not yet been integrated, or deliberate operational separation between subsidiaries — has no way in this document to express "use issuer A for the parent.example subsidiary and issuer B for the subsidiary.example subsidiary" when both share an email domain. Two candidate extensions exist:

  • Multi-record DNS TXT, with each record carrying additional selector tokens (e.g. iss=https://... selector=acct-prefix:eu-). This would require per-account dispatch logic on the Relying Party.

  • Issuer-side branching, where the discovered issuer is a single Authorization Server that itself fans out to multiple back-end IdPs per its own policy.

This document takes no position. A future revision SHOULD adopt one of these approaches if the deployment evidence warrants.

A.4. A.4 Trust uplift on source agreement

Per §2.3 the Relying Party MUST NOT treat agreement between two sources as a trust uplift. The contrary position — that agreement across, e.g., DNS TXT and the well-known URI raises the bar an attacker must clear — is intuitively appealing but operationally fragile (it incentivises Relying Parties to query all sources even after a high-precedence one succeeds, defeating the stop-on-first-validated-result rule of §2.2). A future revision MAY revisit this if operational evidence shows that trust uplift on agreement materially reduces phishing or hijack risk.

A.5. A.5 Encoding of multiple TXT RDATA strings

DNS TXT RDATA can be split across multiple character strings; the implementer must decide whether to require single-string RDATA or concatenate. This document RECOMMENDS single-string RDATA in §3.2 but does not forbid concatenation, on the precedent of DKIM and SPF. A future revision MAY tighten this.

Appendix B. Acknowledgments

This work was motivated by the zeroconf-sso prototype [ZEROCONF-SSO], whose spec/GAPS.md log [GAPS] catalogued the specific scenarios cited in §1.1 of this document.

Author's Address

Simon Canning
Canva