[shiro-site] 02/02: added principal propagaion

[lp...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

lprimak pushed a commit to branch jakarta-ee
in repository https://gitbox.apache.org/repos/asf/shiro-site.git

commit 7b4e7d4eb756fe30cb8081c6fa8408092148908b
Author: lprimak <le...@flowlogix.com>
AuthorDate: Wed Feb 8 18:43:05 2023 -0600

    added principal propagaion
---
 .gitignore                        |  1 +
 src/site/content/integration.adoc |  3 ++-
 src/site/content/jakarta-ee.adoc  | 22 +++++++++++++++++++---
 src/site/content/jaxrs.adoc       | 16 +++++++++++++++-
 4 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/.gitignore b/.gitignore
index e9534c0f7..c9f876745 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,3 +5,4 @@ output
 .project
 .settings
 cache
+.sdkmanrc
diff --git a/src/site/content/integration.adoc b/src/site/content/integration.adoc
index 8d1949e07..6735a2304 100644
--- a/src/site/content/integration.adoc
+++ b/src/site/content/integration.adoc
@@ -127,9 +127,10 @@ An open source, flexible, secure Internet of Things (IoT) development framework
 +
 from https://twitter.com/lprimak[Lenny Primak].
 +
-*Note:* Flow Logix Jakarta EE integration will be inegrated directly into Shiro with version 2.0 and above. +
 Integrates Jakarta EE / Java EE applications with Shiro Security, specifically makes Shiro Annotations work with Java EE.
 
+NOTE: This module will be inegrated directly into Shiro with version 2.0 and above.
+
 * *https://github.com/bootique/bootique-shiro[Bootique Shiro]*
 +
 from https://github.com/bootique/bootique[Bootique].
diff --git a/src/site/content/jakarta-ee.adoc b/src/site/content/jakarta-ee.adoc
index 2e5c33ba6..2d3a6846d 100644
--- a/src/site/content/jakarta-ee.adoc
+++ b/src/site/content/jakarta-ee.adoc
@@ -6,17 +6,33 @@
 :idprefix:
 :icons: font
 
+Apache Shiro Jakarta EE module makes it transparent to use Shiro features in Jakarta EE application
+with minimal configuration. It makes annotations such as `@RequiresRoles` available in Jakarta EE (CDI, EJB, etc.) code.
+
 == Dependencies
 
 Include the `shiro-jakarta-ee` dependency in you application classpath (we recomend using a tool such as Apache Maven or Gradle to manage this).
 
 ++++
-<@dependencies.dependencies anchorId="cli" deps=[{'g':'org.apache.shiro', 'a':'shiro-jakarta-ee', "v":"${versions.latestRelease}"},] />
+<@dependencies.dependencies anchorId="cli" deps=[{'g':'org.apache.shiro', 'a':'shiro-jakarta-ee', "v":"${versions.latestRelease}"}] />
 ++++
 
 == CDI
 
 == Jakarta EE
-
+=== Principal Propagation (Jakarta EE)
+By default, Shiro will propagate the Principal to `java.security.Principal`, which may not always be desidered. For example, if calling remote EJBs, the container security mechanism might interpret the principal and will error the remote EJB call as unauthenticated.
+To disable this behavior, you can put the following in your `web.xml`:
+[source,xml]
+----
+<context-param>
+    <param-name>org.apache.shiro.web.disable-principal</param-name>
+    <param-value>false</param-value>
+</context-param>
+----
 == Jax-RS
-See link:jaxrs.html[Jax-RS documentation]
+Jakarta EE module uses Jax-RS module to provide support for non-CDI and non-EJB beans. +
+See link:jaxrs.html[Jax-RS documentation] for more details.
+
+=== Principal Propagation (Jax-RS)
+Propagation is enabled or disabled for Jax-RS by the Jakarta EE module.
diff --git a/src/site/content/jaxrs.adoc b/src/site/content/jaxrs.adoc
index 7ad32cd4c..4626d2835 100644
--- a/src/site/content/jaxrs.adoc
+++ b/src/site/content/jaxrs.adoc
@@ -102,11 +102,25 @@ public class ExampleApp extends Application {
 The `ShiroFeature` does three things:
 
 * configures exception mapping from Shiro's `AuthorizationException` to HTTP status codes (401 and 403)
-* exposes Shiro's `Subject` as a `java.security.Principal`
+* exposes Shiro's `Subject` as a `java.security.Principal` (Principal Propagation - see below)
 * Configures processing of Shiro's annotations
 
 In the above example, requests to either `/api/shiro` or `/api/shiro/define` will return an HTTP status of `401` if a user is not currently logged in. A request to `/api/shiro/define` made by a user without the `hello:define` will return a `403`.
 
+=== Principal Propagation
+If calling remote EJBs, for example, the container security mechanism might interpret `java.security.Principal` and will error the remote EJB call as unauthenticated.
+If Jax-RS is used in conjunction with the link:jakarta-ee.html[Jakarta EE] module, the principal propagation is configured by Jakarta EE. However, if Jax-RS module is used standalone, principal propagation can be disabled by adding a configuration property to the map as illustrated below:
+[source,java]
+----
+@ApplicationPath("/api")
+public class JaxRsApplication extends Application {
+    @Override
+    public Map<String, Object> getProperties() {
+        return Map.of(SHIRO_WEB_JAXRS_DISABLE_PRINCIPAL_PARAM, Boolean.TRUE);
+    }
+}
+----
+
 == Want to see more?
 
 You can find portable JAX-RS application that runs with https://jersey.java.net/[Jersey], https://resteasy.dev/[RestEasy] or https://cxf.apache.org[Apache CXF] in the https://github.com/apache/shiro/tree/main/samples[samples] directory on Github.