I spent 10 minutes searching for one in the article, in the RFC, in the wikipedia page, on google, to search for a .well-known example. Couldn't find one.
I did read one before while working with github oidc, and I did find it very useful.
What is it with technical documentations that go deep describing what it is in plenty words but refusing to give a single example? This far from the first case I've ran into either.
> I spent 10 minutes searching for one in the article, in the RFC, in the wikipedia page, on google, to search for a .well-known example. Couldn't find one.
I don't know how that can be, since you claim to have found the RFC; the RFC straight-forwardly states,
> 5. IANA Considerations
> This specification updates the registration procedures for the "Well-Known URI" registry, first defined in [RFC5785]; see Section 3.1.
& then of course directs IANA to establish a registry. We'd expect this section, given the very nature of the RFC is that it establishes a collection of things, so that there is an IANA considerations section should be wholly unsurprising…
And there's a link to a listing of every standardized .well-known URI there is.
> What is it with technical documentations that go deep describing what it is in plenty words but refusing to give a single example?
The RFC provides an example in the form of "example", but also in the form of "robots.txt" (as a "it could have used this, had this existed", but what else could it have done?).
I've been setting up some federated servers (Matrix, activitypub) and I ran into .well_known/ paths in many of them. Webfinger resolver for activitypub and a more custom matrix server-to-server federation endpoint.
well-known is for programmatic access, it either namespaces something you’re told to look for (e.g. various types of domain markers) or it lets you discover a feature / endpoint.
In the latter case you just probe, for instance if you’re a password manager and you have a password for site A you hit A/.well-known/change-password and if they returns something you can surface a change password link to your user.
The one you found is for OIDC provider discovery (https://openid.net/specs/openid-connect-discovery-1_0.html#P...) so someone tells you they want to log in via Google, you hit that endpoint, and it lets you setup Google as an oidc provider rather without needing to hard-code providers. Even if you just want to support Google as a provider, you hit that and you get the entire configuration rather than have to hunt down the same information in the docs.
Pretty much all service discovery should work this way:
1. User enters hostname (or comes in from a QR code or TXT record or whatevs)
2. Client requests GET https://<hostname>/.well-known/<servicename>
3. This either redirects to the canonical base path of the service, which then can be queried itself for instances, or it directly returns a JSON/XML/whatever array of instances of the service on this server, and their respective base paths
This is a lot better than assuming the service must be the document root (forcing service discrimination into the hostname) or assuming it can always have /<servicename>/ as a base path.
What RFC? The oidc discovery spec has an example, and for change-password it’s just a redirect. RFC 8615 is about the existence and management of the .well-know namespace, so examples don’t really make sense.
The great virtue of the in-band challenge types is that web servers can just handle them out of the box, without any need for a separate setup step that depends on your stack. I think this has done a heck of a lot to increase adoption of HTTPS.
Also, DNS-PERSIST-01 seems to be coming soon for Let's Encrypt, which should allow even people that can't easily dynamically update their DNS records to get wildcard certs. I assume this might become more widely used than HTTP-01 challenges.
I wish someone would write a blog post about the difference between DNS registrars and DNS hosts, because I've seen people assume they need to use a registrar that has an API in order to change their DNS records programmatically. I used to assume that too.
I agree that it can be confusing. I use RFC 2136 DNS UPDATE with my own DNS server. But for example, for my workplace this new challenge is convenient as they refuse to want to run their own DNS server.
- registrars control NS records, however these can be changed
- NS records control other records
- registrars can also use their own nameservers to manage your DNS
Slightly less well-known than XDG directories among the developers of Linux-targeted software, it would seem.
Seriously, what an oxymoronic name. "/index.html" is a well known URL, literally: most of web-developers are aware of it. But inventing a bunch of URLs with predefined semantics and then slapping the "well-known" label on it... well, it won't magically make them actually well-known.
I did read one before while working with github oidc, and I did find it very useful.
What is it with technical documentations that go deep describing what it is in plenty words but refusing to give a single example? This far from the first case I've ran into either.