docs: document wildcard custom domains - #392
Merged
Merged
Conversation
A wildcard domain (*.sso.yourdomain.com) serves every subdomain beneath it from a single entry, which is what you want if you give each of your own customers a branded login URL. Enterprise, and it counts as one custom domain however many subdomains you go on to serve. The section leads with the two records needed, then spends most of its length on the one thing that goes wrong: adding a CNAME per subdomain. That is the intuitive move, it looks harmless, and it breaks the name permanently -- it stops the wildcard resolving anything below it and makes that name impossible to certify, because a certificate needs a validation record beneath the name while routing needs a CNAME at it, and DNS allows only one of those. Anyone migrating from per-customer records has to remove them rather than add to them, so this needed saying plainly rather than as a footnote. Three other things documented because each has bitten in testing: - A wildcard covers one level only, and fails as a browser security warning rather than an error page -- so customers generating URLs from customer names need to validate the shape. - Each subdomain is its own token issuer. An application checking a single hardcoded `iss` rejects every token, which is the likeliest support ticket this feature generates. - Sessions do not carry across subdomains, since cookies are host-scoped. Prettier also realigned one pre-existing table in this file; the file already failed fmt:check on main. Refs #390
Deploying phasetwo-docs with
|
| Latest commit: |
01da808
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://8a95b328.phasetwo-docs.pages.dev |
| Branch Preview URL: | https://update-wildcard-domains.phasetwo-docs.pages.dev |
xgp
approved these changes
Sep 8, 2026
The wildcard page noted in one line that a wildcard does not cover its own parent, and left the reader to work out the rest. The rest turns out to be the sharpest edge on the whole feature, so it gets a section. Routing `sso.yourdomain.com` with a CNAME -- the record type every other custom domain uses, and the one a reader will reach for -- takes the wildcard down. That name already has records beneath it, and a CNAME hides everything below it, so every subdomain stops resolving and the certificate can no longer renew. Neither symptom points back at the record that caused it. An ALIAS resolves to addresses at the name instead of pointing at another name, so it does not occlude; the section names the variants providers use for it, and gives zone delegation as the fallback rather than letting anyone hardcode an address they looked up. It also says the validation record is already there. A wildcard and its parent validate against the same record, so there is nothing to add and the certificate is issued straight away -- the opposite of the "add a record and wait" expectation the page sets everywhere else. Placed directly after the warning against per-subdomain records, and opening by distinguishing the two: a record *at* the parent is expected, a record *beneath* the wildcard is what breaks it. Adjacent without that contrast, the new section reads as contradicting the previous one. The multi-level limit gains the mechanism behind it too. Saying it "fails on the certificate" undersells it: the name resolves, the edge routes it, Keycloak answers, and the sole thing standing in the way is a hostname the certificate does not cover -- which browsers render as a full-page impersonation warning on the login screen. That is why the guidance is to validate the label shape before handing out a URL, rather than to expect a clean error.
This file contains hidden or 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #390.
Documents wildcard custom domains (
*.sso.yourdomain.com) indocs/self-service/custom-domains.md— one entry that serves every subdomain beneath it, for customers who give each of their customers a branded login URL. Enterprise, and it consumes one custom-domain slot however many subdomains follow.Structure
Leads with the two DNS records, then spends most of its length on the one thing that goes wrong.
Adding a CNAME per subdomain. It is the intuitive move, it looks harmless, and it breaks that name permanently: it stops the wildcard resolving anything below it, and makes the name impossible to certify — a certificate needs a validation record beneath the name while routing needs a CNAME at it, and DNS allows only one of those. Anyone migrating from per-customer records has to remove them rather than add to them, so it needed saying plainly rather than as a footnote.
The section also explains that the validation record sits beside the customer subdomains rather than beneath any of them, since that is the structural reason the pattern works at all.
Three other things, each of which bit during testing
issrejects every token. This is the likeliest support ticket the feature generates, so it gets its own subsection rather than a bullet.Plus: app association files are unavailable on a wildcard, cross-linked to the existing section that explains exact-hostname matching.
Notes for review
docusaurus buildsucceeds with no MDX errors or broken links.fmt:checkonmainand CI does not enforce it, but reverting would leave the file half-formatted. Five lines, table padding only.yourdomain.comand the already-documented{cluster_name}.global.auth.ac.Ships after the feature is available: backend p2-inc/phasetwo-keycloak#663, dashboard p2-inc/dashboard-v2#281.
🤖 Generated with Claude Code