Skip to content

Commit eadea64

Browse files
pottisSuresh Potti
pottis
and
Suresh Potti
authored
Explainer for wellknown discovery at apex domain (#828)
Co-authored-by: Suresh Potti <sureshpotti@microsoft.com>
1 parent fa2a08f commit eadea64

1 file changed

Lines changed: 204 additions & 0 deletions

File tree

‎explorations/well_known_subdomain.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# FedCM Well-Known Subdomain Discovery — Explainer
2+
3+
**Authors:**
4+
Suresh Potti (sureshpotti@microsoft.com)
5+
6+
## Participate
7+
8+
- https://github.com/w3c-fedid/FedCM/issues/809
9+
- https://github.com/w3c-fedid/FedCM/pull/823
10+
11+
## Summary
12+
13+
This document describes a proposed addition to FedCM's [=well-known file=] discovery
14+
algorithm: allow an Identity Provider (IDP) to host the well-known file at a fixed
15+
`web-identity.<registrable domain>` subdomain in addition to the existing apex
16+
(`<registrable domain>`) location. The user agent attempts the subdomain first and
17+
falls back to the apex if the subdomain fetch fails. This preserves all of FedCM's
18+
existing anti-fingerprinting privacy properties while removing operational obstacles
19+
that today prevent some organizations from deploying FedCM.
20+
21+
## Status
22+
23+
Proposed addition to the FedCM specification, captured in
24+
[PR #823](https://github.com/w3c-fedid/FedCM/pull/823) and motivated by
25+
[Issue #809](https://github.com/w3c-fedid/FedCM/issues/809).
26+
27+
## Problem Statement
28+
29+
FedCM's current spec requires the well-known file to be served from the IDP's
30+
[registrable domain](https://url.spec.whatwg.org/#host-registrable-domain) — for
31+
`login.contoso.com` that means `https://contoso.com/.well-known/web-identity`. This
32+
two-tier design exists for a critical privacy reason: it prevents the IDP from
33+
fingerprinting the Relying Party (RP) by encoding RP information in the config file
34+
path (see [`#manifest-fingerprinting`](https://fedidcg.github.io/FedCM/#manifest-fingerprinting)).
35+
36+
The privacy goal is sound, but pinning the file to the apex (registrable) domain
37+
creates real-world deployment friction for many organizations:
38+
39+
### 1. Apex domains are operationally awkward
40+
41+
Apex domains (e.g., `contoso.com`) cannot use DNS `CNAME` records because they must
42+
hold `NS` and `SOA` records at the zone root. Modern cloud and CDN providers expect
43+
`CNAME`-based onboarding for load balancing, geographic affinity, and failover.
44+
Workarounds (`ALIAS` / `ANAME` records, or pinned `A`/`AAAA` records) exist but are
45+
not universally supported and frequently degrade DNS-driven traffic management.
46+
47+
### 2. Split ownership of subdomains
48+
49+
Within a single registrable domain, different subdomains often belong to different
50+
teams or vendors:
51+
52+
| Subdomain | Operated by |
53+
| ------------------------ | ------------------------------------------ |
54+
| `contoso.com` (apex) | Marketing CMS / brand site |
55+
| `login.contoso.com` | Authentication service (e.g., Entra B2C) |
56+
| `support.contoso.com` | Ticketing SaaS |
57+
| `blog.contoso.com` | Substack / external blog |
58+
59+
Requiring the well-known file at the apex couples the authentication service's
60+
release process to whichever team owns the apex web property. Both teams must
61+
coordinate to ship FedCM, and any change at the apex risks breaking sign-in.
62+
63+
### 3. White-label IDPs cannot host on the customer apex
64+
65+
When an organization delegates authentication to a white-label IDP (Okta, Microsoft
66+
Entra External ID/B2C, Auth0, etc.), the customer typically `CNAME`s a subdomain
67+
such as `login.contoso.com` to the IDP. The IDP has no control over `contoso.com`
68+
itself and therefore cannot host the well-known file on its customer's behalf,
69+
making FedCM onboarding a per-customer manual task at the apex.
70+
71+
## Proposed Solution
72+
73+
### How it works
74+
75+
PR #823 adds a fixed subdomain — `web-identity.<registrable domain>` — as an
76+
alternative location for the well-known file. The IDP only needs to point that
77+
subdomain at its existing authentication infrastructure using a standard DNS record:
78+
79+
```
80+
web-identity.contoso.com. CNAME login.contoso.com.
81+
```
82+
83+
The user agent's updated `fetch the config file` algorithm runs as follows:
84+
85+
1. Compute `registrableDomain` from the configUrl host.
86+
2. Build two URLs:
87+
- `subdomainUrl` = `https://web-identity.<registrableDomain>/.well-known/web-identity`
88+
- `rootUrl` (apex fallback) = `https://<registrableDomain>/.well-known/web-identity`
89+
3. Fetch `subdomainUrl` first (in parallel with the config fetch, as today).
90+
4. If the subdomain fetch fails (DNS, TLS, HTTP error, malformed JSON, or
91+
`provider_urls` length > 1), immediately fall back to fetching `rootUrl`.
92+
5. Validate the resulting well-known file against the config URL exactly as before.
93+
94+
The same-site shortcut (`skipWellKnown` when RP and IDP share a registrable domain)
95+
is preserved.
96+
97+
### Why this preserves privacy
98+
99+
The anti-fingerprinting guarantee of the well-known file rests on two properties:
100+
101+
1. The file lives at a **fixed path** the IDP cannot vary per RP.
102+
2. The file lives within a **location the IDP cannot use to encode RP identity**.
103+
104+
Both still hold. `web-identity.<registrable domain>` is a fixed name within the
105+
same registrable domain the IDP already controls. There is no per-RP variation,
106+
no new origin to enumerate, and the request continues to be sent without
107+
credentials, without a `Referer`, and from an opaque origin — identical to the
108+
existing apex fetch.
109+
110+
### Why a fixed subdomain (not a configurable one)
111+
112+
A configurable subdomain would reintroduce exactly the fingerprinting surface the
113+
well-known file was designed to eliminate: the IDP could vary the location based on
114+
the RP. A single, hard-coded label (`web-identity.`) keeps the location
115+
deterministic and inspectable.
116+
117+
### Why subdomain-first with apex fallback (not the other way around)
118+
119+
Subdomain-first benefits new and white-label deployments without breaking any IDP
120+
that has already shipped against the apex location. Apex-first would force every
121+
new deployment to wait one fetch round-trip before reaching the working subdomain.
122+
The fallback is triggered only on actual failure, so steady-state cost for
123+
already-deployed apex IDPs is one extra failed request per discovery — and the
124+
spec allows the fallback to begin immediately on subdomain failure rather than
125+
waiting for the config fetch.
126+
127+
## Example deployment
128+
129+
A white-label IDP, `idp.example`, hosts authentication for `contoso.com`:
130+
131+
1. Customer (`contoso.com`) creates a single DNS record:
132+
```
133+
web-identity.contoso.com. CNAME tenants.idp.example.
134+
```
135+
2. The white-label IDP serves `/.well-known/web-identity` from
136+
`tenants.idp.example` with the customer's `provider_urls` entry.
137+
3. No change is required at `contoso.com` (the apex). The marketing site, CDN,
138+
and any other apex tenants are untouched.
139+
4. User agents fetching `https://login.contoso.com/fedcm/config.json` discover
140+
the well-known file at `https://web-identity.contoso.com/.well-known/web-identity`
141+
on the first try.
142+
143+
## Alternatives considered
144+
145+
### Keep apex-only (status quo)
146+
147+
Rejected. Documented operational pain (apex DNS limitations, split ownership,
148+
white-label delegation) is real and is blocking adoption today. See discussion
149+
on Issue #809.
150+
151+
### Allow the IDP to declare an arbitrary well-known location
152+
153+
Rejected. Any IDP-controlled location reintroduces RP fingerprinting via the
154+
discovery URL, which is the exact threat the well-known file mitigates.
155+
156+
### Use a different fixed label (e.g., `fedcm.`, `.well-known.`)
157+
158+
`fedcm.` was the label proposed in Issue #809. PR #823 settled on `web-identity.`
159+
to match the existing well-known path segment (`/.well-known/web-identity`) and
160+
to leave room for non-FedCM Web Identity specifications to share the same
161+
discovery point. The label choice is a bikeshed but `web-identity.` is consistent
162+
with the existing naming.
163+
164+
### Require IDPs to migrate to the subdomain
165+
166+
Rejected as a breaking change. Apex fallback keeps already-deployed IDPs working
167+
unchanged; the subdomain is purely additive.
168+
169+
## Privacy and Security Considerations
170+
171+
- **No new fingerprinting surface.** The discovery URL is a deterministic function
172+
of the registrable domain. The IDP cannot encode RP identity in it.
173+
- **Same request shape as today.** Subdomain and apex fetches both use
174+
`credentials: "omit"`, `referrer-policy: "no-referrer"`, an opaque origin, and
175+
`Sec-Fetch-Dest: webidentity`.
176+
- **TLS still required.** The subdomain must serve a valid certificate covering
177+
`web-identity.<registrable domain>`. IDPs that cannot or will not provision such
178+
a certificate simply continue to use the apex location.
179+
- **Cookie scope unchanged.** No cookies are sent on either fetch; the subdomain
180+
introduces no new cookie-sharing surface beyond what `*.contoso.com` already
181+
implies.
182+
- **Content authority unchanged.** The IDP still proves authority over the
183+
registrable domain by being able to serve content under it; whether that proof
184+
comes from the apex or the `web-identity.` subdomain is equivalent for FedCM's
185+
trust model, since both are within the same site.
186+
187+
## Open Questions
188+
189+
- **Should the apex fallback eventually be deprecated?** Not in this proposal.
190+
PR #823 keeps it indefinitely for backward compatibility.
191+
- **Caching.** Should a successful subdomain discovery be cached so that the apex
192+
fallback is not retried on every navigation? The existing well-known caching
193+
behavior applies; no new cache key is introduced.
194+
- **Interaction with `provider_urls` size relaxation
195+
([Issue #333](https://github.com/fedidcg/FedCM/issues/333))** — orthogonal; the
196+
fallback rules treat `> 1` entries as failure today and that behavior is
197+
preserved on both subdomain and apex fetches.
198+
199+
## References
200+
201+
- Issue: [w3c-fedid/FedCM#809](https://github.com/w3c-fedid/FedCM/issues/809)
202+
- PR: [w3c-fedid/FedCM#823](https://github.com/w3c-fedid/FedCM/pull/823)
203+
- Spec sections touched: `#well-known-discovery`, `#fetch-config-file`,
204+
`#manifest-fingerprinting`, `#deployment-well-known`

0 commit comments

Comments
 (0)