jespa.security

Class RunAs

java.lang.Object

jespa.security.RunAs

public class RunAs
extends java.lang.Object

This utility class simplifies common JAAS Subject based security model credential "bootstrapping". The JAAS security model manages credentials by associating them with the current thread. The static runAs methods of this class may be used to perform the otherwise tedious procedure of executing code in the context of a credential. Additionally, the credential may first be acquired by performing a login (in which case it will be destroyed before runAs returns).

Note that a well organized program should, in theory, only need to perform this bootstrapping procedure in one location throughout an entire program. Even an elaborate desktop application that may need to change identities at runtime can perform the credential bootstrapping process inside of a loop but very early in the application life-cycle. Once the credentials are associated with the current thread, they will be propagated throughout the program and will be accessible to any code that needs them.

All Jespa library code that needs to acquire credentials such as SecurityProvider.initSecContext(byte[], int, int) and protocol clients use the JAAS security model and thus require this credential bootstrapping process.

To be more specific, JAAS credential bootstrapping is normally performed as follows: a javax.security.auth.Subject class is created, credentials and principals are added to it, and a PrivilegedExceptionAction.run method is called through Subject.doAs (there are other permutations of this procedure but for our purposes this is a sufficient description). The following code illustrates how this credential bootstrapping method is performed explicitly:

Subject subject = new Subject();
subject.getPrivateCredentials().add(credential);
subject.getPrincipals().add(principal);
Subject.doAs(subject, action);

This class provides static runAs methods to perform the above operation but there is another more sophisticated scenario - calling a PrivilegedExceptionAction with the credentials acquired by a JAAS LoginModule.

To perform a JAAS login and then call a PrivilegedExceptionAction with the acquired credentials, code like the following would be used:

LoginContext lc = new LoginContext("AppName", TextCallbackHandler());
lc.login();
Subject.doAs(lc.getSubject(), action);

where "AppName" refers to a JAAS configuration file entry like:

AppName {
    some.auth.Module REQUIRED debug=true;
};

and that file is supplied on the commandline using the "java.security.auth.login.config" System property like:

java -Djava.security.auth.login.config=test.conf MyApp

This class provides a static runAs method to handle all of the above, without using a configuration file at all.

The following complete program illustrates how to use RunAs to perform a Kerberos login and call a PrivilegedExceptionAction that simply prints the Subject data.

import java.security.*;
import java.util.HashMap;
import javax.security.auth.*;
import jespa.security.RunAs;

public class Krb5RunAs implements PrivilegedExceptionAction {

    public Object run() throws Exception {
        System.out.println(Subject.getSubject(AccessController.getContext()));
        return null;
    }

    public static void main(String[] args) throws Exception {
        Krb5RunAs ra = new Krb5RunAs();
        HashMap options = new HashMap();
        options.put("debug", "true");
        RunAs.runAs(ra, null, "com.sun.security.auth.module.Krb5LoginModule", options, null);
    }
}

Note: Even though this elimiates the login configuration file, Sun's Kerberos LoginModuile still requires a valid krb5.conf and does not use other Jespa infrastructure like the DNS cache.

Of course the above works equally well with the "jespa.security.LoginModule". The options map is passed directoy to the SecurityProvider constructor. See the NtlmLogin.java example program.

Constructor Summary

Constructors

Constructor and Description
RunAs()

Method Summary

Modifier and Type	Method and Description
static java.lang.Object	runAs(java.security.PrivilegedExceptionAction action, java.lang.Object credential) Run the PrivilegedExceptionAction through a Subject with the supplied credential.
static java.lang.Object	runAs(java.security.PrivilegedExceptionAction action, java.lang.Object credential, java.security.Principal principal) Runs the PrivilegedExceptionAction through a Subject with the supplied credential and optional Principal.
static java.lang.Object	runAs(java.security.PrivilegedExceptionAction action, java.lang.Object credential, java.lang.String moduleName, java.util.Map options) Runs the PrivilegedExceptionAction after bootstrapping the supplied credential through the named LoginModule.
static java.lang.Object	runAs(java.security.PrivilegedExceptionAction action, java.lang.String principalName, java.lang.String moduleName, java.util.Map options, javax.security.auth.callback.CallbackHandler callbackHandler) Runs the PrivilegedExceptionAction after bootstrapping credentials through the named LoginModule.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RunAs

public RunAs()

Method Detail

runAs

public static java.lang.Object runAs(java.security.PrivilegedExceptionAction action,
                                     java.lang.Object credential,
                                     java.lang.String moduleName,
                                     java.util.Map options)
                              throws java.lang.Exception

Runs the PrivilegedExceptionAction after bootstrapping the supplied credential through the named LoginModule. If a LoginContext is created successfully, it's logoff method is called before this method returns.

This method just calls the CallbackHandler version of runAs with an interal CallbackHandler that returns the username and password of the supplied PasswordCredential.

Consider the following example which uses runAs to execute the Krb5LoginModule with a plaintext username and password:

public class RunAsKrb5 implements PrivilegedExceptionAction
{
    public Object run() throws Exception
    {   
        // Print the Subject which contains Kerberos ticket info
        System.out.println(Subject.getSubject(AccessController.getContext()));
        return null;
    }   
    public static void main(String[] args) throws Exception
    {   
        RunAsKrb5 ra = new RunAsKrb5();
        PasswordCredential credential = new PasswordCredential("alice", "moonbike69".toCharArray());
        HashMap options = new HashMap();
        options.put("debug", "true");
        RunAs.runAs(ra, credential, "com.sun.security.auth.module.Krb5LoginModule", options);
    }   
}

Callingt the Krb5LoginModule with a Plaintext Password using RunAs

Note: The Krb5LoginModule still requires a valid krb5.conf file.

Parameters:

action - the action to run (if the login is successful)

credential - the credential with which to login (currently this must be a PasswordCredential).

moduleName - the class name of the LoginModule to use (such as jespa.security.LoginModule)

options - the LoginModule options

Returns:

the return value of Subject.doAs

Throws:

java.lang.Exception - from the supplied action or if the supplied credential is not a PasswordCredential or if a login error occurs

runAs

public static java.lang.Object runAs(java.security.PrivilegedExceptionAction action,
                                     java.lang.String principalName,
                                     java.lang.String moduleName,
                                     java.util.Map options,
                                     javax.security.auth.callback.CallbackHandler callbackHandler)
                              throws java.lang.Exception

Runs the PrivilegedExceptionAction after bootstrapping credentials through the named LoginModule. If a LoginContext is created successfully, it's logoff method is called before this method returns. If no callback handler is supplied, the com.sun.security.auth.callback.TextCallbackHandler is used.

Parameters:

action - the action to run (if the login is successful)

principalName - an optional LoginModule "principal"

moduleName - the class name of the LoginModule to use (such as jespa.security.LoginModule)

options - the LoginModule options

callbackHandler - a CallbackHandler or null to use the Sun TextCallbackHandler

Returns:

the return value of Subject.doAs

Throws:

java.lang.Exception - if a login error occurs or from the supplied action

runAs

public static java.lang.Object runAs(java.security.PrivilegedExceptionAction action,
                                     java.lang.Object credential,
                                     java.security.Principal principal)
                              throws java.lang.Exception

Runs the PrivilegedExceptionAction through a Subject with the supplied credential and optional Principal.

Parameters:

action - the action to run

credential - the credential to place in the Subject

principal - an optional Principal to place in the Subject

Returns:

the return value of Subject.doAs

Throws:

java.lang.Exception - from the supplied action

runAs

public static java.lang.Object runAs(java.security.PrivilegedExceptionAction action,
                                     java.lang.Object credential)
                              throws java.lang.Exception

Run the PrivilegedExceptionAction through a Subject with the supplied credential. This method simply calls runAs(action, credential, null).

Parameters:

action - the action to run

credential - the credential to place in the Subject

Returns:

the return value of Subject.doAs

Throws:

java.lang.Exception - from the supplied action