The org.jboss.security.ClientLoginModule is an implementation of LoginModule  for use by JBoss clients for the establishment of the caller identity and credentials. This simply sets the org.jboss.security.SecurityAssociation.principal to the value of the NameCallback  filled in by the CallbackHandler , and the org.jboss.security.SecurityAssociation.credential  to the value of the PasswordCallback  filled in by the CallbackHandler . This is the only supported mechanism for a client to establish the current thread's caller. Both stand-alone client applications and server environments, acting as JBoss EJB clients where the security environment has not been configured to use JBossSX transparently, need to use the ClientLoginModule . Of course, you could always set the org.jboss.security.SecurityAssociation  information directly, but this is considered an internal API that is subject to change without notice.

Note that this login module does not perform any authentication. It merely copies the login information provided to it into the JBoss server EJB invocation layer for subsequent authentication on the server. If you need to perform client-side authentication of users you would need to configure another login module in addition to the ClientLoginModule .

The supported login module configuration options include the following:

• multi-threaded=true|false, When the multi-threaded option is set to true, each login thread has its own principal and credential storage. This is useful in client environments where multiple user identities are active in separate threads. When true, each separate thread must perform its own login. When set to false the login identity and credentials are global variables that apply to all threads in the VM. The default for this option is false.

• password-stacking=useFirstPass, When password-stacking option is set, this module first looks for a shared username and password using "javax.security.auth.login.name" and "javax.security.auth.login.password" respectively in the login module shared state Map. This allows a module configured prior to this one to establish a valid username and password that should be passed to JBoss. You would use this option if you want to perform client-side authentication of clients using some other login module such as the LdapLoginModule.

• restore-login-identity=[true|false] (since 3.2.4)

When restore-login-identity is true, the SecurityAssociation principal

and credential seen on entry to the login() method are saved and restored

on either abort or logout. When false (the default), the abort and logout

simply clear the SecurityAssociation. A restore-login-identity of true is

needed if one need to change identities and then restore the original

caller identity.

A sample login configuration for ClientLoginModule is the default configuration entry found in the JBoss distribution client/auth.conf file. The configuration is:

other {

// Put your login modules that work without jBoss here

// jBoss LoginModule

org.jboss.security.ClientLoginModule required;

// Put your login modules that need jBoss here

};

The standard server conf/login-config.xml includes a pre-configured client-login domain that can be used:

    <application-policy name = "client-login">
       <authentication>
          <login-module code = "org.jboss.security.ClientLoginModule"
             flag = "required">
             <!-- Any existing security context will be restored on logout -->
             <module-option name="restore-login-identity">true</module-option>
          </login-module>
       </authentication>
    </application-policy>

Warning

The ClientLoginModule must not be added to the login domain that performs the actual authentication within  the application server.  Doing so may result in a corrupt principal stack and at worst this could lead to users having greater privileges than intended.

Also when using the ClientLoginModule within the application server to change the current principal you must wrap this in a try / finally block and call logout on the LoginContext after the call that required the new principal has completed.  Again failure to do this could lead to a corrupt principal stack and again this could lead to users having greater privileges than intended.

Referenced by: