Liberty profile: Security public APIs

Security public APIs in the Liberty profile provides a way of extending the security infrastructure.

The Liberty profile contains public APIs that you can use to implement security functions. The security public APIs in the Liberty profile are a subset of the full profile security public APIs. The main classes are WSSecurityHelper, WSSubject, and RegistryHelper. These classes contain a subset of the methods that are available in the full profile versions. There is also a new class WebSecurityHelper.

The following sections describe those main classes. There are also other classes such as UserRegistry, WSCredential, and other exception classes.

All the security public APIs supported by the Liberty profile are in the Java™ API documentation. The Java API documentation for each Liberty profile API is detailed in the Programming Interfaces (APIs) section of the information center, and is also available as a separate .zip file in one of the javadoc subdirectories of the ${wlp.install.dir}/dev directory.

WSSecurityHelper
This class contains only the methods isServerSecurityEnabled() and isGlobalSecurityEnabled(). They both return true if either of the following features are enabled in the server.xml file:
  • appSecurity-2.0
  • zosSecurity-1.0
Otherwise, the methods return false. These methods are carried over from the full profile WSSecurityHelper class for compatibility.
Note:
  • There are no cells in the Liberty profile, so there is no distinction in the Liberty profile between global security and server security. Therefore both methods return the same value.
  • The method revokeSSOCookies(javax.servlet.http.HttpServletRequest req,javax.servlet.http.HttpServletResponse res) is not supported in the Liberty profile. Instead you can use the Servlet 3.0 logout function.
  • The method getLTPACookieFromSSOToken() has been renamed to a new public API class: WebSecurityHelper.
WSSubject
This class provides utility methods for querying and setting the security thread context. All methods from the full profile WSSubject are supported in the Liberty profile.
Note: Java 2 security is not enabled in the Liberty profile, so the Java 2 security checks in WSSubject are not performed.
RegistryHelper
This class provides access to the UserRegistry object and trusted realm information. In the Liberty profile, it contains the following subset of the full profile methods:
public static UserRegistry getUserRegistry(String realmName) throws WSSecurityException
public static List<String> getInboundTrustedRealms(String realmName) throws WSSecurityException
public static boolean isRealmInboundTrusted(String inboundRealm, String localRealm)
WebSecurityHelper
This class contains the renamed getLTPACookieFromSSOToken() method, which was moved from WSSecurityHelper:
public static Cookie getLTPACookieFromSSOToken() throws Exception

Security public API code examples

The following examples demonstrate how to use security public APIs in the Liberty profile to do a programmatic login and operate on the Subject.
Example 1: Create a Subject and use it for authorization
This example demonstrates how to use WSSecurityHelper, WSSubject, and UserRegistry to do a programmatic login to create a Java Subject, then perform an action and use that Subject for any authorization that is required.
Note: The following code uses WSSecurityHelper to check if security is enabled before doing further security processing. This check is used extensively because of the modular nature of the Liberty profile: If security is not enabled then the security run time is not loaded. WSSecurityHelper is always loaded, even if security is not enabled.
import java.rmi.RemoteException;
import java.security.PrivilegedAction;

import javax.security.auth.Subject;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.login.LoginContext;
import javax.security.auth.login.LoginException;

import com.ibm.websphere.security.CustomRegistryException;
import com.ibm.websphere.security.UserRegistry;
import com.ibm.websphere.security.WSSecurityException;
import com.ibm.websphere.security.WSSecurityHelper;
import com.ibm.websphere.security.auth.WSSubject;
import com.ibm.websphere.security.auth.callback.WSCallbackHandlerImpl;
import com.ibm.wsspi.security.registry.RegistryHelper;
public class myServlet {

	...
	if (WSSecurityHelper.isServerSecurityEnabled()) {
		UserRegistry ur = null;
		try {
			ur = RegistryHelper.getUserRegistry(null);
		} catch (WSSecurityException e1) {
			// record some diagnostic info
			return;
		}
		String userid = "user1";
		String password = "user1password";
		try {
			if (ur.isValidUser(userid)) {
				// create a Subject, authenticating with
				// a userid and password
				CallbackHandler wscbh = new WSCallbackHandlerImpl(userid, password);
				LoginContext ctx;
				ctx = new LoginContext("WSLogin", wscbh);
				ctx.login();
				Subject subject = ctx.getSubject();
				// Perform an action using the Subject for
				// any required authorization
				WSSubject.doAs(subject, action);
			}
		} catch (CustomRegistryException e) {
			// record some diagnostic info
			return;
		} catch (RemoteException e) {
			// record some diagnostic info
			return;
		} catch (LoginException e) {
			// record some diagnostic info
			return;
		}
	}
	...
	private final PrivilegedAction action = new PrivilegedAction() {
		@Override
		public Object run() {
			// do something useful here
			return null;
		}
	};

}
Example 2: Create a Subject and make it the current Subject on the thread
The following example demonstrates how to use WSSecurityHelper and WSSubject to do a programmatic login to create a Java Subject, make that Subject the current Subject on the thread, and finally restore the original security thread context.
Note: The following code uses WSSecurityHelper to check if security is enabled before doing further security processing.
import javax.security.auth.Subject;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.login.LoginContext;
import javax.security.auth.login.LoginException;

import com.ibm.websphere.security.WSSecurityException;
import com.ibm.websphere.security.WSSecurityHelper;
import com.ibm.websphere.security.auth.WSSubject;
import com.ibm.websphere.security.auth.callback.WSCallbackHandlerImpl;
...
if (WSSecurityHelper.isServerSecurityEnabled()) {
	CallbackHandler wscbh = new WSCallbackHandlerImpl("user1", "user1password");
	LoginContext ctx;
	try {
		// create a Subject, authenticating with
		// a userid and password
		ctx = new LoginContext("WSLogin", wscbh);
		ctx.login();
		Subject mySubject = ctx.getSubject();
		Subject oldSubject = null;
		try {
			// Save a ref to the current Subject on the thread
			oldSubject = WSSubject.getRunAsSubject();
			// Make mySubject the current Subject on the thread
			WSSubject.setRunAsSubject(mySubject);
			// Do something useful here. Any authorization
			// required will be performed using mySubject
		} catch (WSSecurityException e) {
			// record some diagnostic info
			return;
		} finally {
			// Put the original Subject back on the thread context
			if (oldSubject != null) {
				try {
					WSSubject.setRunAsSubject(oldSubject);
				} catch (WSSecurityException e) {
					// record some diagnostic info 
				}
			}
		}
	} catch (LoginException e) {
		// record some diagnostic info
		return;
	}
}
Example 3: Get information of the current Subject on the thread
The following example demonstrates how to use WSSecurityHelper, WSSubject, and WSCredential to get information about the current Subject on the thread.
Note: The following code uses WSSecurityHelper to check if security is enabled before doing further security processing.
import java.util.ArrayList;
import java.util.Iterator;
import java.util.Set;

import javax.security.auth.Subject;
import javax.security.auth.login.CredentialExpiredException;

import com.ibm.websphere.security.WSSecurityException;
import com.ibm.websphere.security.WSSecurityHelper;
import com.ibm.websphere.security.auth.CredentialDestroyedException;
import com.ibm.websphere.security.auth.WSSubject;
import com.ibm.websphere.security.cred.WSCredential;
...
if (WSSecurityHelper.isServerSecurityEnabled()) {
	// Get the caller's subject
	Subject callerSubject;
	try {
		callerSubject = WSSubject.getCallerSubject();
	} catch (WSSecurityException e) {
		// record some diagnostic info
		return;
	}
	WSCredential wsCred = null;
	Set<WSCredential> wsCredentials =
		callerSubject.getPublicCredentials(WSCredential.class);
	Iterator<WSCredential> wsCredentialsIterator = wsCredentials.iterator();
	if (wsCredentialsIterator.hasNext()) {
		wsCred = wsCredentialsIterator.next();
		try {
			// Print out the groups
			ArrayList<String> groups = wsCred.getGroupIds();
			for (String group : groups) {
				System.out.println("Group name: " + group);
			}
		} catch (CredentialExpiredException e) {
			// record some diagnostic info
			return;
		} catch (CredentialDestroyedException e) {
			// record some diagnostic info
			return;
		}
	}
}
}

Icon that indicates the type of topic Reference topic

Terms and conditions for information centers | Feedback


Timestamp icon Last updated: Monday, 21 April 2014
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-express-iseries&topic=rwlp_sec_apis
File name: rwlp_sec_apis.html