Customizing an application login to perform an identity assertion by using JAAS

You can use the Java™ Authentication and Authorization Service (JAAS) login framework to create a JAAS login configuration that can be used to perform login to an identity assertion on Liberty.

About this task

By configuring identity assertion with trust validation, an application can use the JAAS login configuration to perform a programmatic identity assertion. See IdentityAssertionLoginModule for more detail.

Avoid trouble: There are several security configuration examples on the Open Liberty website for reference when configuring security for your applications on Liberty. See Configuring JAAS on Liberty by using developer tools.

1. Delegate trust validation to a user-implemented plug-in point.
   Trust validation is accomplished by a custom login module. This custom login module performs any trust validation required, then sets the trust and identity information in the shared state to be passed on to the identity assertion login module. A map is required in the following shared state key:

   com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.state

   If the state is missing then a WSLoginFailedException problem is reported by the IdentityAssertionLoginModule class.

   The map in the shared state key must include a trust key with the following key name:

   com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.trust

   If this key is set to true, then trust is established. If the key is set to false, then no trust is established and IdentityAssertionLoginModule class creates a WSLoginFailedException problem.

   The map in the shared state key must also set one of the following resources:

   • An identity key. A java.security.Principal can be set in the following key:

     com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.principal

   • A java.security.cert.X509Certificate[]. This certificate can be set in the following key:

      com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.certficates

   If both a principal and certificate are supplied, then the principal is used and a warning is reported.
2. Create a JAAS configuration for application logins.
   The JAAS configuration will contain the user-implemented trust validation custom login module and IdentityAssertionLoginModule class. Then to configure an application login configuration, add the following code in the server.xml file:

   <jaasLoginContextEntry id="CustomIdentityAssertion" name="CustomIdentityAssertion" 
                          loginModuleRef="customIdentityAssertion,identityAssertion" />
   <jaasLoginModule id="customIdentityAssertion" 
                    className="com.ibm.ws.security.authentication.IdentityAssertionLoginModule" 
                    controlFlag="REQUIRED" libraryRef="customLoginLib"/>
   	<library id="customLoginLib">
       <fileset dir="${server.config.dir}" includes="IdentityAssertionLoginModule.jar"/>      
   	</library>

   This JAAS configuration is used by the application to perform an identity assertion.
3. Perform the programmable identity assertion.
   A program can now use the JAAS login configuration to perform a programmatic identity assertion. The application program can create a login context for the JAAS configuration created in step 2, then log in to that login context with the identity that would assert to. If the login is successful then that identity can be set in the current running process. The following example illustrates this process:

   NameCallback handler = new NameCallback(new MyPrincipal("Joe"));
   LoginContext lc = new LoginContext("customIdentityAssertion", handler);
   lc.login();  //assume successful
   Subject s = lc.getSubject();
   WSSubject.setRunAsSubject(s);
   // From here on , the runas identity is "Joe"

   Note: The MyPrincipal class is the implementation of the java.security.Principal interface in the example.