Accept multiple scopes in authorize requests and let the user grant one, PG-5168

[snake14]

Description

Spec-bound MCP clients (Claude Web, Claude Code) send every scope advertised by /.well-known/oauth-authorization-server in the authorize request, which the single-scope guard rejected outright, so no connection could be established without manually overriding the client to a single scope.

The consent screen now lists the selectable scopes as a radio group and the user grants exactly one, defaulting to the least privileged (read < write < admin < superuser). The chosen scope is re-validated server side and narrowed onto the authorization request before the code is issued, so tokens still carry exactly one scope, and it is recorded in the authorize audit activity for both allow and deny. Selectable scopes are limited to those the client may use and the signed-in user has the access level to grant, so a write-only user is never offered matomo:admin. A single selectable scope is still shown as plain text.

Also includes a hardening fix for the consent handling, tracked separately under #AS-621, kept in its own commit.

Behaviour changes worth a look during review:

• Clients with an empty scope list now fall back to the globally allowed scopes instead of being rejected, matching what ScopeRepository::finalizeScopes() already did at the token endpoint.
• When the user's access level is too low for every requested scope, the error names those scopes instead of reporting an invalid client scope mapping, which pointed at the wrong cause.
• A consent submission whose decision is neither allow nor deny is rejected instead of being treated as a denial.

Issue No

PG-5168

Steps to Replicate the Issue

1. Register an OAuth client with the authorization code grant and a redirect URI, then note its client ID.
2. Request several scopes at once: ?module=OAuth2&action=authorize&response_type=code&client_id=<clientId>&redirect_uri=<redirectUri>&scope=matomo:read%20matomo:write%20matomo:admin&state=test
3. Before this PR the request is rejected with "Invalid scope, check the scope mapped to the requested client".
4. With this PR the consent screen shows a radio group with matomo:read preselected. Allow, exchange the code, and the token carries only the chosen scope. Deny returns error=access_denied. Either way the ActivityLog entry records the selected scope.

Checklist

• [✔] Tested locally or on demo2/demo3?
• [✔] New test case added/updated?
• [✔] Are all newly added texts included via translation?
• [✔] Are text sanitized properly? (Eg use of v-text v/s v-html for vue)
• [✔] Version bumped?
• [✔] I have understood, reviewed, and tested all AI outputs before use
• [✔] All AI instructions respect security, IP, and privacy rules
• [✔] Documentation updated?

🤖 Generated with Claude Code

[snake14]

@mneudert Does this PR meet what you were trying to achieve with PG-5168?

[AltamashShaikh]

@snake14 I was testing this locally and it seems sending multiple scope, still shows only 1 scope which is mapped in the UI, its will not throw any error for Claude MCP.

Test Link

https://localhost.matomo.com/index.php?module=OAuth2&action=authorize&response_type=code&client_id=xx&redirect_uri=http://localhost.demo.com/matomoOAuth2Callback.php&scope=matomo:read%20matomo:write%20matomo:admin%20matomo:superuser&state=abc123&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256

[snake14]

@snake14 I was testing this locally and it seems sending multiple scope, still shows only 1 scope which is mapped in the UI, its will not throw any error for Claude MCP.

Thanks @AltamashShaikh . I think misunderstood the initiating request and expected the collection of scopes. It should be fixed now.

[AltamashShaikh]

Works now as expected

@snake14 Can you check this ?

Medium-risk issues

  - The branch changes the meaning of the OAuth2.authorize.decision.end payload without changing its version. In Controller.php:154, scopes is now documented and
    emitted as only the user-selected scope. Previously the event carried the request scopes. For allowed decisions that may be acceptable, but for denied decisions
    it is actively misleading: the event now reports one selected/defaulted scope even though no scope was granted and the client may have requested more. Any
    downstream plugin or audit consumer using version: v1 can silently misinterpret this.

  - The tests lock in that misleading denied-event behavior. tests/Integration/AuthorizeControllerTest.php:299 explicitly asserts that a denied multi-scope request
    records only ['matomo:read']. If the user simply clicks Deny on the default selection, the audit trail will say they denied matomo:read, not that the client
    requested matomo:read matomo:write. That weakens the branch’s own stated audit value.

  Low-risk / polish

  - The event docblock in Controller.php:141 says “the scopes that were granted” even though the same payload shape is emitted for denied decisions. That wording
    should be split between “requested”, “selected”, and “granted” semantics, or the payload should carry separate fields

[snake14]

Works now as expected

@snake14 Can you check this ?

Medium-risk issues

  - The branch changes the meaning of the OAuth2.authorize.decision.end payload without changing its version. In Controller.php:154, scopes is now documented and
    emitted as only the user-selected scope. Previously the event carried the request scopes. For allowed decisions that may be acceptable, but for denied decisions
    it is actively misleading: the event now reports one selected/defaulted scope even though no scope was granted and the client may have requested more. Any
    downstream plugin or audit consumer using version: v1 can silently misinterpret this.

  - The tests lock in that misleading denied-event behavior. tests/Integration/AuthorizeControllerTest.php:299 explicitly asserts that a denied multi-scope request
    records only ['matomo:read']. If the user simply clicks Deny on the default selection, the audit trail will say they denied matomo:read, not that the client
    requested matomo:read matomo:write. That weakens the branch’s own stated audit value.

  Low-risk / polish

  - The event docblock in Controller.php:141 says “the scopes that were granted” even though the same payload shape is emitted for denied decisions. That wording
    should be split between “requested”, “selected”, and “granted” semantics, or the payload should carry separate fields

@AltamashShaikh Agreed, and fixed. scopes keeps its previous meaning as the effective permission and now holds only the granted scope, empty when the request is denied, so a listener reading it can never act on more access than was granted. Everything the client asked for moves to a new requestedScopes, which also keeps the full request recorded on denied decisions.

AuthorizeClient::extractParams() whitelists the new key and forces scopes empty unless the decision is allowed, so the stored activity cannot report a grant that did not happen.