You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by ch...@apache.org on 2013/04/05 16:38:36 UTC
svn commit: r1464990 - in /felix/site/trunk/content:
documentation/subprojects/apache-felix-jaas.mdtext
site/apache-felix-jaas.data/ site/apache-felix-jaas.data/jaas-config.png
Author: chetanm
Date: Fri Apr 5 14:38:36 2013
New Revision: 1464990
URL: http://svn.apache.org/r1464990
Log:
FELIX-3980 - Add documentation related to usage of Felix JAAS Bundle
Initial draft. Work in progress
Added:
felix/site/trunk/content/documentation/subprojects/apache-felix-jaas.mdtext (with props)
felix/site/trunk/content/site/apache-felix-jaas.data/
felix/site/trunk/content/site/apache-felix-jaas.data/jaas-config.png (with props)
Added: felix/site/trunk/content/documentation/subprojects/apache-felix-jaas.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-jaas.mdtext?rev=1464990&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-jaas.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-jaas.mdtext Fri Apr 5 14:38:36 2013
@@ -0,0 +1,124 @@
+Title: Apache Felix JAAS Support
+
+<div class="note">
+Work in progress as part of FELIX-3980
+</div>
+
+Apache Felix JAAS support aims to simplify usage of JAAS in OSGi.
+
+It supports following features
+
+1. 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
+2. It enables usage of OSGi Configuration support to dynamically configure the login modules.
+3. It allows LoginModule instances to be created via factories registered in OSGi Service Registry
+4. It does not require the client to depend on any OSGi API
+5. It works well with the dynamic nature of the OSGi env
+6. 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
+
+ :::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
+
+1. 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.
+2. Instantiating a LoginModule generally requires access to internal implementation classes, by exporting these classes an implementing bundle would break its encapsulation.
+3. 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.
+
+## Making it work
+
+In order to make JAAS work under OSGi following
+
+## Usage
+The JAAS support involves following parts
+
+1. LoginContext Creation - Refers to the client code which constructs the LoginContext and then perform login operation
+2. LoginModule Registration - Mechanism by which LoginModule is registered with a given `realm`.
+
+### LoginModule registration
+
+The login modules can be registered via two mechanism
+
+* OSGi Configuration
+* LoginModuleFactory registered with the OSGi ServiceRegistry
+
+#### 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.
+
+ :::xml
+ <Jaas-ModuleClass>org.apache.felix.example.jaas.config.internal.SampleConfigLoginModule</Jaas-ModuleClass>
+
+##### OSGi 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 via "Configuration" tab of Felix WebConsole
+
+!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
+
+For an example refer to [Sample Confiuration](http://svn.apache.org/repos/asf/felix/trunk/examples/jaas/launcher/src/main/config/org.apache.felix.jaas.Configuration.factory-simple.cfg). It configures a SampleConfigLoginModule for `sample` realm
+
+#### LoginModuleFactory
+
+Any bundle which want to provide a LoginModule implementation would need to provide a factory service which implements the [LoginModuleFactory](http://svn.apache.org/repos/asf/felix/trunk/jaas/src/main/java/org/apache/felix/jaas/LoginModuleFactory.java) 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
+
+ :::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 [JdbcLoginModuleFactory](http://svn.apache.org/repos/asf/felix/trunk/examples/jaas/lm-jdbc/src/main/java/org/apache/felix/example/jaas/jdbc/JdbcLoginModuleFactory.java) for one example of its usage. It constructs a JdbcLoginModule based on the configuration and passes on the datasource.
+
+
+## Resources
+
+1. [Java JAAS Reference Guide](http://docs.oracle.com/javase/1.5.0/docs/guide/security/jaas/JAASRefGuide.html)
+2. [JAAS Login Configuration File](http://docs.oracle.com/javase/1.5.0/docs/guide/security/jaas/tutorials/LoginConfigFile.html)
\ No newline at end of file
Propchange: felix/site/trunk/content/documentation/subprojects/apache-felix-jaas.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: felix/site/trunk/content/site/apache-felix-jaas.data/jaas-config.png
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/site/apache-felix-jaas.data/jaas-config.png?rev=1464990&view=auto
==============================================================================
Binary file - no diff available.
Propchange: felix/site/trunk/content/site/apache-felix-jaas.data/jaas-config.png
------------------------------------------------------------------------------
svn:mime-type = image/png