23 Configuring Jakarta EE Applications to Use OPSS

This chapter describes the configuration and packaging recommended for Jakarta EE applications that use OPSS but do not use Oracle Application Development Framework (Oracle ADF) security.

The following security-related files are relevant in a Jakarta EE application during development, deployment, and runtime:

• DOMAIN_HOME/config/fmwconfig/jps-config.xml

• DOMAIN_HOME/config/fmwconfig/system-jazn-data.xml

• jazn-data.xml (packaged in the application Enterprise ARchive (EAR) file)

• cwallet.sso (packaged in the application EAR file)

• web.xml (packaged in the application EAR file)

• weblogic-application.xml (packaged in the application EAR file)

See also:

Configuring Java SE Applications to Use OPSS

Developing Oracle ADF Applications

Securing Oracle ADF Applications

OPSS API References

• About Authentication in Jakarta EE Applications
  
• Developing Authentication in Jakarta EE Applications
  
• Configuring the Filter and the Interceptor
  
• Choosing the Appropriate Class for Enterprise Groups and Users
  
• Packaging a Jakarta EE Application Manually
  
• Configuring Jakarta EE Applications to Use OPSS
  

About Authentication in Jakarta EE Applications

The following topics contain information about developing authentication in Jakarta EE applications:

• Authentication in Understanding Security for Oracle WebLogic Server.

• Developing Applications with the WebLogic Security Service:

  • Securing Web Applications

  • Using JAAS Authentication in Java Clients

  • Using SSL Authentication in Java Clients

• Developing Security Providers for Oracle WebLogic Server:

  • Authentication Providers

  • Login Modules

  • How to Develop a Custom Authentication Provider

  • Identity Assertion Providers

  • Servlet Authentication Filters

Developing Authentication in Jakarta EE Applications

The OPSS login modules support programmatic user authentication and assertion in Jakarta EE and SE applications, and the API you use to call these login modules is common to both Jakarta EE and SE applications. Oracle WebLogic Server delegates user authentication and assertion to WebLogic Server security providers.

See also:

Authentication Providers in Developing Security Providers for Oracle WebLogic Server

Using Login Modules in Java Applications

Configuring the Filter and the Interceptor

The configurations explained in this section are required only if you are packaging or configuring your Jakarta EE application (integrated with OPSS) outside Oracle JDeveloper.

OPSS provides the JpsFilter filter for Java servlets and the JpsInterceptor interceptor for Jakarta Enterprise Beans (EJBs). The filter is configured in the web.xml file packed in a web application archive (WAR) file. The interceptor is configured in the ejb-jar.xml file packed in a JAR file.

OPSS also provides a way to configure the stripe that application MBeans access, in the web.xml file.

Ready-to-use, the filter is set with the default parameter values so you need not configure it in the deployment descriptor. However, you must configure it manually if a value different from the default value is required. The interceptor must be manually configured.

The parameters you use to configure the filter and the interceptor are explained in the following sections:

See also:

About the Anonymous User and Role

About the Authenticated Role

Interceptor Configuration Requirements

Summary of Filter and Interceptor Parameters

• Setting the Application Stripe
  
• Setting Application Role Support
  
• Setting the Anonymous User and Role
  
• Setting Authenticated Role Support
  
• Setting JAAS Mode
  
• Interceptor Configuration Requirements
  
• Summary of Filter and Interceptor Parameters
  

Setting the Application Stripe

The application stripe is optionally specified in the application web.xml file, and it is used at runtime to determine which set of policies are applicable. If unspecified, it defaults to the application ID (which includes the application name).

To set the application stripe, use the application.name parameter. This setting is optional and case-sensitive. If unspecified, it defaults to the name of the application.

To specify the application stripe, configure either the filter or the context-param elements in web.xml:

<filter>
 <filter-name>JpsFilter</filter-name>
 <filter-class>oracle.security.jps.ee.http.JpsFilter</filter-class>
 <init-param>
  <param-name>application.name</param-name>
  <param-value>stripeid</param-value>
 </init-param>
</filter>

<context-param>
 <description>JPS custom stripe id</description>
 <param-name>application.name</param-name>
 <param-value>stripeid</param-value>
</context-param>

If your application contains application MBeans that access the security store and your the name of your application is different from the name of the stripe they access, then you must use the context-param configuration like the previous one to specify the stripe name.

Additional Examples

The following example illustrates the configuration of the MyServlet1 and MyServlet2 servlets in web.xml. Note that servlets in the same WAR file use the same policy stripe.

<filter>
   <filter-name>JpsFilter</filter-name>
   <filter-class>oracle.security.jps.ee.http.JpsFilter</filter-class>
   <init-param>
      <param-name>application.name</param-name>
      <param-value>MyAppName</param-value>
   </init-param>
</filter>
<filter-mapping>
   <filter-name>JpsFilter</filter-name>
   <servlet-name>MyServlet1</servlet-name>
   <dispatcher>REQUEST</dispatcher>
</filter-mapping>
<filter-mapping>
   <filter-name>JpsFilter</filter-name>
   <servlet-name>MyServlet2</servlet-name>
   <dispatcher>REQUEST</dispatcher>
</filter-mapping>

The following example illustrates the configuration of the MyAppName application stripe and the JpsInterceptor interceptor in the ejb-jar.xml file, and the binding of that interceptor to MyEjb:

<interceptor>
  <interceptor-class>oracle.security.jps.ee.ejb.JpsInterceptor</interceptor-class>
  <env-entry>
     <env-entry-name>application.name</env-entry-name>
     <env-entry-type>java.lang.String</env-entry-type>
     <env-entry-value>MyAppName</env-entry-value>
     <injection-target>
       <injection-target-class>
         oracle.security.jps.ee.ejb.JpsInterceptor</injection-target-class>
       <injection-target-name>application_name</injection-target-name>
     </injection-target>
  </env-entry>
</interceptor>
...
<interceptor-binding>
   <ejb-name>MyEjb</ejb-name>
   <interceptor-class>
     oracle.security.jps.ee.ejb.JpsInterceptor</interceptor-class>
</interceptor-binding>.

Setting Application Role Support

To add application roles to a subject, set the add.application.roles parameter to true. Not to add them, set it to false. The default value is true. The principal class for an application role is the oracle.security.jps.service.policystore.ApplicationRole class.

Setting the Anonymous User and Role

To enable the use of the anonymous user, set enable.anonymous to true. To disable it, set it to false. The default value is true.

To remove the anonymous role from a subject, set remove.anonymous.role to true. To retain it, set it to false. The default value is false.

The names and the principal classes for the anonymous user and role are:

anonymous
oracle.security.jps.internal.core.principals.JpsAnonymousUserImpl
anonymous-role
oracle.security.jps.internal.core.principals.JpsAnonymousRoleImpl

The following example illustrates the setting of the anonymous user and role in the web.xml file, and the use of the JpsFilter filter by the MyServlet Java servlet:

<filter>
   <filter-name>JpsFilter</filter-name>
   <filter-class>oracle.security.jps.ee.http.JpsFilter</filter-class>
   <init-param>
      <param-name>enable.anonymous</param-name>
      <param-value>true</param-value>
   </init-param>
   <init-param>
      <param-name>remove.anonymous.role</param-name>
      <param-value>false</param-value>
   </init-param>
</filter>
<filter-mapping>
   <filter-name>JpsFilter</filter-name>
   <servlet-name>MyServlet</servlet-name>
   <dispatcher>REQUEST</dispatcher>
 </filter-mapping>

The following example illustrates the setting of remove.anonymous.role in the ejb-jar.xml file, and the use of the interceptor by MyEjb:

<interceptor>
  <interceptor-class>oracle.security.jps.ee.ejb.JpsInterceptor</interceptor-class>
  <env-entry>
     <env-entry-name>remove.anonymous.role</env-entry-name>
     <env-entry-type>java.lang.Boolean</env-entry-type>
     <env-entry-value>false</env-entry-value>
     <injection-target>
       <injection-target-class>
          oracle.security.jps.ee.ejb.JpsInterceptor</injection-target-class>
       <injection-target-name>remove_anonymous_role/injection-target-name>
     </injection-target>
  </env-entry>
</interceptor>
...
<interceptor-binding>
   <ejb-name>MyEjb</ejb-name>
   <interceptor-class>
        oracle.security.jps.ee.ejb.JpsInterceptor</interceptor-class>
</interceptor-binding>

Setting Authenticated Role Support

To add the authenticated role to a subject, set the add.authenticated.role property to true. Not to add it, set it to false. The default value is true.

The name and principal class for the authenticated role are:

authenticated-role
oracle.security.jps.internal.core.principals.JpsAuthenticatedRoleImpl

The following example illustrates the configuration of the add.authenticated.role property and the use of the JpsFilter filter by the MyServlet Java servlet, in the web.xml file:

<filter>
   <filter-name>JpsFilter</filter-name>
   <filter-class>oracle.security.jps.ee.http.JpsFilter</filter-class>
   <init-param>
      <param-name>add.authenticated.role</param-name>
      <param-value>false</param-value>
   </init-param>
</filter>
<filter-mapping>
   <filter-name>JpsFilter</filter-name>
   <servlet-name>MyServlet</servlet-name>
   <dispatcher>REQUEST</dispatcher>
</filter-mapping>

Setting JAAS Mode

To set JAAS mode use the oracle.security.jps.jaas.mode parameter with one of the following values:

doAs
doAsPrivileged
off
undefined
subjectOnly

The default value is doAsPrivileged.

The following example illustrates the use of the JpsFilter filter by the MyServlet Java servlet:

<filter>
   <filter-name>JpsFilter</filter-name>
   <filter-class>oracle.security.jps.ee.http.JpsFilter</filter-class>
   <init-param>
      <param-name>oracle.security.jps.jaas.mode</param-name>
      <param-value>doAs</param-value>
   </init-param>
</filter>
<filter-mapping>
   <filter-name>JpsFilter</filter-name>
   <servlet-name>MyServlet</servlet-name>
   <dispatcher>REQUEST</dispatcher>
</filter-mapping>

The following example illustrates a doAs setting and the use of the JpsInterceptor interceptor:

<interceptor>
  <interceptor-class>oracle.security.jps.ee.ejb.JpsInterceptor</interceptor-class>
  <env-entry>
     <env-entry-name>oracle.security.jps.jaas.mode</env-entry-name>
     <env-entry-type>java.lang.String</env-entry-type>
     <env-entry-value>doAs</env-entry-value>
     <injection-target>
       <injection-target-class>
          oracle.security.jps.ee.ejb.JpsInterceptor</injection-target-class>
       <injection-target-name>oracle_security_jps_jaas_mode
                </injection-target-name>
     </injection-target>
  </env-entry>
</interceptor>
...
<interceptor-binding>
   <ejb-name>MyEjb</ejb-name>
   <interceptor-class>
        oracle.security.jps.ee.ejb.JpsInterceptor</interceptor-class>
</interceptor-binding>

Interceptor Configuration Requirements

The following requirements apply to all JpsInterceptor parameter specifications:

• Must specify the parameter type in the env-entry-type element.

• Must specify the injection-target element, which identifies the same class as that of the interceptor (specified in the injection-target-class element). In the injection-target-name element, the name must be rewritten as a string where the dots are replaced by underscores.

• Must specify the binding of the interceptor to EJB by referring to the interceptor's class.

Summary of Filter and Interceptor Parameters

The following table lists the filter and the interceptor parameters:

Table 23-1 JpsFilter and JpsInterceptor Parameters

Parameter Name	Values	Default	Function	Notes
application.name	Any valid string. The value is case-sensitive.	The name of the application.	Specifies the subset of policies that the Java servlet or EJB use.	Must specify if several Java servlets or EJB access the same subset of policies.
add.application.roles	true or false	true	Adds application roles to the subject.	Set to false not to add application roles to a subject.
enable.anonymous	true or false	true	Enables the anonymous user in the subject.	If true, then it includes the anonymous user and role in a subject.
remove.anonymous.role	true or false	false	Removes the anonymous role from the subject after authentication.	Available for Java servlets only. For EJB, the anonymous role is removed from a subject. If false, then the subject retains the anonymous role after authentication. If true, then it is removed after authentication.
add.authenticated.role	true or false	true	Allows adding the authenticated role to the subject.	Set to false not to include the authenticated role to a subject.
oracle.security.jps.jaas.mode	doAsPrivileged doAs off undefined subjectOnly	doAsPrivileged	Sets the JAAS mode.	Not Applicable (N/A)

Choosing the Appropriate Class for Enterprise Groups and Users

The classes you specify in members of an application role must be either the application role class or one of the following two:

weblogic.security.principal.WLSUserImpl
weblogic.security.principal.WLSGroupImpl

The following example illustrates the use of the ApplicationRole and WLSGroupImpl classes in the specification of a role:

<app-role>
  <name>app_monitor</name>
  <display-name>application role monitor</display-name>
  <class>oracle.security.jps.service.policystore.ApplicationRole</class>
  <members>
    <member>
      <class>oracle.security.jps.service.policystore.ApplicationRole</class>
      <name>app_operator</name>
    </member>
    <member>
      <class>weblogic.security.principal.WLSGroupImpl</class>
      <name>Developers</name>
    </member>
  </members>
 </app-role>

Application role names are case-insensitive. Enterprise user and group names are case-sensitive.

See also:

Failure to Get Permissions - Case Mismatch

Packaging a Jakarta EE Application Manually

This section explains the packaging requirements for Java servlets and EJB that use custom policies and credentials.

Application policies are defined in the jazn-data.xml file. The only supported way to include this file with an application is to package it in the META-INF directory of the application EAR file.

Java servlets are packaged in a WAR file that contains the web.xml configuration file. The EJB is packaged in a WAR file that contains the ejb-jar.xml configuration file. The WAR file must include the configuration of the filter (for Java servlets) or the interceptor (for EJB) in the corresponding configuration file.

The following packaging requirements are stated to Java servlets and the configuration of the filter in the web.xml file, but they also apply to EJB and the configuration of the interceptor in the ejb-jar.xml file:

• The application must be packaged in a single EAR file.

• The EAR file must contain exactly one META-INF/jazn-data.xml file that specifies application policies and roles.

• The EAR file may contain one or more WAR files.

• Each WAR or JAR file in the EAR file must contain exactly one web.xml file that configures the JpsFilter filter and such configurations in all EAR files must be identical.

• Component credentials in cwallet.sso files can be packaged in the EAR file.

If a component requires a filter configuration different from that of other components, then it must be packaged in a separate EAR file and deployed separately.

See also:

Configuring the Filter and the Interceptor

• Packaging Policies with the Application
  
• Packaging Credentials with the Application
  

Packaging Policies with the Application

Application policies are defined in the jazn-data.xml file. The only supported way to include this file with an application is to package it in the META-INF directory of the application EAR file.

To specify particular policies for a component in a WAR file, that component must be packaged in a separate EAR file with its own jazn-data.xml file. No other policy package combination is supported, and policy files other than jazn-data.xml are disregarded.

Packaging Credentials with the Application

Application credentials are defined in the cwallet.sso file. The only supported way to include this file with an application is to package it in the META-INF directory of the application EAR file.

To specify particular credentials for a component in a WAR file, that component must be packaged in a separate EAR file with its own cwallet.sso file. No other credential package combination is supported, and credential files other than the cwallet.sso file are disregarded.

Configuring Jakarta EE Applications to Use OPSS

The following sections describe how to control the migration of policies and credentials packaged with a Jakarta EE application at application deployment:

See also:

Migrating Identities with migrateSecurityStore

• Controlling Policy Migration
  
• Configuring Policy Migration According to Behavior
  
• Using File Credential Stores
  
• Controlling Credential Migration
  
• Configuring Credential Migration According to Behavior
  
• Using Supported Permission Classes
  
• Specifying Bootstrap Credentials Manually
  

Controlling Policy Migration

You control the migration of application policies at deployment with parameters specified in the META-INF/weblogic-application.xml file. If you do not use Fusion Middleware Control to manage your application, then you must enter these configurations manually.

Set thejps.deployment.handler.disabled system property to true to disable the migration of policies and credentials at deployment for all applications regardless of particular settings in the weblogic-application.xml files.

When you deploy an application that incudes policies and credentials to a Managed Server running in a computer different from where the Administration Server is running, do not use the life cycle listener to control migration at deployment, because the data maintained by the Managed Server and the Administration Server would end up not synchronized. Instead, use the migrateSecurityStore command to migrate those policies and credentials to the security store.

The parameters that configure the migration and removal of policies are the following:

• Migration

  • jps.policystore.migration

  • jps.apppolicy.idstoreartifact.migration

  • jps.policystore.removal

• Listener

  • JpsApplicationLifecycleListener

• Principal Validation

  • jps.policystore.migration.validate.principal

• Target of Migration (application stripe)

  • jps.policystore.applicationid

See also:

Deploying Secure Applications with Fusion Middleware Control

• jps.policystore.migration
  
• jps.policystore.applicationid
  
• jps.apppolicy.idstoreartifact.migration
  
• jps.policystore.removal
  
• jps.policystore.migration.validate.principal
  
• JpsApplicationLifecycleListener
  

jps.policystore.migration

This parameter, configured in the following example, specifies whether to migrate and merge or overwrite policies in the security store:

<wls:application-param>
  <wls:param-name>jps.policystore.migration</wls:param-name>
  <wls:param-value>Option</wls:param-value>
</wls:application-param>

where Option stands for MERGE, OVERWRITE, or OFF.

Set to OFF to prevent migration. Set to MERGE to migrate merging policies. Set to OVERWRITE to migrate overwriting policies in the target store. The default value is MERGE.

jps.policystore.applicationid

This parameter, configured in the following example, specifies the target stripe into which policies are migrated.

<wls:application-param>
  <wls:param-name>jps.policystore.applicationid</wls:param-name>
  <wls:param-value>myApplicationStripe</wls:param-value>
</wls:application-param>

The value can be any valid string. If unspecified, then WebLogic Server creates a stripe name based on the application name and version using the application_name#version format.

The value of this parameter must match the value of the application.name parameter specified for the JpsFilter filter (in web.xml) or for the JpsInterceptor interceptor (in ejb-jar.xml).

The value read from the weblogic-application.xml file is used at deployment. The value read from the web.xml or the ejb-jar.xml file is used at runtime.

jps.apppolicy.idstoreartifact.migration

This parameter, configured in the following example, specifies whether to exclude migrating references to enterprise users or groups, such as the mapping of application roles to enterprise users or groups. Thus it allows you to the migration of just application policies and it ignores the mapping of application roles to enterprise users or groups.

<wls:application-param>
  <wls:param-name>jps.apppolicy.idstoreartifact.migration</wls:param-name>
  <wls:param-value>Option</wls:param-value>
</wls:application-param>

where Option stands for true or false. Set to false to exclude the migration of artifacts referencing enterprise users or groups. Otherwise, set it to true. If unspecified, then it defaults to true.

Note:

After you deploy the application with this parameter set to false and before the application is used in the domain, map application roles to enterprise groups or users with Oracle Enterprise Manager Fusion Middleware Control (Fusion Middleware Control) or Oracle WebLogic Remote Console.

The following examples illustrate a jazn-data.xml file, packaged in the application EAR file, that describes the policy. The system-jazn-data.xml file represents the file security store into which application policies are migrated. It is assumed that the jps.apppolicy.idstoreartifact.migration parameter is false.

<!-- Example 1: app role applicationDeveloperRole in jazn-data.xml that references 
the enterprise group developers -->
<app-role>
<class>weblogic.security.principal.WLSGroupImpl</class> 
  <name>applicationDeveloperRole</name> 
  <display-name>application role applicationDeveloperRole</display-name> 
  <members>
    <member> 
      <class>weblogic.security.principal.WLSGroupImpl</class>
      <name>developers</name> 
    </member>
  </members>
</app-role>

<!-- app role applicationDeveloperRole in system-jazn-data.xml after migration: notice how the role developers has been excluded -->
<app-role>
  <name>applicationDeveloperRole</name> 
  <display-name>application role applicationDeveloperRole</display-name> 
  <guid>CB3633A0D0E811DDBF08952E56E4544A</guid> 
  <class>weblogic.security.principal.WLSGroupImpl</class> 
</app-role>

<!-- Example 2: app role viewerApplicationRole in jazn-data.xml makes reference 
to the anonymous role -->
<app-role>
  <name>viewerApplicationRole</name> 
  <display-name>viewerApplicationRole</display-name> 
  <class>weblogic.security.principal.WLSGroupImpl</class> 
  <members>
    <member>
      <class>
oracle.security.jps.internal.core.principals.JpsAnonymousRoleImpl
      </class> 
      <name>anonymous-role</name> 
    </member>
  </members>
</app-role>
 
<!-- app role viewerApplicationRole in system-jazn-data.xml after migration: 
notice that references to the anonymous role are never excluded -->
<app-role>
  <name>viewerApplicationRole</name>
  <display-name>viewerApplicationRole</display-name>
  <guid>CB3D86A0D0E811DDBF08952E56E4544A</guid> 
  <class>weblogic.security.principal.WLSGroupImpl</class> 
  <members>
    <member>
      <class>
oracle.security.jps.internal.core.principals.JpsAnonymousRoleImpl
      </class>
      <name>anonymous-role</name> 
    </member>
  </members>
</app-role>

jps.policystore.removal

This parameter, configured in the following example, specifies whether to remove policies when you undeploy the application:

<wls:application-param>
  <wls:param-name>jps.policystore.removal</wls:param-name>
  <wls:param-value>OFF</wls:param-value>
</wls:application-param>

Set to OFF to prevent removing policies. If not set, then policies are removed. By default, policies are not removed when you undeploy the application.

Consider using this setting when multiple applications share the same application stripe and one of them is undeployed, but note that setting jps.plicystore.ramoval to OFF for a given application requires knowing, at application deployment, whether it uses an application stripe shared with other applications.

jps.policystore.migration.validate.principal

This parameter, configured in the following example, specifies whether to check for principals in system and application policies at deployment or redeployment:

<wls:application-param>
  <wls:param-name>jps.policystore.migration.validate.principal</wls:param-name>
  <wls:param-value>option</wls:param-value>
</wls:application-param>

where option stands for true or false.

Set to true to validate enterprise users and groups: if a principal (in an application or system policy) refers to an enterprise user or group not found in the identity store, then log a warning and continue. Set to false, to skip the check. If unspecified, it defaults to false. Validation warnings are logged in the server log.

JpsApplicationLifecycleListener

This parameter, configured in the following example, specifies the listener class:

<wls:listener>
  <wls:listener-class>
    oracle.security.jps.wls.listeners.JpsApplicationLifecycleListener
  </wls:listener-class>
</wls:listener>

Configuring Policy Migration According to Behavior

The following sections describe recommendations and the settings required in typical scenarios:

• Recommendations
  
• Skipping Migrating Policies
  
• Migrating Merging Policies
  
• Migrating Overwriting Policies
  
• Removing or Not Removing Policies
  
• Migrating Policies in a Static Deployment
  

Recommendations

The following recommendations apply to both policies and credential migration.

A value setting not described in the following sections is not recommended.

If you want to deploy your application to multiple Managed Servers, then choose to migrate when you deploy it to just one of those servers only. The rest of the deployments should choose not to migrate policies and credentials. This ensures that the policies and credentials are migrated only once from the application store to the store. All the deployments must use the same application ID.

An alternative to migrating security data at deployment is to migrate policies and credentials with the migrateSecurityStore WLST command. For information about this command, see Migrating the Security Store with migrateSecurityStore.

If your application packages policies and credentials and you deploy it to several servers, then you must include the Administration Server so that the process updates the$DOMAIN_HOME/config/fmwconfig/system-jazn-data.xml policy file.

Skipping Migrating Policies

The following table shows the settings to skip migration:

Table 23-2 Settings to Skip Policy Migration

Settings	Valid at Deployment or Redeployment
JpsApplicationLifecycleListener	Set
jps.policystore.migration	OFF

Skip migrating policies when you want to keep domain policies as they are, but you would migrate policies when deploying the application for the first time.

Migrating Merging Policies

The following table shows the setting to migrate only policies that are not in the target store:

Table 23-3 Settings to Migrate Merging Policies

Settings	Valid at Deployment or Redeployment
JpsApplicationLifecycleListener	Set
jps.policystore.migration	MERGE
jps.policystore.applicationid	Optional. Defaults to the Java servlet or EJB name.
jps.apppolicy.idstoreartifact.migration	Optional. Set to false to exclude migrating policies that reference enterprise artifacts. Otherwise set to true. Defaults to true.
jps.policystore.migration.validate.principal	Optional. Set to true to validate enterprise users and roles in application and system policies. Set to false, otherwise. If unspecified, it defaults to false.

Choose to migrate policies with merging at redeployment if a policy has changed (since last undeployment) or you want to add new policies.

Migrating Overwriting Policies

The following table shows the setting to migrate all policies overwriting matching target policies:

Table 23-4 Settings to Migrate Overwriting Policies

Settings	Valid at Deployment or Redeployment
JpsApplicationLifecycleListener	Set
jps.policystore.migration	OVERWRITE
jps.policystore.migration.validate.principal	Optional. Set to true to validate enterprise users and roles in application and system policies. Set to false, otherwise. If unspecified, it defaults to false.

Choose to migrate policies with overwriting at redeployment if you want to replace all policies with new ones.

Removing or Not Removing Policies

Only application policies can be removed at undeployment. System policies are not removed. The following table shows the setting to remove application policies at undeployment:

Table 23-5 Settings to Remove Policies

Settings	Valid at Undeployment
JpsApplicationLifecycleListener	Set
jps.policystore.removal	Not set (default)

The stripe from which policies are removed at undeployment depends on the stripe you specified at deployment or redeployment. If you redeploy an application with a stripe specification different than the original one, then policies in that original stripe are not removed.

The following table shows the settings to disable removing policies at application undeployment:

Table 23-6 Settings to Disable Removing Policies

Settings	Valid at Undeployment
JpsApplicationLifecycleListener	Set
jps.policystore.removal	OFF

What Gets Removed and What Remains

Consider the myApp application that has been configured for automatic migration and removal of policies. The following example (in the application's jazn-data.xml file) illustrates the policies that are migrated at application deployment and policies that are not removed at application undeployment:

<jazn-data>
  <policy-store>
    <applications>
    <!-- The contents of the following element application is migrated 
         to the element policy-store in domain system-jazn-data.xml;
         when myApp is undeployed with EM, it is removed from security store -->
      <application>
        <name>myApp</name>
        <app-roles>
          <app-role>
            <class>oracle.security.jps.service.policystore.SomeRole</class>
            <name>applicationDeveloperRole</name>
            <display-name>application role applicationDeveloperRole</display-name>
            <members>
              <member>
                <class>oracle.security.somePath.JpsXmlEnterpriseRoleImpl</class>
                <name>developers</name>
              </member>
            </members>
          </app-role>
        </app-roles>
        <jazn-policy>
          <grant>
            <grantee>
              <principals>
                <principal>
            <class>oracle.security.jps.service.policystore.ApplicationRole</class>
                  <name>applicationDeveloperRole</name>
                </principal>
              </principals>
            </grantee>
            <permissions>
              <permission>
                <class>oracle.security.jps.JpsPermission</class>
                <name>loadPolicy</name>
              </permission>
            </permissions>
          </grant>
        </jazn-policy>
      </application>
    </applications>
  </policy-store>
    
  <jazn-policy>
  <!-- The following codesource grant is migrated to the element
       jazn-policy in domain system-jazn-data.xml; when myApp is undeployed
       with FMC, it is not removed from security store -->
    <grant>
      <grantee>
        <codesource>
          <url>file:${domain.home}/servers/${weblogic.Name}/Foo.ear/-</url>
        </codesource>
      </grantee>
      <permissions>
        <permission>               <class>oracle.security.jps.service.credstore.CredentialAccessPermission</class>
          <name>context=SYSTEM,mapName=*,keyName=*</name>
          <actions>*</actions>
        </permission>
      </permissions>
    </grant>
  </jazn-policy>
</jazn-data>

Migrating Policies in a Static Deployment

The following table shows the settings to migrate application policies when the application is statically deployed. The MERGE or OVERWRITE operation takes place only if the application policies do not already exist in the security store.

Table 23-7 Settings to Migrate Policies with Static Deployments

Settings	Valid at Static Deployments
JpsApplicationLifecycleListener	Set
jps.policystore.migration	MERGE or OVERWRITE

The following table shows the settings to skip migrating application policies when the application is statically deployed.

Table 23-8 Settings Not to Migrate Policies with Static Deployments

Settings	Valid at Static Deployments
JpsApplicationLifecycleListener	Set
jps.policystore.migration	OFF

Using File Credential Stores

A file credential store is the cwallet.sso file. The location of this file is specified in the jps-config.xml file with the <serviceInstance> element:

<serviceInstance name="credstore" provider="credstoressp">
   <property name="location"  value="myCredStorePath"/>
</serviceInstance>

See also:

Administering Oracle Fusion Middleware

• Common Wallet Operations

• Managing Keystores, Wallets, and Certificates

Controlling Credential Migration

You control the migration of application credentials at deployment with parameters specified in the META-INF/weblogic-application.xml file. If you do not use Fusion Middleware Control to manage your application, then you must enter these configurations manually.

Set the jps.deployment.handler.disabled system property to true to disable the migration of policies and credentials at deployment for all applications regardless of settings in weblogic-application.xml application files.

When you deploy an application that packages policies and credentials to a Managed Server running in a computer different from where the Administration Server is running, do not use the life cycle listener to control migration at deployment because the data maintained by the Managed Server and the Administration Server would end up not synchronized. Instead, use the migrateSecurityStore command to migrate those policies and credentials to the security store. For information about this command, see Migrating the Security Store with migrateSecurityStore.

The parameters that configure the migration and removal of credentials are:

• jps.credstore.migration

• JpsApplicationLifecycleListener

• jps.credstore.migration
  

jps.credstore.migration

This parameter, configured in the following example, specifies whether to migrate and merge or overwrite credentials in the security store:

<wls:application-param>
  <wls:param-name>jps.credstore.migration</wls:param-name>
  <wls:param-value>Option</wls:param-value>
</wls:application-param>

where Option stands for MERGE, OVERWRITE, or OFF.

Set to OFF to prevent migration. Set to MERGE to migrate merging credentials. Set to OVERWRITE to migrate overwriting credentials. The default value is MERGE.

Configuring Credential Migration According to Behavior

The following sections describe recommendations and the settings required in typical scenarios.

Note that application credentials are not removed when you undeploy the application.

• Skipping Migrating Credentials
  
• Migrating Merging Credentials
  
• Migrating Overwriting Credentials
  

Skipping Migrating Credentials

The following table shows the setting to prevent the migration:

Table 23-9 Settings to Skip Credential Migration

Settings	Valid at deployment or redeployment
jps.credstore.migration	OFF

Migrating Merging Credentials

The following table shows the settings required to migrate only credentials that are not in the target store:

Table 23-10 Settings to Migrate Merging Credentials

Settings	Valid at deployment or redeployment
JpsApplicationLifecycleListener	Set
jps.credstore.migration	MERGE

Migrating Overwriting Credentials

The following table shows the setting to migrate all credentials overwriting target credentials:

Table 23-11 Settings to Migrate Overwriting Credentials

Settings	Valid at deployment or redeployment
JpsApplicationLifecycleListener	Set
jps.credstore.migration	OVERWRITE
jps.app.credential.overwrite.allowed	Must be true

Using Supported Permission Classes

The following sections describe the values you use in the <class>, <name>, and <actions> elements within a <permission> element in the system-jazn-data.xml file:

All permission classes used in policies must be included in the class path, so the policy provider can load them when a service instance is initialized.

• Security Store Permission Class
  
• Credential Store Permission Class
  
• Generic Permission Class
  

Security Store Permission Class

The security store permission class is:

oracle.security.jps.service.policystore.PolicyStoreAccessPermission

If the permission applies to a particular application, then use the following pattern for the corresponding name element, where appStripeName specifies the particular application:

context=APPLICATION,name=appStripeName

When the permission applies to all applications, use the following name pattern:

context=APPLICATION,name=*

If the permission applies to all applications and system policies, then use the following name pattern:

context=SYTEM

The values allowed in the actions element are the following (* stands for any action):

*
createPolicy
getConfiguredApplications
getSystemPolicy
getApplicationPolicy
createApplicationPolicy
deleteApplicationPolicy
grant
revoke
createAppRole
alterAppRole
removeAppRole
addPrincipalToAppRole
removePrincipalFromAppRole
hasPermission
containsAppRole

The following examples illustrate grants to create policies and to do runtime checks:

grant { 
   permission oracle.security.jps.service.policystore.PolicyStoreAccessPermission  
 "context=APPLICATION,name=*", "*"; 
   permission oracle.security.jps.service.policystore.PolicyStoreAccessPermission  
 "context=SYSTEM,adminresource=ApplicationPolicy,instancename=*", "*"; oracle.security.jps.JpsPermission "AppSecurityContext.setApplicationID.*"; 
 };

grant codebase "file:${opss.lib.location}/-" { permission java.security.AllPermission; 
 };

Credential Store Permission Class

The credential store permission class is the oracle.security.jps.service.credstore.CredentialAccessPermission class.

If the permission applies to a map and a particular key in that map, then use the following pattern for the corresponding name element, where myMap and myKey specify the particular credential:

context=SYSTEM,mapName=myMap,keyName=myKey

If the permission applies to a map and all keys in it, then use the following pattern, where myMap specifies the particular map:

context=SYSTEM,mapName=myMap,keyName=*

The values allowed in the actions element are the following (* stands for any action):

*
read
write
update
delete

Generic Permission Class

The generic permission class is the oracle.security.jps.JpsPermission class.

If the permission applies to an assertion performed by the oracle.security.jps.callback.IdentityCallback callback instance, then use the following pattern for the corresponding <name> element:

IdentityAssertion

The only value allowed in the actions element is execute.

Specifying Bootstrap Credentials Manually

You specify the credentials needed to connect and access the domain repository in the cwallet.sso file, which is configured in the jps-config.xml file. These credentials are called bootstrap credentials and are always kept in a file.

Bootstrap credentials are configured in a context named bootstrap_credstore_context:

<serviceInstances>
    ...
  <serviceInstance location="./bootstrap" provider="credstoressp" name="bootstrap.cred">
      <property value="./bootstrap" name="location"/>
  </serviceInstance>
    ...
</serviceInstances>
 
<jpsContext name="bootstrap_credstore_context">
    <serviceInstanceRef ref="bootstrap.cred"/>
</jpsContext>

where the cwallet.sso file is assumed present in the bootstrap directory.

The bootstrap.security.principal.key and bootstrap.security.principal.map properties specify the bootstrap map and key:

<serviceInstance provider="ldap.policystore.provider" name="policystore.ldap">
  ...
  <property value="bootstrapKey" name="bootstrap.security.principal.key"/>
  ...
</serviceInstance>

If the bootstrap.security.principal.map property is unspecified, then it defaults to BOOTSTRAP_JPS.

To modify or add bootstrap credentials, see modifyBootStrapCredential and addBootStrapCredential in WLST Command Reference for Infrastructure Security.