Skip to content

docs: deprecate the id_token response_type default - #63

Merged
turegjorup merged 1 commit into
developfrom
docs/deprecate-implicit-response-type
Aug 26, 2026
Merged

docs: deprecate the id_token response_type default#63
turegjorup merged 1 commit into
developfrom
docs/deprecate-implicit-response-type

Conversation

@turegjorup

Copy link
Copy Markdown
Collaborator

getAuthorizationUrl() defaults to response_type => 'id_token' with response_mode => 'query' — the OIDC implicit flow, with the ID token delivered in the query string. Callers should pass response_type => 'code' and exchange the code with getIdToken(), which is what openid-connect-bundle already does.

The default becomes code in 6.0. This PR announces that and documents why; it changes no behaviour.

Why, accurately

Two reasons, and deliberately not the one that looks obvious:

  • OIDC Core §3.2.2.5 returns implicit-flow parameters in the fragment, which never reaches the server. So the response_mode => 'query' default exists to make the ID token readable server-side — a provider extension (Azure AD B2C supports it) rather than something the spec describes. The README's own verification example reads $request->query->get('id_token'), which only works because of it.
  • It puts a credential in the query string, where web server access logs and browser history keep it.

RFC 9700 §2.1.2 does not forbid this, and the docs say so rather than overstating the case. Its normative sentence covers response types that issue access tokens in the authorization response, and it names code id_token as an acceptable alternative — so a bare id_token response falls outside the prohibition. It does point at code as the flow to prefer.

Why no runtime notice

An E_USER_DEPRECATED would fire on this library's own default path, so every consumer that has never touched response_type would see it, and the only way to silence it is to make the change the notice is asking for. The changelog and README ask for it directly instead. Happy to add the notice if you would rather have it enforced noisily.

Changes

  • README.md gains a Response type: pass code explicitly subsection replacing the bare note that previously just stated the defaults without comment.
  • An inline note on the defaults in getAuthorizationUrl(), so the next reader of that array finds the reasoning at the point of the decision.
  • A ### Deprecated changelog entry.

Verification

136 tests green, coverage 100%, mutation 100% (unchanged — no logic touched). markdownlint, prettier, php-cs-fixer and PHPStan max clean at the ceiling and at the dependency floor.

getAuthorizationUrl() defaults to response_type=id_token with
response_mode=query — the OIDC implicit flow, with the ID token delivered in
the query string. Callers should pass response_type=code and exchange via
getIdToken(), which is what openid-connect-bundle already does.

Two accurate reasons, since the obvious citation does not apply. OIDC Core
§3.2.2.5 returns implicit-flow parameters in the fragment, which never
reaches the server — so the query response mode exists to make the token
readable server-side, relying on a provider extension rather than anything
the spec describes. And it puts a credential in the query string, where web
server access logs and browser history keep it.

RFC 9700 §2.1.2 recommends code over response types that return tokens in the
authorization response, but its normative sentence names access tokens and
offers `code id_token` as acceptable, so it does not literally cover a bare
id_token response. The README says so rather than overstating it.

Documentation only. The default becomes code in 6.0; no runtime deprecation
notice is emitted, because it would fire on this library's own default path
and consumers could only silence it by making the change the notice asks for
— which the changelog and README ask for directly instead.
@codecov

codecov Bot commented Aug 26, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (8d137cf) to head (088b0f2).

Additional details and impacted files
@@             Coverage Diff             @@
##             develop       #63   +/-   ##
===========================================
  Coverage     100.00%   100.00%           
  Complexity        88        88           
===========================================
  Files              1         1           
  Lines            224       224           
===========================================
  Hits             224       224           
Flag Coverage Δ
unittests 100.00% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@turegjorup
turegjorup merged commit 3f7724f into develop Aug 26, 2026
18 checks passed
@turegjorup
turegjorup deleted the docs/deprecate-implicit-response-type branch August 26, 2026 11:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant