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 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…
If you see the linked section…
> The "Well-Known URIs" registry is located at <https://www.iana.org/assignments/well-known-uris/>.
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?).
And https://www.rfc-editor.org/info/rfc8615/#section-3
> Applications that wish to mint new well-known URIs MUST register. them, following the procedures in Section 5.1 […]
Of course this is all voluntary, but why would you risk a name collision with another project if the process is quite straightforward?
Here's one I could find: https://accounts.google.com/.well-known/openid-configuration
But how does one even find this?
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.
That said, I still find it very bizzare that it's so hard to find a tangible example to see how it is in practice.
The rfc has none. Another spec including the use of it has none. In the end only completed service provider/implementers show it.
Before programmatic access happens, it needs to be written by a human. Yet the whole thing feels so human-unfriendly.
Perhaps I am biased robots.txt sets a high bar on how easy it is to find and work with?
It's a JSON array of public keys which you can use to validate a JWT which is what an OIDC token is.
Making it an array means you can rotate keys whenever but the validator is typically caching the public keys.
https://www.hanko.io/blog/understanding-jwks
Actually... found it https://datatracker.ietf.org/doc/html/rfc6749
And here's a PHP implementation that is perfect. https://github.com/thephpleague/oauth2-client
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.