[DOC] Clarify that disabling principal parameter also disables JSR-250 annotations

.asf.yaml

@@ -42,7 +42,7 @@ github:
           - "release/*"
         excludes: []
       bypass_teams:
-        - "release-managers"
+        - "shiro private"
       restrict_deletion: true
       restrict_force_push: true
       required_signatures: false

support/jakarta-ee/src/main/java/org/apache/shiro/ee/listeners/EnvironmentLoaderListener.java

@@ -46,6 +46,20 @@ public class EnvironmentLoaderListener extends EnvironmentLoader implements Serv
     private static final String SHIRO_EE_CHAR_ENCODING_PARAM = "org.apache.shiro.ee.character-encoding";
     private static final String FORM_RESUBMIT_DISABLED_PARAM = "org.apache.shiro.form-resubmit.disabled";
     private static final String FORM_RESUBMIT_SECURE_COOKIES = "org.apache.shiro.form-resubmit.secure-cookies";
+    /**
+     * Configuration parameter to disable the injection of the Shiro Subject/Principal.
+     *
+     * <p><strong>⚠️ WARNING: Side-Effect on JSR-250 Annotations</strong><br>
+     * Setting this parameter to {@code true} will not only disable principal injection,
+     * but it will also <em>silently disable</em> the processing of JSR-250 security
+     * annotations (such as {@code @RolesAllowed}, {@code @PermitAll}, and {@code @DenyAll}).
+     * Because JSR-250 annotations require a valid Principal to evaluate roles against,
+     * disabling the principal inherently removes the framework's ability to enforce
+     * these declarative authorization checks.
+     *
+     * <p>If your application relies on JSR-250 annotations for access control,
+     * <strong>do not</strong> enable this parameter.
+     */
     private static final String SHIRO_WEB_DISABLE_PRINCIPAL_PARAM = "org.apache.shiro.web.disable-principal";
 
     public static boolean isShiroEEDisabled(ServletContext ctx) {

support/jaxrs/src/main/java/org/apache/shiro/web/jaxrs/ShiroAnnotationFilterFeature.java

@@ -62,7 +62,7 @@ public class ShiroAnnotationFilterFeature implements DynamicFeature {
     public void configure(ResourceInfo resourceInfo, FeatureContext context) {
         List<Annotation> authzSpecs = new ArrayList<>();
         var annotations = SHIRO_ANNOTATIONS;
-        if (Boolean.TRUE.equals(context.getConfiguration().getProperty(SHIRO_WEB_JAXRS_DISABLE_PRINCIPAL_PARAM))) {
+        if (!Boolean.TRUE.equals(context.getConfiguration().getProperty(SHIRO_WEB_JAXRS_DISABLE_PRINCIPAL_PARAM))) {
             annotations = Stream.concat(SHIRO_ANNOTATIONS.stream(), JSR_250_ANNOTATIONS.stream())
                     .collect(Collectors.toList());
         }

support/jaxrs/src/main/java/org/apache/shiro/web/jaxrs/SubjectPrincipalRequestFilter.java

@@ -34,6 +34,19 @@
 @PreMatching
 public class SubjectPrincipalRequestFilter implements ContainerRequestFilter {
     @SuppressWarnings("checkstyle:JavadocVariable")
+    /**
+     * Configuration parameter to disable the injection of the Shiro Subject/Principal in JAX-RS.
+     *
+     * <p><strong>⚠️ WARNING: Side-Effect on JSR-250 Annotations</strong><br>
+     * Setting this parameter to {@code true} will also <em>silently disable</em>
+     * the processing of JSR-250 security annotations (such as {@code @RolesAllowed},
+     * {@code @PermitAll}, and {@code @DenyAll}). Because JSR-250 annotations require
+     * a valid Principal to evaluate roles against, disabling the principal inherently
+     * removes the framework's ability to enforce these declarative authorization checks.
+     *
+     * <p>If your application relies on JSR-250 annotations for access control,
+     * <strong>do not</strong> enable this parameter.
+     */
     public static final String SHIRO_WEB_JAXRS_DISABLE_PRINCIPAL_PARAM = "org.apache.shiro.web.jaxrs.disable-principal";
 
     @Override