+

Search Tips   |   Advanced Search

Security public APIs

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

The Liberty profile contains public APIs we can leverage 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 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 server.xml:

Otherwise, the methods return false. These methods are carried over from the full profile WSSecurityHelper class for compatibility.

  • 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 we 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.

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.

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.

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.

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;
        }
    }
}


Parent topic: Security