Merge pull request #6649 from eclipse/jetty-10.0.x-jetty-jaspi

Issue #6406 - backport of jetty-jaspi changes to jetty-10 (#6412)

documentation/jetty-documentation/src/main/asciidoc/old_docs/security/authentication.adoc

@@ -511,3 +511,19 @@ Below is an example which, like the one above, sets up a server with a `HashLogi
 ----
 include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/SecuredHelloHandler.java[]
 ----
+
+==== JSR 196: Java Authentication Service Provider Interface for Containers (JASPI)
+
+Jetty can utilize portable authentication modules that implements the Jakarta Authentication specification. This requires the jetty-jaspi module.
+
+Only modules conforming to the ServerAuthModule interface in the https://www.jcp.org/en/jsr/detail?id=196[JASPI Spec] are supported. These modules must be configured before start-up.
+
+The following illustrates a jetty module setting up HTTP Basic Authentication using an Authentication module that comes packaged with the jetty-jaspi module: `org.eclipse.jetty.security.jaspi.modules.BasicAuthenticationAuthModule`
+
+[source, xml, subs="{sub-order}"]
+----
+include::{SRCDIR}/jetty-jaspi/src/main/config/etc/jaspi/jaspi-demo.xml[tags=documentation]
+----
+
+Given the portability goal of Jakarta Authentication, custom or 3rd party `ServerAuthModule` implementations may be configured instead here.
+

documentation/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc

@@ -34,6 +34,7 @@ include::annotations/chapter.adoc[]
 include::jsp/chapter.adoc[]
 include::jndi/chapter.adoc[]
 include::jaas/chapter.adoc[]
+include::jaspi/chapter.adoc[]
 include::jmx/chapter.adoc[]
 include::logging/chapter.adoc[]
 include::troubleshooting/chapter.adoc[]

documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaspi/chapter.adoc

@@ -0,0 +1,68 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+// which is available at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+// ========================================================================
+//
+
+[[og-jaspi]]
+=== JASPI
+
+Enabling this module allows Jetty to utilize authentication modules that implement the JSR 196 (JASPI) specification. JASPI provides an SPI (Service Provider Interface) for pluggable, portable, and standardized authentication modules. Compatible modules are portable between servers that support the JASPI specification. This module provides a bridge from Java Authentication to the Jetty Security framework.
+
+Only modules conforming to the "Servlet Container Profile" with the ServerAuthModule interface within the https://www.jcp.org/en/jsr/detail?id=196[JASPI Spec] are supported. These modules must be configured before start-up.  Operations for runtime registering or de-registering authentication modules are not supported.
+
+[[og-jaspi-configuration]]
+==== Configuration
+
+[[og-jaspi-module]]
+===== The `jaspi` module
+
+Enable the `jaspi` module:
+
+----
+include::{JETTY_HOME}/modules/jaspi.mod[]
+----
+
+[[og-jaspi-xml]]
+===== Configure JASPI
+
+To enable the `jaspi` module you can use the following command (issued from within the `$JETTY_BASE` directory):
+
+----
+$ java -jar $JETTY_HOME/start.jar --add-modules=jaspi
+----
+
+You can then register a `AuthConfigProvider` onto the static `AuthConfigFactory` obtained with `AuthConfigFactory.getFactory()`. This registration can be done in the XML configuration file which will be copied to `$JETTY_BASE/etc/jaspi/jaspi-authmoduleconfig.xml` when the module is enabled.
+
+====== JASPI Demo
+The `jaspi-demo` module illustrates setting up HTTP Basic Authentication using a Java Authentication module that comes packaged with jetty: `org.eclipse.jetty.security.jaspi.modules.BasicAuthenticationAuthModule`, and applies it for a context named `/test`.
+
+[source, xml]
+----
+include::{JETTY_HOME}/etc/jaspi/jaspi-demo.xml[]
+----
+
+This example uses the `AuthConfigProvider` implementation provided by Jetty to register a `ServerAuthModule` directly. Other custom or 3rd party modules that are compatible with the `ServerAuthModule` interface in JASPI can be registered in the same way.
+
+===== Integration with Jetty Authentication Mechanisms
+
+To integrate with Jetty authentication mechanisms you must add a `LoginService` to your context. The `LoginService` provides a way for you to obtain a `UserIdentity` from a username and credentials. JASPI can interact with this Jetty `LoginService` by using the `PasswordValidationCallback`.
+
+The `CallerPrincipalCallback` and `GroupPrincipalCallback` do not require use of a Jetty `LoginService`. The principal from the `CallerPrincipalCallback` will be used directly with the `IdentityService` to produce a `UserIdentity`.
+
+===== Replacing the Jetty DefaultAuthConfigFactory
+
+Jetty provides an implementation of the `AuthConfigFactory` interface which is used to register `AuthConfigProviders`. This can be replaced by a custom implementation by adding a custom module which provides `auth-config-factory`.
+This custom module must reference an XML file which sets a new instance of the `AuthConfigFactory` with the static method `AuthConfigFactory.setFactory()`.
+For an example of this see the `jaspi-default-auth-config-factory` module, which provides the default implementation used by Jetty.
+
+----
+include::{JETTY_HOME}/modules/jaspi-default-auth-config-factory.mod[]
+----

jetty-jaspi/pom.xml

@@ -80,17 +80,5 @@
       <version>1.2.0</version>
       <scope>test</scope>
     </dependency>
-    <dependency>
-      <groupId>org.apache.geronimo.components</groupId>
-      <artifactId>geronimo-jaspi</artifactId>
-      <version>2.0.0</version>
-      <exclusions>
-        <exclusion>
-          <groupId>org.apache.geronimo.specs</groupId>
-          <artifactId>geronimo-jaspic_1.0_spec</artifactId>
-        </exclusion>
-      </exclusions>
-      <scope>test</scope>
-    </dependency>
   </dependencies>
 </project>

jetty-jaspi/src/main/config/etc/jaspi/jaspi-authmoduleconfig.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0"?>
+<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
+
+<Configure>
+  <Call class="javax.security.auth.message.config.AuthConfigFactory" name="getFactory">
+    <!-- Configure the AuthConfigFactory here. -->
+  </Call>
+</Configure>

jetty-jaspi/src/main/config/etc/jaspi/jaspi-default.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0"?>
+<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
+
+<Configure id="Server" class="org.eclipse.jetty.server.Server">
+
+  <!-- ===================================================================== -->
+  <!-- Configure a factory for Jaspi                                         -->
+  <!-- ===================================================================== -->
+  <Call class="javax.security.auth.message.config.AuthConfigFactory" name="setFactory">
+    <Arg>
+      <New id="jaspiAuthConfigFactory" class="org.eclipse.jetty.security.jaspi.DefaultAuthConfigFactory" />
+    </Arg>
+  </Call>
+  <Call name="addBean">
+    <Arg>
+      <Ref refid="jaspiAuthConfigFactory" />
+    </Arg>
+    <Arg type="boolean">false</Arg>
+  </Call>
+</Configure>

jetty-jaspi/src/main/config/etc/jaspi/jaspi-demo.xml

@@ -0,0 +1,48 @@
+<?xml version="1.0"?>
+<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
+
+<Configure>
+  <Call class="javax.security.auth.message.config.AuthConfigFactory" name="getFactory">
+    <Call name="registerConfigProvider">
+
+      <!-- The Jetty provided implementation of AuthConfigProvider which will wrap a ServerAuthModule. -->
+      <Arg type="String">org.eclipse.jetty.security.jaspi.provider.JaspiAuthConfigProvider</Arg>
+
+      <!-- A Map of initialization properties. -->
+      <Arg>
+        <Map>
+          <Entry>
+            <!-- Provide the fully qualified classname of the ServerAuthModule to be used. -->
+            <Item>ServerAuthModule</Item>
+            <Item>org.eclipse.jetty.security.jaspi.modules.BasicAuthenticationAuthModule</Item>
+          </Entry>
+          <Entry>
+            <!-- Realm as utilised by Jetty Security  -->
+            <Item>org.eclipse.jetty.security.jaspi.modules.RealmName</Item>
+            <Item>Test Realm</Item>
+          </Entry>
+        </Map>
+      </Arg>
+
+      <!-- Message Layer Identifier as per spec chapter 3.1  -->
+      <Arg type="String">HttpServlet</Arg>
+
+      <!-- Application Context Identifier as per spec chapter 3.2
+
+        AppContextID ::= hostname blank context-path
+        The algorithm applied here will use the
+        _serverName on the configured JaspiAuthenticatorFactory (if set) and try to match it
+        against the "server" part (in the "server /test" example below).
+        Next it will try to match the ServletContext#getVirtualServerName to the "server" part.
+        If neither are set, it will then try to match the first Subject's principal name, and finally fall back to
+        the default value "server" if none are available.
+
+        The context-path should match the context path where this applies.
+      -->
+      <Arg type="String">server /test</Arg>
+
+      <!-- A friendly description of the provided auth-module. -->
+      <Arg type="String">A simple provider using HTTP BASIC authentication.</Arg>
+    </Call>
+  </Call>
+</Configure>

jetty-jaspi/src/main/config/modules/jaspi-default-auth-config-factory.mod

@@ -0,0 +1,16 @@
+# DO NOT EDIT - See: https://www.eclipse.org/jetty/documentation/current/startup-modules.html
+
+[description]
+Provides a DefaultAuthConfigFactory for jaspi
+
+[tags]
+security
+
+[depend]
+security
+
+[provide]
+auth-config-factory
+
+[xml]
+etc/jaspi/jaspi-default.xml

jetty-jaspi/src/main/config/modules/jaspi-demo.mod

@@ -0,0 +1,16 @@
+# DO NOT EDIT - See: https://www.eclipse.org/jetty/documentation/current/startup-modules.html
+
+[description]
+Enables JASPI basic authentication the /test context path.
+
+[tags]
+security
+
+[depend]
+jaspi
+
+[xml]
+etc/jaspi/jaspi-demo.xml
+
+[files]
+basehome:etc/jaspi/jaspi-demo.xml|etc/jaspi/jaspi-demo.xml

jetty-jaspi/src/main/config/modules/jaspi.mod

@@ -3,9 +3,20 @@
 [description]
 Enables JASPI authentication for deployed web applications.
 
+[tags]
+security
+
 [depend]
 security
+auth-config-factory
 
 [lib]
 lib/jetty-jaspi-${jetty.version}.jar
 lib/jaspi/*.jar
+
+[xml]
+etc/jaspi/jaspi-authmoduleconfig.xml
+
+[files]
+basehome:etc/jaspi/jaspi-authmoduleconfig.xml|etc/jaspi/jaspi-authmoduleconfig.xml
+

jetty-jaspi/src/main/java/module-info.java

@@ -19,8 +19,9 @@
     exports org.eclipse.jetty.security.jaspi;
     exports org.eclipse.jetty.security.jaspi.callback;
     exports org.eclipse.jetty.security.jaspi.modules;
+    exports org.eclipse.jetty.security.jaspi.provider;
 
-    requires javax.security.auth.message;
+    requires transitive javax.security.auth.message;
     requires jetty.servlet.api;
     requires transitive org.eclipse.jetty.security;
     requires org.slf4j;