skip to content

Under RFC 8414, for the issuer https://id.example.org/contest, which URL does a client fetch the metadata document from?

level: middleimportance: should knowfreq 50%

answer

  1. inserted, not appended
  2. host first, then well-known, then path
  3. a path-less issuer hides the difference
  4. the other discovery rule appends instead
  5. the issuer path lands after the segment

basics

~10 s

https://id.example.org/.well-known/oauth-authorization-server/contest. RFC 8414 inserts the well-known string between the host and the issuer's path component rather than appending it to the end, which is where the OpenID Connect Discovery 1.0 transformation differs.

solid answer

~40 s

The rule is **insertion**, not appending: the well-known URI string goes between the **host component** and the **path component** of the issuer. For the issuer `https://id.example.org/contest` the document is at `https://id.example.org/.well-known/oauth-authorization-server/contest`, not at `https://id.example.org/contest/.well-known/oauth-authorization-server`. This is exactly where RFC 8414 parts company with OpenID Connect Discovery 1.0, which appends `/.well-known/openid-configuration` after the issuer's path. The difference hides for a long time because most first deployments use an issuer with no path component at all — then there is nothing to insert before, and appending code happens to build the right string. It surfaces the day someone stands up a multi-tenant server where each tenant's issuer carries a path, and every tenant's discovery fetch comes back not found while the root issuer still works.

code

http · 3 lines
http
GET /.well-known/oauth-authorization-server/contest HTTP/1.1
Host: id.example.org
Accept: application/json

go deeper

for a junior

Remember the direction: the well-known segment goes in after the host, and anything the issuer had as a path follows it rather than precedes it.

for a middle

Be able to derive the URL for a path-qualified issuer on the spot, and explain why an appending implementation passes its tests until a multi-tenant issuer appears.

for a senior

Recognise the production symptom — one issuer on a host discovers fine and another comes back not found — and trace it to the transformation rather than to networking or a missing route.

for a principal

Treat it as an interoperability cost: deciding whether your own deployment publishes at more than one location, and what you owe integrators who implemented the other rule.

## The rule RFC 8414 does not give a fixed URL for the metadata document; it gives a **transformation** applied to the authorization server's issuer identifier. The well-known URI string — by default `/.well-known/oauth-authorization-server` — is **inserted between the host component and the path component** of the issuer. The issuer's path, if it has one, ends up **after** the well-known segment. So for the issuer `https://id.example.org/contest` the metadata document is at: `https://id.example.org/.well-known/oauth-authorization-server/contest` and it is **not** at `https://id.example.org/contest/.well-known/oauth-authorization-server`. ## Worked both ways | issuer identifier | RFC 8414 (inserted) | OpenID Connect Discovery 1.0 (appended) | |---|---|---| | `https://id.example.org` | `https://id.example.org/.well-known/oauth-authorization-server` | `https://id.example.org/.well-known/openid-configuration` | | `https://id.example.org/contest` | `https://id.example.org/.well-known/oauth-authorization-server/contest` | `https://id.example.org/contest/.well-known/openid-configuration` | Read the first row and the second together. In the first row both transformations put their well-known segment **directly after the host**, because a path-less issuer leaves nothing to insert in front of. In the second row they diverge: one document sits above the tenant path, the other below it. The two documents are different documents defined by different specifications — the point here is only the shape of the transformation, not what the other document contains. ## Why the wrong rule survives testing Almost every first integration is against an issuer with no path component, and against that issuer a naive "take the issuer string and add the well-known path on the end" implementation produces a working URL. The code passes its tests, ships, and is copied. Then one of these happens: - a **multi-tenant** deployment gives each tenant its own issuer under one host, so every issuer now has a path; - a server is put behind a shared host and moved under a prefix such as `/auth`; - a second environment is stood up with an issuer that is path-qualified to separate it from the first. Every one of those turns the appended URL into a request for a resource that does not exist, while the root issuer keeps working. The symptom is confusing precisely because it is partial: one server discovers fine, another on the same host does not. ## Related rules that go with it - The issuer identifier is a URL using the **https** scheme with **no query or fragment components**. A client that has been handed an issuer with a query string has been handed a broken value, not an unusual one. - The path component is used **exactly once** and only in the position the rule gives it. Host and port stay in front of the well-known segment. - The string is not normalised on the way through. Whatever path the issuer carries, including its case and any trailing slash, is what lands after the well-known segment — and that same byte-exact string is what the client will later compare the document's own `issuer` member against. - The well-known suffix is a **default**, so a client should build the URL from the rule rather than hold a literal URL, which is the habit the rule exists to enforce. ## Publishing at both locations RFC 8414 is aware of the divergence from the earlier OpenID Connect transformation and records it, and a deployment **may** publish its document at more than one location so that older clients keep working. That is a server-side kindness, not something a client may rely on. A client derives the URL by the rule; if it also probes a second location it is guessing, and it will eventually guess a URL that belongs to a different tenant. ## What a client should do 1. Keep the issuer identifier as a single configured string and never split it into separate host and path settings. 2. Reject an issuer that is not https, or that carries a query or fragment, before doing anything else. 3. Build the URL by inserting the well-known segment after the host and before the path, rather than by string concatenation on the end. 4. Do not normalise the issuer — no case folding, no adding or stripping a trailing slash — because the same string is the one the issuer-match check will use. The whole rule is four lines of code, and it is the kind of four lines that gets written once from memory and then diverges silently from the specification. Deriving it, rather than pasting a discovery URL somebody sent you, is the habit the question is really testing.

  • A server's issuer has no path component. Does the insertion rule still say anything?
    Yes — it says the segment goes directly after the host, which is where a naive append also lands. That coincidence is why wrong implementations pass their first round of tests: nothing about the path-less case distinguishes the two rules.
  • How many times does the issuer's path appear in the derived URL?
    Once, after the well-known segment. The host and any explicit port stay in front of it, the scheme is always `https`, and there is no query or fragment to carry because an RFC 8414 issuer may not have either.
  • Should a client fall back to the appended location when the derived URL returns nothing?
    No. A deployment may choose to publish at more than one location, but probing is guessing, and on a shared host a guessed path can land on a document that belongs to a different issuer. Fail the fetch and surface the issuer that was configured.

saying these in an interview costs you the question

  • Appends the well-known path to the end of the issuer.
  • Assumes the OpenID Connect discovery path rule applies to RFC 8414.
  • Treats a trailing slash on the issuer as cosmetic.
  • Believes the two transformations always produce the same URL.
  • Stores a literal discovery URL instead of deriving it from the issuer.