diff --git a/docs/reference/src/index.xml b/docs/reference/src/index.xml index 9d9cc57da1..1415d98386 100644 --- a/docs/reference/src/index.xml +++ b/docs/reference/src/index.xml @@ -887,6 +887,13 @@ This is discussed further in the CAS Single Sign On section. + + + JaasAuthenticationProvider is able to + delegate authentication requests to a JAAS + LoginModule. This is discussed further + below. + @@ -1126,6 +1133,130 @@ bean context configuration shown above. + + JAAS Authentication + + Acegi Security provides a package able to delegate + authentication requests to the Java Authentication and Authorization + Service (JAAS). This package is discussed in detail below. + + Central to JAAS operation are login configuration files. To + learn more about JAAS login configuration files, consult the JAAS + reference documentation available from Sun Microsystems. We expect you + to have a basic understanding of JAAS and its login configuration file + syntax in order to understand this section. + + + JaasAuthenticationProvider + + The JaasAuthenticationProvider attempts to + authenticate a user’s principal and credentials through JAAS. + + + Let’s assume we have a JAAS login configuration file, + /WEB-INF/login.conf, with the following + contents: + + JAASTest { + sample.SampleLoginModule required; +}; + + Like all Acegi Security beans, the + JaasAuthenticationProvider is configured via the + application context. The following definitions would correspond to + the above JAAS login configuration file: + + <bean id="jaasAuthenticationProvider" class="net.sf.acegisecurity.providers.jaas.JaasAuthenticationProvider"> + <property name="loginConfig"> + <value>/WEB-INF/login.conf</value> + </property> + <property name="loginContextName"> + <value>JAASTest</value> + </property> + <property name="callbackHandlers"> + <list> + <bean class="net.sf.acegisecurity.providers.jaas.JaasNameCallbackHandler"/> + <bean class="net.sf.acegisecurity.providers.jaas.JaasPasswordCallbackHandler"/> + </list> + </property> + <property name="authorityGranters"> + <list> + <bean class="net.sf.acegisecurity.providers.jaas.TestAuthorityGranter"/> + </list> + </property> +</bean> + + The CallbackHandlers and + AuthorityGranters are discussed below. + + + + Callbacks + + Most JAAS LoginModules require a callback + of some sort. These callbacks are usually used to obtain the + username and password from the user. In an Acegi Security + deployment, Acegi Security is responsible for this user interaction + (typically via a reference to a + ContextHolder-managed + Authentication object). The JAAS package for + Acegi Security provides two default callback handlers, + JaasNameCallbackHandler and + JaasPasswordCallbackHandler. Each of these + callback handlers implement + JaasAuthenticationCallbackHandler. In most cases + these callback handlers can simply be used without understand the + internal mechanics. For those needing full control over the callback + behavior, internally JaasAutheticationProvider + wraps these JaasAuthenticationCallbackHandlers + with an InternalCallbackHandler. The + InternalCallbackHandler is the class that + actually implements JAAS’ normal CallbackHandler + interface. Any time that the JAAS LoginModule is + used, it is passed a list of application context configured + InternalCallbackHandlers. If the + LoginModule requests a callback against the + InternalCallbackHandlers, the callback is in-turn + passed to the JaasAuthenticationCallbackHandlers + being wrapped. + + + + AuthorityGranters + + JAAS works with principals. Even “roles” are represented as + principals in JAAS. Acegi Security, on the other hand, works with + Authentication objects. Each + Authentication object contains a single + principal, and multiple GrantedAuthority[]s. To + facilitate mapping between these different concepts, the Acegi + Security JAAS package includes an + AuthorityGranter interface. An + AuthorityGranter is responsible for inspecting a + JAAS principal and returning a String. The + JaasAuthenticationProvider then creates a + JaasGrantedAuthority (which implements Acegi + Security’s GrantedAuthority interface) containing + both the AuthorityGranter-returned + String and the JAAS principal that the + AuthorityGranter was passed. The + JaasAuthenticationProvider obtains the JAAS + principals by firstly successfully authenticating the user’s + credentials using the JAAS LoginModule, and then + accessing the LoginContext it returns. A call to + LoginContext.getSubject().getPrincipals() is + made, with each resulting principal passed to each + AuthorityGranter defined against the + JaasAuthenticationProvider.setAuthorityGranters(List) + property. Acegi Security does not include any production + AuthorityGranters given every JAAS principal has + an implementation-specific meaning. However, there is a + TestAuthorityGranter in the unit tests that + demonstrates a simple AuthorityGranter + implementation. + + + Authentication Recommendations