Allen-wick opened a new pull request, #2764:
URL: https://github.com/apache/shiro/pull/2764
[DOC] Clarify that disabling principal parameter also disables JSR-250
annotations
### Description
This PR updates the Javadoc for the `disable-principal` configuration
parameters in the `shiro-jakarta-ee` and `shiro-jaxrs` modules to explicitly
document their cascading side-effects on JSR-250 security annotations.
### Context
This documentation improvement follows a private security report regarding
JSR-250 annotation processing in the `shiro-jaxrs` module. The Apache Shiro
Security Team confirmed:
1. The underlying code logic has been fixed (logic inversion bug)
2. The behavior where disabling the principal also disables JSR-250
annotations is by-design (since JSR-250 requires a valid Principal to evaluate
against)
3. The documentation was unclear about this side-effect, which could lead
developers to inadvertently create authorization gaps when tuning JAX-RS
parameters
Per the security team's recommendation, this PR adds explicit warnings to
the source code Javadoc to prevent future misconfigurations.
### Changes
1.
**support/jakarta-ee/src/main/java/org/apache/shiro/ee/listeners/EnvironmentLoaderListener.java**:
- Added WARNING Javadoc block to `SHIRO_WEB_DISABLE_PRINCIPAL_PARAM`
constant explaining that enabling this parameter silently disables JSR-250
annotations (`@RolesAllowed`, `@PermitAll`, `@DenyAll`)
2.
**support/jaxrs/src/main/java/org/apache/shiro/web/jaxrs/SubjectPrincipalRequestFilter.java**:
- Added WARNING Javadoc block to
`SHIRO_WEB_JAXRS_DISABLE_PRINCIPAL_PARAM` constant with the same clarification
### Why This Matters
- **Prevents Silent Fail-Open**: Developers who rely on JSR-250 annotations
for declarative authorization will now be explicitly warned that enabling
`disable-principal` removes this protection layer
- **IDE Visibility**: By adding the warning to Javadoc, developers using IDE
auto-completion or reading generated API docs will see the warning immediately
when configuring these parameters
- **Security Best Practice**: Aligns with the principle that
security-critical configuration side-effects should be documented at the point
of use
### Testing
- This is a documentation-only change; no functional code modifications
- Javadoc can be generated via `mvn javadoc:javadoc` to verify formatting
- No new dependencies or build steps required
### Related Issue
fixes #2763
---
**Checklist**:
- [x] GitHub issue filed: #2763
- [x] Pull request title formatted as `[DOC] - ...`
- [x] Detailed description provided
- [x] `fixes #2763` added to link to related issue
- [x] This is a trivial documentation change (javadoc comments), no `mvn
verify` required per contribution guidelines
- [x] Contribution licensed under Apache License 2.0
Thank you to the Apache Shiro Security Team for the transparent triage
process and for guiding this documentation improvement.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
