IBM FileNet P8, Version 5.2.1            

WebLogic Server

WebLogic has a security framework that uses Security Providers. Various providers are available for special jobs, such as Role Mapping Providers or Authorization Providers, but for WS-EAF, we are only interested in Authentication Providers.

An Authentication Provider is a Java™ Management Extensions (JMX) managed bean (MBean) that has a UI page or two in the WebLogic administration console for setting various login options. Each Authentication Provider has a flag for specifying OPTIONAL, REQUIRED, REQUISITE, or SUFFICIENT, as does a JAAS LoginModule. They can even be stacked in WebLogic security realms in much the same way that LoginModules can be stacked in a JAAS configuration stanza.

An Authentication Provider has an associated JAAS LoginModule, which performs the JAAS login. The rest of the Authentication Provider provides a framework that automatically digitally signs Principals that are created by its LoginModule and also has methods that validate such Principals later and that perform such tasks as identity assertion.

Implementing the Custom LoginModule

The WebLogic security framework can be divided into a WebLogic client-side API and a server-side SPI. The client-side API provides interfaces for applications to perform programmatic authentication or implement custom JAAS LoginModules. On the server side, WebLogic provides a Security Service Programming Interface (SSPI), which can be used to implement custom security providers. Viewed from the WebLogic application standpoint, WS-EAF is considered an in-container application client.

WebLogic application server supplies a default UsernamePasswordLoginModule for general client authentication with username/password credentials. For other authentication mechanisms, you typically must implement your own client LoginModule. The WebLogic API provides three important methods that are useful in developing a custom LoginModule for WS-EAF:
  • weblogic.security.auth.Authenticate.authenticate(Environment env, Subject subject)
  • weblogic.security.services.Authentication.login(CallbackHandler handler)
  • weblogic.security.services.Authentication.login(String realmName, CallbackHandler handler)

Either a thick client or an in container client, such as a servlet, can create a LoginModule implemented with theAuthenticate.authenticate method. The method takes an Environment argument that specifies an Environment map that must contain a username and a credential string. The authenticate method calls into the WebLogic Server side security run time, where the work is done by WebLogic security providers. The WebLogic security providers perform the actual authentication and return a signed valid Subject to the client application.

From the previous description of the Authenticate.authenticate method, you can see that for a typical extensible authentication implementation that uses WS-EAF, it might be of little use, as it depends on an underlying username/password authentication mechanism. However, if the custom binary security token can be decomposed into a username/password pair, and the decomposed username/password information is intended to be used in the authentication process, then a LoginModule implemented with Authenticate.authenticate is the simplest way to achieve the goal.

In most other use cases, use one of the Authentication.login methods to implement your custom LoginModule (referred to as an application LoginModule).

The following pseudocode shows what a typical custom application LoginModule must do in the initialize, login and commit methods:
public void initialize(Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options)
{
	This.callbackHandler = callbackHandler;
	this.subjectBeforeCommit = null;
	this.subject = subject;
}

public boolean login()
{
 	subjectBeforeCommit = Authentication.login(callbackHandler);
}

public boolean commit()
{
	subject.getPrincipals().addAll(subjectBeforeCommit.getPrincipals());
	subject.getPublicCredentials().addAll(
	subjectBeforeCommit.getPublicCredentials());
	subject.getPrivateCredentials().addAll(
	subjectBeforeCommit.getPrivateCredentials());
}

The callbackHandler in the previous example is the one WS-EAF creates when it initiates a standard JAAS authentication process. Notice how Authentication.login is called and the returned Subject is saved in the login method. Inside the commit method, the Principals/credentials are transferred to the current authenticating Subject.

The Authentication.login method calls into the WebLogic security framework and eventually calls the custom Authentication Provider's LoginModule implementation.

Implementing a Custom Authentication Provider

A WebLogic Authentication Provider is a JMX MBean that can be deployed from the WebLogic administration console. The WebLogic security framework also uses JAAS internally so that implementing a custom Authentication Provider involves a JAAS LoginModule implementation (referred to as the Security Provider LoginModule), as well as implementing some additional SPI interfaces that allow the custom Authentication Provider to interact with the application server. The LoginModule is the central place in which authentication occurs. So here the focus is on the LoginModule component implementation. (See Resources for links to information about the actual steps in the implementation and deployment of the custom Authentication Provider.)

The following code sample demonstrates how to use the key methods for the Authentication Provider LoginModule:
public void initialize(Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options)
{
	//This callbackHandler is the one passed by authentication.login() method.
	this.callbackHandler = callbackHandler;
	this.subject = subject;
	this.principalsForSubject = new Vector();
}

public boolean login()
{
	Callback[] callbacks = null;
	callbacks = new Callback[1];
	callbacks[0] = new TextInputCallback("WSIHEADER");
	callbackHandler.handle(callbacks);
	String wsiHeader = ((TextInputCallback)callbacks[0]).getText();
	Parse wsiHeader and retrieve the BinarySecurityToken, ValueType.
	Custom authentication using the BinarySecurityToken
	Retrieve the user and group information after authentication
	principalsForSubject.add(new WLSUserImpl(username));
	principalsForSubject.add(new WLSGroupImpl(groupName));
}

public boolean commit()
{
	subject.getPrincipals().addAll(principalsForSubject);
}

Notice inside the login method, the callbackHandler is the one passed by the Authentication.login method, and this example uses the WSIHEADER prompt to retrieve the entire WS-Security header. After the Authentication Provider finishes authentication, the Subject is passed to the WebLogic Principal Validator to sign, making it valid.

Additional Notes®

  1. The Principals created by the LoginModule must be derived from WLSPrincipal or must use the supplied WLSUserImpl or WLSGroupImpl classes so that the default PrincipalValidatorImpl works with them. You can avoid this scenario, but at the price of implementing your own PrincipalValidator class.
  2. WebLogic distinguishes between privileged users and non-privileged users. A privileged user has at least one group Principal, while a non-privileged user has none. For a nonprivileged user, WebLogic uses the default JVM user, which is the first user who logged on for that JVM. Refer to Programming WebLogic JNDI on the Oracle WebLogic website (see the Resources) for workarounds for this problem with JNDI contexts and the runAs command.
  3. WebLogic adds an extra LoginModule option, IdentityAssertion, which must be handled by any custom LoginModule. When true, the module asks for a NameCallback only (no PasswordCallback) and verifies that the name is a valid Principal at the moment.


Last updated: October 2015
ws_eaf007.htm

© Copyright IBM Corporation 2015.