Include metadata scopes in WWW-Authenticate challenge

[sdelamo]

Summary

• Source the Bearer scope challenge parameter from ProtectedResourceMetadataProvider for the current request or path-specific protected-resource metadata.
• Preserve the existing resource_metadata challenge behavior and omit scope when metadata scopes are null, empty, or blank-only.
• Update protected-resource metadata and WWW-Authenticate docs for the provider-backed behavior.

Release Target

• Target branch: 5.1.x
• Release target: 5.1.0
• Micronaut organization project: 5.1.0 Release (Throw an error if multiple annotations are used. #147)

Verification

• git diff --check -- security-oauth2/src/main/java/io/micronaut/security/oauth2/metadata/ResourceMetadataWwwAuthenticateChallengeProvider.java security-oauth2/src/test/java/io/micronaut/security/oauth2/metadata/ResourceMetadataWwwAuthenticateChallengeProviderTest.java src/main/docs/guide/oauth/oauth-endpoints/protectedResourceMetadata.adoc src/main/docs/guide/rejection/wwwAuthenticate.adoc
• ./gradlew :micronaut-security-oauth2:test --tests io.micronaut.security.oauth2.metadata.ResourceMetadataWwwAuthenticateChallengeProviderTest --no-daemon --no-build-cache --rerun-tasks (7 tests, 7 successes)

PR Assets

• None. This change updates Java source, tests, and AsciiDoc source; no rendered images, PDFs, logs, archives, or generated assets changed.

Closes #2079

---

✨ This message was AI-generated using gpt-5

[Copilot]

Pull request overview

This PR enhances the OAuth2 protected-resource metadata integration by adding an optional scope parameter to the WWW-Authenticate: Bearer challenge, sourced from ProtectedResourceMetadataProvider for the current request (including path-specific metadata). It keeps the existing resource_metadata challenge parameter behavior and documents the new scope-emission behavior.

Changes:

• Add scope to the Bearer WWW-Authenticate challenge when ProtectedResourceMetadata.scopesSupported() is non-empty after trimming.
• Extend test coverage to validate scope emission and omission for null/empty/blank-only scope lists.
• Update the OAuth protected-resource metadata and WWW-Authenticate documentation to describe provider-backed scope behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
security-oauth2/src/main/java/io/micronaut/security/oauth2/metadata/ResourceMetadataWwwAuthenticateChallengeProvider.java	Adds provider-derived scope parameter emission while preserving existing resource_metadata behavior.
security-oauth2/src/test/java/io/micronaut/security/oauth2/metadata/ResourceMetadataWwwAuthenticateChallengeProviderTest.java	Adds tests for scope inclusion from path-specific metadata and omission when scopes are null/empty/blank-only.
src/main/docs/guide/oauth/oauth-endpoints/protectedResourceMetadata.adoc	Documents that the same metadata provider also drives Bearer challenge scopes.
src/main/docs/guide/rejection/wwwAuthenticate.adoc	Documents when scope will be included in the Bearer WWW-Authenticate challenge.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
88.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud