This is an automated email from the ASF dual-hosted git repository. djencks pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/felix-antora-site.git
commit 9daa925d45310faaa1c6fecd4178c28575b05b01 Author: David Jencks <[email protected]> AuthorDate: Sun Jul 11 15:41:23 2021 -0700 remove jaas doc (unmaintained) --- modules/ROOT/pages/documentation/subprojects.adoc | 2 +- .../subprojects/apache-felix-jaas.adoc | 315 --------------------- 2 files changed, 1 insertion(+), 316 deletions(-) diff --git a/modules/ROOT/pages/documentation/subprojects.adoc b/modules/ROOT/pages/documentation/subprojects.adoc index ba582b2..a05e913 100644 --- a/modules/ROOT/pages/documentation/subprojects.adoc +++ b/modules/ROOT/pages/documentation/subprojects.adoc @@ -118,7 +118,7 @@ The last documentation may be found in the https://github.com/apache/felix-site- * https://github.com/apache/felix-site-pub/blob/last-cms/documentation/subprojects/apache-felix-commons.html[Commons] * https://github.com/apache/felix-site-pub/blob/last-cms/documentation/subprojects/apache-felix-deployment-admin.html[Deployment Admin] * https://github.com/apache/felix-site-pub/blob/last-cms/documentation/subprojects/apache-felix-ipojo.html[iPOJO] -* xref:documentation/subprojects/apache-felix-jaas.adoc[JAAS Support] +* https://github.com/apache/felix-site-pub/blob/last-cms/documentation/subprojects/apache-felix-jaas.html[JAAS Support] * xref:documentation/subprojects/apache-felix-lightweight-http-service.adoc[Lightweight HTTP Service] * xref:documentation/subprojects/apache-felix-manifest-generator-mangen.adoc[Manifest Generator (mangen)] * xref:documentation/subprojects/apache-felix-maven-obr-plugin.adoc[Maven OBR Plugin] diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-jaas.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-jaas.adoc deleted file mode 100644 index fbf628f..0000000 --- a/modules/ROOT/pages/documentation/subprojects/apache-felix-jaas.adoc +++ /dev/null @@ -1,315 +0,0 @@ -= Apache Felix JAAS Support - - - -Apache Felix JAAS support aims to simplify usage of JAAS in OSGi. - -It supports following features - -. It can work both in Standalone and AppServer deployments i.e. -in those environment where global JAAS configuration might be used by other applications and our usage of JAAS should not affect them -. It enables usage of OSGi Configuration support to dynamically configure the login modules. -. It allows LoginModule instances to be created via factories registered in OSGi Service Registry -. It does not require the client to depend on any OSGi API -. It works well with the dynamic nature of the OSGi env -. Implementation depends only on Core OSGi API and ConfigAdmin (RFC 104) - -== The Problem - -The basic problem when using JAAS in OSGi is that it creates the LoginModule instance using reflection. -This poses problem in OSGi env as the client bundle does not have the visibility of all the required LoginModule classes. - -A typical use of JAAS login looks like below - -[source,java] - // let the LoginContext instantiate a new Subject - LoginContext lc = new LoginContext("myApp"); - lc.login(); - -In this mode the `LoginContext` would access the global JAAS `Configuration` internally via `Configuration.getConfiguration()`. -It would then instantiate the LoginModule instance based on the configuration value. -It uses the Thread Context ClassLoader (TCCL) to create the instance. -This approach fails to work when used in OSGi - -. The Thread Context ClassLoader is not defined in general in an OSGi context. -It can and has to be set by the caller and OSGi cannot generally enforce that. -. Instantiating a LoginModule generally requires access to internal implementation classes, by exporting these classes an implementing bundle would break its encapsulation. -. Even if an implementation class was exported, importing this class in a consumer bundle would bind it to the specific implementation package provided, which violates the principle of loose coupling. - -== Usage - -The JAAS support involves following parts - -. LoginModule Registration - Mechanism by which LoginModule is registered with a given `realm`. -. LoginContext Creation - Refers to the client code which constructs the LoginContext and then perform login operation - -In section below we would first provide details on various ways by which a `LoginModule` would be configured so that it can participate in JAAS flow and then about various ways in which the client code can invoke the JAAS logic - -=== LoginModule registration - -The login modules can be registered via two mechanism - -* OSGi Configuration - LoginModule are registered via OSGi configuration -* LoginModuleFactory - LoginModule are registered with the OSGi ServiceRegistry via `LoginModuleFactory` - -==== A - OSGi Configuration - -LoginModules can also be configured via configuration which is somewhat similar to the file based configuration. -It consist of two parts - -* Information around which bundle provides a specific LoginModule module -* Configuration required to be passed to that LoginModule - -===== Manifest Header Entry - -Any bundle which provides a LoginModule class needs to provide this information via _Jaas-ModuleClass_ manifest header. -[source,xml] - <Jaas-ModuleClass>org.apache.felix.example.jaas.config.internal.SampleConfigLoginModule</Jaas-ModuleClass> - -===== Configuration - -JAAS module depends on OSGi Configuration for managing the LoginModule configuration. -The configuration factory PID is `org.apache.felix.jaas.Configuration.factory`.It provides the required metatype descriptor thus enabling configuration via "Configuration" tab of Felix WebConsole - -image::documentation/subprojects/jaas-config.png[] - -Configuration properties - -* `jaas.classname` - Fully qualified name of the LoginModule class -* `jaas.controlFlag` - LoginControlFlag to use like required, optional, requisite, sufficient. -Default is set to required -* `jaas.realmName` - JAAS Realm name. -If specified then LoginModule would be registered against given realm otherwise it is bound to a 'other' realm -* `jaas.ranking` - Ranking for the LoginModule. -It would be used to order the various login modules. -The entries are sorted in a descending order (i.e. -higher value ranked configurations come first) - -For an example refer to http://svn.apache.org/repos/asf/felix/trunk/examples/jaas/launcher/src/main/config/org.apache.felix.jaas.Configuration.factory-simple.cfg[Sample Configuration]. -It configures a SampleConfigLoginModule for `sample` realm - -==== B - LoginModuleFactory - -Any bundle which want to provide a LoginModule implementation would need to provide a factory service which implements the http://svn.apache.org/repos/asf/felix/trunk/jaas/src/main/java/org/apache/felix/jaas/LoginModuleFactory.java[LoginModuleFactory] interface. -The factory needs to be registeredwith following optional properties - -* `jaas.controlFlag` - LoginControlFlag to use like required, optional, requisite, sufficient. -Default is set to required -* `jaas.realmName` - JAAS Realm name. -If specified then LoginModule would be registered against given realm otherwise it is bound to a 'other' realm. -* `service.ranking` - Ranking for the LoginModule. -It would be used to order the various login modules. - -Interface - -[source,java] ----- -/** - * A factory for creating {@link LoginModule} instances. - */ -public interface LoginModuleFactory -{ - /** - * Property name specifying whether or not a <code>LoginModule</code> is - * REQUIRED, REQUISITE, SUFFICIENT or OPTIONAL. Refer to {@link javax.security.auth.login.Configuration} - * for more details around the meaning of these flags - * - * By default the value is set to REQUIRED - */ - String JAAS_CONTROL_FLAG = "jaas.controlFlag"; - - /** - * Property name specifying the Realm name (or application name) against which the - * LoginModule would be registered. - * - * <p>If no realm name is provided then LoginModule would registered with a default realm - * as configured - */ - String JAAS_REALM_NAME = "jaas.realmName"; - - /** - * Creates the LoginModule instance - * @return loginModule instance - */ - LoginModule createLoginModule(); -} ----- - -Refer to http://svn.apache.org/repos/asf/felix/trunk/examples/jaas/lm-jdbc/src/main/java/org/apache/felix/example/jaas/jdbc/JdbcLoginModuleFactory.java[JdbcLoginModuleFactory] for one example of its usage. -It constructs a JdbcLoginModule based on the configuration and passes on the datasource. - -=== LoginContext creation patterns - -There are various ways through which a JAAS Client can invoke the JAAS login. - -==== LoginContextFactory Mode - -In this mode the client logic obtains a reference to the `org.apache.felix.jaas.LoginContextFactory` service and then creates a `LoginContext` instance - - :java - LoginContextFactory loginContextFactory = ... - CallbackHandler handler = ...; - Subject subject = new Subject(); - try - { - LoginContext lc = loginContextFactory.createLoginContext("sample",subject,handler); - lc.login(); - ... - } - catch (LoginException e) - { - handleAuthenticationFailure(e); - } - -Refer to http://svn.apache.org/repos/asf/felix/trunk/examples/jaas/app/src/main/java/org/apache/felix/example/jaas/app/internal/FactoryDemoServlet.java[FactoryDemoServlet] for an example. -Following points to be noted for this usage pattern - -* Client code needs to depend on Apache Felix JAAS Support API -* No need to manage Thread Context Classloader while invoking `LoginContext` -* No need to import LoginModule related packages - -==== Configuration SPI with Default Policy Mode - -In this mode the client logic explicitly fetch the JAAS Configuration and then pass it on to the LoginContext. -In this mode the <<configuration-spi,JAAS Configuration Policy>> is set to `Default`. - -[source,java] ----- -CallbackHandler handler = ...; - -Subject subject = new Subject(); -final ClassLoader cl = Thread.currentThread().getContextClassLoader(); -try -{ - Configuration config = Configuration.getInstance( - 'JavaLoginConfig', //Algorithm name - null, //Extra params to be passed. For this impl its null - 'FelixJaasProvider' //Name of the config provider - ); - Thread.currentThread().setContextClassLoader(getClass().getClassLoader()); - LoginContext lc = new LoginContext("sample", subject, handler, config); - lc.login(); - - ... -} -finally -{ - Thread.currentThread().setContextClassLoader(cl); -} ----- - -In above flow the `Configuration` instance is explicitly fetched and passed on to the - -Refer to http://svn.apache.org/repos/asf/felix/trunk/examples/jaas/app/src/main/java/org/apache/felix/example/jaas/app/internal/TCCLDemoServlet.java[TCCLDemoServlet] for an example. -Following points to be noted for this usage pattern - -* Client code needs to be aware of the name of the config provider. -* Client bundle would need to have an import for package `org.apache.felix.jaas.boot`. -Refer to <<boot-classpath,Boot classpath>> section for more details -* Global configuration is not modified so other users of JAAS are not affected - -==== Replace Global Configuration Mode - -In this mode the JAAS bundle would replace the Global configuration through Configuration.setConfiguration call. -In this mode the client code would use the normal LoginContext creation and the <<configuration-spi,JAAS Configuration Policy>> is set to `Replace Global Configuration`. - -[source,java] ----- -final ClassLoader cl = Thread.currentThread().getContextClassLoader(); -try -{ - Thread.currentThread().setContextClassLoader(getClass().getClassLoader()); - - // let the LoginContext instantiate a new Subject - LoginContext lc = new LoginContext("appName"); - lc.login(); -} -finally -{ - Thread.currentThread().setContextClassLoader(cl); -} ----- - -Following points need to be considered this mode - -* Client code is not aware of the provider name -* Client bundle would need to have an import for package `org.apache.felix.jaas.boot`. -Refer to <<boot-classpath,Boot classpath>> section for more details -* Global configuration is modified. -So it might cause issue while running in co deployed scenarios like Application Server. - -Refer to http://svn.apache.org/repos/asf/felix/trunk/examples/jaas/app/src/main/java/org/apache/felix/example/jaas/app/internal/GlobalConfigDemoServlet.java[GlobalConfigDemoServlet] for an example - -[[boot-classpath]] -==== Modified Boot Classpath Mode - -In previous modes (except the LoginContextFactory mode) the client code needs to switch the Thread Context Classloader (TCCL). -This is due the way JAAS logic instantiates the `LoginModule`. -The Felix JAAS Support provides a `ProxyLoginModule` which takes care of routing the LoginModule calls properly. -However for this class to be visible to JAAS logic one of the two approaches can be used - -*Manage TCCL Explicitly* - -The client bundle would need to - -. Have an explicit import for `org.apache.felix.jaas.boot` package and -. Manage TCCL explicitly which making JAAS related calls. - - [source,java] - final Thread current = Thread.currentThread(); - final ClassLoader orig = current.getContextClassLoader(); - try { - current.setContextClassLoader(getClass().getClassLoader()); - loginContext = new LoginContext(appName, subject,callbackHandler, config); - } finally{ - current.setContextClassLoader(orig); - } - -Note that in above flow the TCCL is managed explicitly - -*Modify Boot Classpath* - -Another way would involve modifying the boot classpath. - -. Place the `org.apache.felix.jaas-xxx-boot.jar` in the boot classpath via `-Xbootclasspath:bootclasspath` option -. Make the `org.apache.felix.jaas.boot` part of boot delegation list - - [source,java] - LoginContext lc = new LoginContext("sample", subject, handler); - lc.login(); - -Note that in above code we do not have to manage TCCL and neither add an import to `org.apache.felix.jaas.boot` package - -Refer to http://svn.apache.org/repos/asf/felix/trunk/examples/jaas/app/src/main/java/org/apache/felix/example/jaas/app/internal/BootClasspathDemoServlet.java[BootClasspathDemoServlet] for code sample - -[[configuration-spi]] -=== JAAS Configuration SPI Settings - -There are various ways in which LoginContext can be created depending on the usage mode. -The JAAS support exposes following properties - -image::documentation/subprojects/jaas-spi-config.png[] - -* `Default JAAS Realm` - Name of the realm to use in case a LoginModule does not provide an explicit realmName. -This is useful for single application mode where all LoginModule in an OSGi container are to be used. -Usage of realm help in global settings because same config file is used to capture settings for all applications running on same JVM -* `JAAS Config Provider name` - Name against which the Configuration SPI provider should register -* `Configuration Policy` - This would be explained in next section - ** `Default` - Global configuration is not touched. -Client code are expected to use the Configuration Spi mode - ** `Replace Global Configuration` - In this the global configuration is replaced with OSGi configuration. -Client code need not perform any special configuration handling. -At most they need to switch the Thread Context Classloader - ** `Proxy Global Configuration` - Similar to previous one but it saves the default configuration and does a fallback check on that also. -This should minimize any disruption in shared mode - -== WebConsole Plugin - -The runtime JAAS realm is exposed via a WebConsole Plugin. - -image::documentation/subprojects/jaas-plugin.png[] - -== Resources - -. http://docs.oracle.com/javase/1.5.0/docs/guide/security/jaas/JAASRefGuide.html[Java JAAS Reference Guide] -. http://docs.oracle.com/javase/1.5.0/docs/guide/security/jaas/tutorials/LoginConfigFile.html[JAAS Login Configuration File]
