The transition states of the JpsStartup.start method are defined by the following constants:

• UNINITIALIZED - The state before a call to JpsStartup.start.

• INITIALIZING - The state to which it transitions after calling JpsStartup.start.

• FAILURE - The state to which it transitions if the INITIALIZING state run into any errors.

• ACTIVE - The state to which it transitions if the INITIALIZING state completed successfully.

• INACTIVE - The state to which it transitions after calling the JpsStatup.stop method.

The JpsStartup.getState method returns the current OPSS state.

The class includes the following constructor:

JpsStatup(java.lang.String platformType,
          java.util.Map<java.lang.String,ContextConfiguration>  ctxtCfgs, 
          java.util.Map<java.lang.String,?> options)

Call this constructor when you want to start OPSS with additional context details and options.

The ctxCfgs argument holds the details of the context specified in the jps-config-jse.xml file. To start contexts other than the default context, pass multiple context information. To start a context other than the default context, pass the context name. If unspecified, then it uses the default context.

The options argument groups specific OPSS startup values. For information about runtime options, see Table 24-1.

The following table describes the options you use with the jpsStartup method:

This section illustrates the use of the JpsStartup class in typical scenarios.

Example 1

The following example illustrates how to start OPSS with no explicit parameters.

JpsStartup jpsStartUp = new JpsStartup();
jpsStartUp.start();
jpsStartUp.getState();   
jpsStartUp.stop();

Example 2

The following example illustrates how to start OPSS with specific configuration values. Note that:

• default1 is the default context passed as part of the contextConfig map.

• To disable audit, set ENABLE_AUDIT_SERVICE_EXT to false. By default, it is enabled.

• To disable runtime services set ENABLE_POLICY_STORE_SERVICE_EXT to false. By default, it is enabled.

ConfigurationServiceProvider prov = ConfigurationServiceProvider.newInstance();
ConfigurationService configService = prov.getConfigurationService();
ContextConfiguration configuration = configService.getContextConfiguration("default1");
Map<String, ContextConfiguration> contextConfig = new HashMap<String, ContextConfiguration>();
contextConfig.put(JpsConstants.DEFAULT_CONTEXT_KEY, configuration);

Map<String, Object> option = new HashMap<String, Object>();
option.put(JpsConstants.ENABLE_AUDIT_SERVICE_EXT, "FALSE");
option.put(JpsConstants.ENABLE_POLICY_STORE_SERVICE_EXT, "FALSE");

JpsStartup  jpsStartUp = new JpsStartup("JSE", contextConfig, option);
jpsStartUp.start();
jpsStartUp.stop();

Example 3

The following example illustrates how to start OPSS with an additional context:

Map<String, Object> startupOption = new HashMap<String, Object>();
        
ConfigurationServiceProvider prov = ConfigurationServiceProvider.newInstance();
ConfigurationService configService = prov.getConfigurationService();
ContextConfiguration configuration = configService.getContextConfiguration("default1");

Map<String, ContextConfiguration> contextConfig = new HashMap<String, ContextConfiguration>();
contextConfig.put(JpsConstants.DEFAULT_CONTEXT_KEY, configuration);
 
JpsStartup jpsStartUp = new JpsStartup("JSE", contextConfig, startupOption);
jpsStartUp.start();
jpsStartUp.stop();

Example 4

The following example illustrates how to start OPSS with multiple contexts. It assumes that the jps.config-jse.xml file includes the contexts:

<jpsContexts default="default">
 <jpsContext name="default">
  <serviceInstanceRef ref="credstore"/> ...
 </jpsContext>

 <jpsContext name="default1">
  <serviceInstanceRef ref="idstore.loginmodule"/> ...
 </jpsContext>

 <jpsContext name="default2">
  <serviceInstanceRef ref="keystore"/> ...
 </jpsContext>

 <jpsContext name="default3">
  <serviceInstanceRef ref="policystore "/> ...
 </jpsContext>

 <jpsContext name="bootstrap_credstore_context">
  <serviceInstanceRef ref="bootstrap.credstore"/>
 </jpsContext>
</jpsContexts>

ConfigurationServiceProvider prov = ConfigurationServiceProvider.newInstance();
ConfigurationService configService = prov.getConfigurationService();
ContextConfiguration configuration1 = configService.getContextConfiguration("default1");
ContextConfiguration configuration2 = configService.getContextConfiguration("default2");
ContextConfiguration configuration3 = configService.getContextConfiguration("default3");
 
Map<String, ContextConfiguration> contextConfig = new HashMap<String, ContextConfiguration>();
 
contextConfig.put(JpsConstants.DEFAULT_CONTEXT_KEY, configuration);
contextConfig.put(("default1", configuration1);
contextConfig.put(("default2", configuration2);
contextConfig.put(("default3", configuration3);
 
Map<String, Object> startupOption = new HashMap<String, Object>();
startupOption.put(JpsConstants.ACTIVE_CONTEXT, "default");
 
JpsStartup jpsStartUp = new JpsStartup("JSE", contextConfig, startupOption);
jpsStartUp.start();
jpsStartUp.stop();

The ACTIVE_CONTEXT parameter specifies the context to use as default. If DEFAULT_CONTEXT_KEY is not passed as part of map, then the default context is started provided there is no ACTIVE_CONTEXT key passed as part of startupOption map.

Example 5

The following example illustrates how to start OPSS in the SCRIPT mode. This mode is used when you do not want runtime services started.

Map<String, Object> startupOption = new HashMap<String, Object>();
startupOption.put(JpsConstants.RUNTIME_MODE, "SCRIPT");        
 
JpsStartup jpsStartUp = new JpsStartup("JSE", startupOption);
jpsStartUp.start();
jpsStartUp.stop();

Provisioning the jpsPermission

The following example illustrates a grant allowing the jdoe principal permission to execute the User Assertion login module:

<grant>
  <grantee>
    <principals>
      <principal>
        <class>weblogic.security.principal.WLSUserImpl</class>
        <name>jdoe</name>
      </principal>
    </principals>
  </grantee>
  <permissions>
    <permission>
      <class>oracle.security.jps.JpsPermission</class>
      <name>IdentityAssertion</name>
      <action>execute</action>
    </permission>
  </permissions>
</grant>

Implementing the CallbackHandler

The following example illustrates an implementation of the callback handler:

import oracle.security.jps.callback.IdentityCallback;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
import java.io.IOException;
    public class AssertCallbackHandler implements CallbackHandler {
        private String name = null;
        public AssertCallbackHandler(String name) {
            this.name = name;
        }
        public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
            for (Callback callback : callbacks) {
                if (callback instanceof IdentityCallback) {
                    IdentityCallback nc = (IdentityCallback) callback;
                    nc.setIdentity(name);
                }
                else {
                    throw new UnsupportedCallbackException(callback);
                }
            }
        }
    }

Implementing the Programmatic Assertion

The following example illustrates how to assert a user:

import oracle.security.jps.callback.IdentityCallback;
import oracle.security.jps.internal.api.jaas.module.JpsLoginModuleFactory;
import oracle.security.jps.internal.api.jaas.module.JpsLoginModuleType;
import javax.security.auth.Subject;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
import javax.security.auth.login.LoginContext;
import java.io.IOException;
import java.security.AccessController;
import java.security.PrivilegedActionException;
import java.security.PrivilegedExceptionAction;
        Subject subject = AccessController.doPrivileged(new PrivilegedExceptionAction<Subject>() {
            public Subject run() throws Exception {
                JpsLoginModuleFactory f = JpsLoginModuleFactory.getLoginModuleFactory();
                CallbackHandler cbh = new AssertCallbackHandler(name);
                LoginContext c = f.getLoginContext(JpsLoginModuleType.USER_ASSERTION, null, cbh);
                c.login();
                return c.getSubject();
            }
        });

Using the Identity Store Login Module for Authentication

This section describes the use of the Identity Store login module for basic user name and password authentication.

The following example illustrates how to configure the appName context:

<jpsContext name="appName">
   <serviceInstanceRef ref="jaaslm.idstore1"/>
</jpsContext>

<serviceProvider type="JAAS_LM" name="jaaslm.idstore" 
      class="oracle.security.jps.internal.jaas.module.idstore.IdStoreLoginModule">
   <description>Identity Store-based LoginModule
   </description>
</serviceProvider>

<serviceInstance name="jaaslm.idstore1" provider="jaaslm.idstore">
   <property name="jaas.login.controlFlag" value="REQUIRED"/>
   <property name="debug" value="true"/>
   <property name="addAllRoles" value="true"/>
</serviceInstance>

The following example illustrates a callback that handles the name and password:

import javax.security.auth.Subject;
import javax.security.auth.login.LoginContext;
import javax.security.auth.callback.*;
import java.io.IOException; 
Subject sub = new Subject();
CallbackHandler cbh = new YourCallbackHandler();
LoginContext context = new LoginContext(appName, subject,  cbh);
context.login();

public class SampleCallbackHandler implements CallbackHandler {
//For name/password callbacks
private String name = null;private char[] password = null; 
public SampleCallbackHandler(String name, char[] pwd) { 
   if (name == null || name.length() == 0 )         
      throw new IllegalArgumentException("Invalid name ");
   else 
      this.name = name; 
   if (pwd == null || pwd.length == 0)
      throw new IllegalArgumentException("Invalid password ");
   else
      this.password = pwd;
}
public String getName() {
   return name;
   } public char[] getPassword()  {
   return password;
 }    
public void handle(Callback[] callbacks) 
   throws IOException, UnsupportedCallbackException {
   if (callbacks != null && callbacks.length > 0) {
      for (Callback c : callbacks) {
      if (c instanceof NameCallback) {
            ((NameCallback) c).setName(name);
            } 
   else 
      if (c instanceof PasswordCallback) {
         ((PasswordCallback) c).setPassword(password);
              }           
   else {
      throw new UnsupportedCallbackException(c);
 }
          }
      }
  }
}

Using the Identity Store Login Module for Assertion

To use the Identity Store login module for assertion, provide a permission to execute the protected setIdentity method, and implement the callback handler that uses the oracle.security.jps.callback.IdentityCallback class.

The following example illustrates a configuration that allows the MyApp application permission to execute protected methods in the assertion login module:

<grant>
  <grantee>
    <codesource>
      <url>file:${soa.oracle.home}/application/myApp.ear</url>
		      <--! soa.oracle.home is a system property set when 
      the server JVM is started -->
    </codesource>
  </grantee>
  <permissions>
    <permission>
      <class>oracle.security.jps.JpsPermission</class>
      <name>IdentityAssertion</name>
    </permission>t
  </permissions>
</grant>

The following example illustrates the configuration that allows the jdoe user permission to execute the assertion login module:

<grant>
  <grantee>
    <principals>
      <principal>
        <class>weblogic.security.principal.WLSUserImpl</class>
        <name>jdoe</name>
      </principal>
    </principals>
  </grantee>
  <permissions>
    <permission>
      <class>oracle.security.jps.JpsPermission</class>
      <name>IdentityAssertion</name>
    </permission>
  </permissions>
</grant>

The following example illustrates an implementation of the callback handler:

import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.NameCallback;
import javax.security.auth.callback.PasswordCallback;
import javax.security.auth.callback.UnsupportedCallbackException;
import oracle.security.jps.callback.IdentityCallback;
public class CustomCallbackHandler implements CallbackHandler {
    private String name = null;
    private char[] password;
    public CustomCallbackHandler(String name) {
        this.name = name;
    }
    public CustomCallbackHandler(String name, char[] password) {
      this.name  = name;
      this.password = password;
    }
    public void handle(Callback[] callbacks) throws IOException,
                                                    UnsupportedCallbackException {
        for (Callback callback : callbacks) {
            if (callback instanceof NameCallback) {
              NameCallback nc = (NameCallback) callback;
              nc.setName(name);
            }
            else if (callback instanceof PasswordCallback) {
              PasswordCallback pc = (PasswordCallback) callback;
              pc.setPassword(password);
            }
            else if (callback instanceof IdentityCallback) {
                IdentityCallback idcb = (IdentityCallback)callback;
                idcb.setIdentity(name);
                idcb.setIdentityAsserted(true);
                idcb.setAuthenticationType("CUSTOM");
            } else {
                //throw exception
                throw new UnsupportedCallbackException(callback);
            }
        }
    }
}

The following example illustrates the implementation of a login module:

import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.login.LoginContext;
 
import oracle.security.jps.service.JpsServiceLocator;
import oracle.security.jps.service.login.LoginService;
 
public class LoginModuleExample {
    private static final String CONTEXT_NAME = "JSE_UserAuthnAssertion";
 
    public LoginModuleExample() {
        super();
    }
 
    public Subject assertUser(final String username) throws Exception {
        CallbackHandler cbh =
            AccessController.doPrivileged(new PrivilegedExceptionAction<CallbackHandler>() {
                public CallbackHandler run() throws Exception {
                    return new CustomCallbackHandler(username);
                }
            });
        Subject sub = new Subject();
        LoginService ls =
            JpsServiceLocator.getServiceLocator().lookup(LoginService.class);
        LoginContext context = ls.getLoginContext(sub, cbh);
 
        context.login();
        Subject s = context.getSubject();
 
        return s;
    }
 
    public Subject authenticate(final String username, final char[] password) throws Exception {
        CallbackHandler cbh = new CustomCallbackHandler(username, password);
        Subject sub = new Subject();
        LoginService ls =
            JpsServiceLocator.getServiceLocator().lookup(LoginService.class);
        LoginContext context = ls.getLoginContext(sub, cbh);
 
        context.login();
        Subject s = context.getSubject();
 
        return s;
    }
 
    public static void main(String[] args) {
        LoginModuleExample loginModuleExample = new LoginModuleExample();
        try {
            System.out.println("authenticated user subject = " + 
                               loginModuleExample.authenticate("testUser", 
 "password".toCharArray()));
            System.out.println("asserted user subject = " +
                               loginModuleExample.assertUser("testUser"));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

The SubjectSecurity Class

Here are several scenarios where you use this class:

• UC1 - A scheduler allows submitting and executing jobs. These jobs are submitted at one time and executed at some future time, therefore the need to assert the user's identity and execute the scheduled job in the user's context.

• UC2 - A scheduled job is executed by an entity bean that calls other entity beans to complete the job, and all the code to complete the job must execute in the user's context. Therefore this context must be propagated through the call path, across entity beans.

• UC3 - The permissions to execute a scheduled job are based on the user's application roles. In this case, the user's context must be aware of the application roles granted to the user regardless of the code path across entity beans.

• UC4 - When an unauthenticated user submits a job, the job metadata must persist the anonymous user. Eventually, the job must be executed by the anonymous user.

• UC5 - An MBean running in an application is called from a UI via an MBean server. The MBean operation call a series of diagnostic tests that must be run as a particular user.

• UC6 - An identity has been asserted and the assertion has produced a user context that can be used to run operations as that user.

Programming Guidelines and Recommendations

The SubjectSecurity class allows you to execute code either when a precomputed subject is available, or when the user must first be asserted. If the application context has not been set, then before you use the SubjectSecurity class, set its ID:

AppSecurityContext.setApplicationID(applicationID)

If you have set the application context, then the call to setApplicationID is optional.

When programming with the SubjectSecurity class:

• Use SubjectSecurity.getActionExecutor(subject) if you have already obtained a subject and want to execute some operation with it.

  • If you obtained the subject with the SubjectUtil.getCurrentSubject method, then that subject works with the container security and OPSS, and application roles are considered.

  • If you obtained the subject programmatically using the JpsLoginModuleFactory class, then that subject works with the container security and OPSS.

• Use SubjectSecurity.getActionExecutor(userName) if just the user name is available and want to execute some operation as that user. To use this method, provide a codesource permission like the following:

  <grant>
      <grantee>
          <codesource>
             <url>file:${domain.home}/servers/${weblogic.Name}/myApp.ear/-</url>
          </codesource>
      </grantee>
      <permissions>
          <permission>
              <class>oracle.security.jps.JpsPermission</class>
              <name>IdentityAssertion</name>
              <actions>execute</actions>
          </permission>
      </permissions>
  </grant>
  

  where url specifies the location of the code where the method is called.

• Note that ActionExecutor.execute(PrivilegedAction) calls Subject.doAs with the subject and the application's PrivilegedAction.

• Use SubjectSecurity.executeAs(Subject subject, PrivilegedAction<T> action) to execute the action immediately.

• Use SubjectSecurity.executeAs(Subject subject, PrivilegedExceptionAction<T> action) to execute the action immediately. This method obtains the action executor using the getActionExecutor method, and executes the action.

For information about the oracle.security.jps.runtime.SubjectSecurity class and the oracle.security.jps.runtime.ActionExecutor interface, see Java API Reference for Oracle Platform Security Services.

Using SubjectSecurity

The following example illustrates how to use the SubjectSecurity class to run as the asserted jdoe user:

// get a SubjectSecurity instance
        final SubjectSecurity subjectSecurity = SubjectSecurity.getInstance();
        String username = "jdoe";
// create ActionExecutor with subjectSecurity getActionExecutor(String username)
        ActionExecutor executor =
        AccessController.doPrivileged(new PrivilegedExceptionAction<ActionExecutor>() {
            public ActionExecutor run() throws AssertionException {
                    return subjectSecurity.getActionExecutor(username);
            }
        }, null);
// When OPSS subjects are available,
// create ActionExecutor with SubjectSecurity getActionExecutor(Subject subject)
        Subject opssSubject = SubjectUtil.getCurrentSubject();
        ActionExecutor ececutor = subjectSecurity.getActionExecutor(opssSubject);
 //run privilegedAction
        PrivilegedAction action = new MyPrivilegedAction();
        executor.execute(action);
 //run PrivilegedExceptionAction
        PrivilegedExceptionAction exceptionAction = new MyPrivilegedExceptionAction();
        try {
            executor.execute(exceptionAction);
        } catch (PrivilegedActionException e) {
            // handle PrivilegedActionException
        }

To set audit in your the domain:

The following task assumes that a middleware home is available but no WebLogic Server is running, so neither Fusion Middleware Control nor the setAuditRepository WLST command is available.

To set up audit in this case: