[jboss-cvs] jboss-seam/doc/reference/en/modules ...

[Shane Bryzak]

  User: sbryzak2
  Date: 07/01/17 18:56:47

  Modified:    doc/reference/en/modules  security.xml
  Log:
  documented support for multiple application policies
  
  Revision  Changes    Path
  1.7       +320 -281  jboss-seam/doc/reference/en/modules/security.xml
  
  (In the diff below, changes in quantity of whitespace are not shown.)
  
  Index: security.xml
  ===================================================================
  RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/security.xml,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -b -r1.6 -r1.7
  --- security.xml	17 Jan 2007 13:46:19 -0000	1.6
  +++ security.xml	17 Jan 2007 23:56:47 -0000	1.7
  @@ -456,27 +456,51 @@
       <title>Authentication</title>
   
       <para>
  -      It is a relatively straight forward process to set up authentication.  The first step is to configure
  -      the login modules that are to be used within the project by adding a <literal>loginmodules</literal>
  -      section to <literal>security-config.xml</literal>: 
  +      It is a relatively straight forward process to set up authentication.  The first step is to 
  +      configure the login modules that are to be used within the project by adding one or more
  +      <literal>application-policy</literal> entries to <literal>security-config.xml</literal>.
       </para>
       
       <programlisting>
         <![CDATA[
  -  <loginmodules>
  -    <loginmodule class="org.jboss.seam.security.spi.SeamLoginModule" flag="required">
  -      <option name="authMethod">#{login.authenticate}</option>
  -    </loginmodule>
  -  </loginmodules>      
  +  <application-policy>
  +    <authentication>
  +      <login-module code="org.jboss.seam.security.spi.SeamLoginModule" flag="required">
  +        <module-option name="authMethod">#{login.authenticate}</module-option>
  +      </login-module>
  +    </authentication>
  +  </application-policy>  
  +      ]]>
  +    </programlisting>
  +    
  +    <para>
  +      An <literal>application-policy</literal> without a specified name will be given a default name.  It is
  +      possible to create multiple application policies if required, with each one having its own set of login 
  +      modules.
  +    </para>
  +
  +    <programlisting>
  +      <![CDATA[ 
  +  <application-policy>  <!-- default policy -->
  +    <authentication>
  +      <login-module ...
  +    </authentication>
  +  </application-policy>      
  +      
  +  <application-policy name="special">
  +    <authentication>
  +      <login-module ...
  +    </authentication>
  +  </application-policy>
         ]]>
       </programlisting>
       
       <para>
         The login module configuration should look familiar if you've ever used JAAS before.  Each login module
  -      should have its own <literal>loginmodule</literal> entry, specifying the fully qualified class name of 
  +      should have its own <literal>login-module</literal> entry, specifying the fully qualified class name of 
         the login module class, plus the flag for the login module.  It is also possible to configure additional 
  -      options for each login module, by including <literal>option</literal> entries as children of the 
  -      <literal>loginmodule</literal> entry. Flag values are found in the JSE API documentation for 
  +      options for each login module, by including <literal>module-option</literal> entries as children of the 
  +      <literal>login-module</literal> entry. Flag values are found in the JSE API documentation for 
         <literal>javax.security.auth.login.Configuration</literal>, but are repeated here for convenience:
       </para>
       
  @@ -549,7 +573,9 @@
         </tgroup>
       </table>
       
  +    <para>
       
  +    </para>    
           
       <sect2>
         <title>Using <literal>SeamLoginModule</literal> to authenticate</title>
  @@ -622,7 +648,7 @@
            CallbackHandler cbh = SeamSecurityManager.instance().createCallbackHandler(
                  user.getUsername(), user.getPassword());
            
  -         LoginContext lc = SeamSecurityManager.instance().createLoginContext(cbh);
  +         LoginContext lc = SeamSecurityManager.instance().createLoginContext(null, cbh);
            lc.login();
         }
         catch (LoginException ex)
  @@ -644,10 +670,23 @@
         <para>
           The next thing that happens is the creation of a <literal>LoginContext</literal>.  There is a factory
           method in <literal>SeamSecurityManager</literal> for creating this, as the login context doesn't
  -        use the standard configuration (it uses an application-specific configuration).  The final step is the
  -        call to <literal>lc.login()</literal>, which calls each of the configured login modules in turn, 
  -        passing in the callback handler to each one and performing an authentication based on the configured
  -        login module flags.        
  +        use the standard configuration (it uses an application-specific configuration).  If the application
  +        policy isn't configured with a name, then it will have a default name and the String parameter
  +        passed to <literal>createLoginContext()</literal> can be null.  If your application has multiple
  +        application policies configured, then you can specify which one to use by providing the policy name
  +        to <literal>createLoginContext()</literal>:
  +      </para>
  +      
  +      <programlisting>
  +        <![CDATA[
  +  LoginContext lc = SeamSecurityManager.instance().createLoginContext("special", cbh);        
  +        ]]>
  +      </programlisting>
  +        
  +      <para>
  +        The final step is the call to <literal>lc.login()</literal>, which calls each of the configured login 
  +        modules in turn,  passing in the callback handler to each one and performing an authentication based on 
  +        the configured login module flags.        
         </para>
         
         <para>