Reference and shipped integration test disagree on Authorization in forward.headers_allow

[OliverWolffGIP]

Summary

The configuration reference says the mediated Authorization header is never written into
forward.headers_allow. The shipped integration-test configuration writes it. Since the ITs are the
only complete BFF configuration in the repository, an adopter copying from them inherits the
contradiction — and has no way to tell which side is right.

The two statements

doc/configuration.adoc, section forward:

Three injections happen automatically and are never written in set_headers /
headers_allow: the mediated Authorization: Bearer on require: session routes (Variants 2/3 —
the gateway sets it from the session's access token, and an inbound Authorization header from
the client is always stripped on those routes) […]

integration-tests/src/main/docker/sheriff-config/endpoints/bff-session.yaml:

      forward:
        headers_allow: ["Authorization", "Content-Type"]

with the accompanying comment:

Authorization is allow-listed so the injected mediated bearer is echoed back by go-httpbin;
Cookie is deliberately NOT allow-listed […]

The comment reads as though allow-listing is what lets the mediated bearer reach the upstream, which
is the opposite of what the reference says.

Why it is not resolvable from the outside

Both readings are self-consistent:

• If the injection bypasses the allowlist, the IT entry is harmless but misleading.
• If the injection is subject to the allowlist, the reference is wrong and every deployment that
  follows it silently forwards no credential — a failure that looks like an upstream authorization
  problem, not a gateway configuration problem.

The second case is the expensive one, and it is not distinguishable by reading. I could not settle
it empirically either, because the login flow could not be driven (cuioss/TokenSheriff#628).

Suggestion

Whichever is correct, making the two agree would help — and a sentence in the reference stating
explicitly what happens to an allow-listed Authorization on a require: session route would
remove the ambiguity for good. If the IT genuinely needs the entry for its echo assertion, saying so
in a way that distinguishes "needed for this test" from "needed for mediation" would be enough.

[OliverWolffGIP]

Correcting my own framing above: I wrote that this is not resolvable from the outside. It is — the answer is in the implementation, and I should have looked there before filing.

ForwardPolicyStage.applyMediatedBearer is applied after copyAllowedHeaders, with the ordering stated explicitly:

/**
 * Applies the require: session stage-4 mediated bearer as the outbound Authorization header,
 * last, so it deterministically wins over any inbound Authorization an allowlist happened to
 * forward. A pure-proxy or require: bearer route resolves no mediated bearer, so this is a no-op there.
 */

So listing Authorization in headers_allow on a require: session route is harmless but inert — the mediated bearer overwrites it either way. The reference is correct in effect, and the integration-test entry costs nothing.

That leaves this as a documentation issue rather than a behavioural one, which lowers its severity considerably. What remains worth doing:

• The IT comment ("Authorization is allow-listed so the injected mediated bearer is echoed back") reads as though the allowlist is what enables the mediation. It is not, and that is the sentence an adopter copies the wrong lesson from.
• The reference could state the precedence directly — that an allow-listed Authorization on a session route is overwritten rather than merged or refused. That is the fact a reader needs, and it is currently only in a Javadoc comment.

Feel free to close or retitle as documentation-only.

[cuioss-oliver]

Resolved by #185 (ce644d7, shipped in 0.1.1). Verified at origin/main — both sides now agree, and they say what this issue asked them to say.

The reference side

doc/configuration.adoc:1908 keeps the automatic-injection statement (the mediated Authorization: Bearer is never listed in headers_allow), and :1879–1880 now answers the question the issue said was "not distinguishable by reading" — what happens to an allow-listed Authorization on a require: session route:

On a require: session route the mediated bearer is merged last and overwrites it regardless, so the upstream still sees only the mediated credential.

:1924 and :1932 pin the full precedence order, so the merge point is no longer implicit.

The integration-test side

integration-tests/src/main/docker/sheriff-config/endpoints/bff-session.yaml:14–20 replaces the comment this issue quoted:

Authorization is listed to re-admit the CLIENT's inbound Authorization past the never-forward set — it is NOT what makes the mediated bearer reach the upstream, and the echo does not depend on it. ForwardPolicyStage merges the mediated bearer LAST, unconditionally and without consulting any forward list, overwriting whatever the mode copy forwarded; go-httpbin would echo it back with this entry absent. The entry is kept because it exercises the single re-admittable member of the never-forward set (ADR-0037) and pins that the mediated bearer still wins over a re-admitted client value.

That is precisely the distinction the issue asked for — "saying so in a way that distinguishes 'needed for this test' from 'needed for mediation'". The entry stays, and the reason it stays is now stated and is not the reason the old comment implied.

Which of the two readings was right

The first one: the injection bypasses the allowlist. So the expensive failure mode this issue identified — "the reference is wrong and every deployment that follows it silently forwards no credential" — did not exist. The IT entry was harmless but misleading, exactly as the issue's first branch predicted.

The same comment block also closes the Cookie half, which the old text left to inference: Cookie's absence from the list is not what withholds it. It is an absolute member of the gateway-owned never-forward set (ADR-0037), so no mode and no list re-admits it.

Closing as resolved.