21 Manually Configuring Java EE Applications to Use OPSS

This chapter describes the manual configuration and packaging recommended for Java EE applications that use OPSS but do not use Oracle ADF security. Note that, nevertheless, some topics apply also to Oracle ADF applications.

The information is directed to developers that want to configure and package a Java EE application outside Oracle JDeveloper environment.

The files relevant to application management during development, deployment, runtime, and post-deployment are the following:

DOMAIN_HOME/config/fmwconfig/jps-config.xml

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

jazn-data.xml (in application EAR file)

cwallet.sso (in application EAR file)

web.xml (in application EAR file)

weblogic-application.xml (in application EAR file)

21.1 Configuring the Servlet Filter and the EJB Interceptor

OPSS provides a servlet filter, the JpsFilter, and an EJB interceptor, the JpsInterceptor. The first one is configured in the file web.xml packed in a WAR file; the second one in the file ejb-jar.xml packed in a JAR file. OPSS also provides a way to configure in the file web.xml the stripe that application Mbeans should access; for details, see Configuring the Application Stripe for Application MBeans.

All of them are available on WebLogic and WebSphere. The configuration available differs slightly according to the server platform as follows:

On WebLogic, the JpsFilter is out-of-the-box automatically set with default parameter values and need not be explicitly configured in the deployment descriptor; it needs to be configured manually only if a value different from the default value is required. The JpsInterceptor must be manually configured.

On WebSphere, both the JpsFilter and the JpsInterceptor must be manually configured.

The manual configurations explained in this section are required only if you are packaging or configuring a Java EE application using the OPSS features detailed next outside the Oracle JDeveloper environment.

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

An application stripe defines a subset of policies in the policy store. An application wanting to use that subset of policies would define its application stripe with a string identical to that application name. In this way, different applications can use the same subset of policies in the policy store.

The specification of this parameter is optional and case sensitive; if unspecified, it defaults to the name of the deployed application. Its value defines the subset of policies in the policy store that the application intents to use.

One way of specifying the application stripe is withing the filter element, as illustrated in the following sample:

The following two samples illustrate the configuration of this parameter for a servlet and for an EJB.

The following fragment of a web.xml file shows how to configure two different servlets, MyServlet1 and MyServlet2, to be enabled with the filter so that subsequent authorization checks evaluate correctly. Note that servlets in the same WAR file always use the same policy stripe.

The addition of application roles to a subject is controlled by the following parameter, which can be set to true or false:

add.application.roles

To add application roles to a subject, set the property to true; otherwise, set it to false. The default value is true.

The principal class for the application role is:

oracle.security.jps.service.policystore.ApplicationRole

Anonymous User and Anonymous Role Support

The use of anonymous for a servlet is controlled by the following parameters, which can be set to true or false:

enable.anonymous
remove.anonymous.role

For an EJB, only the second parameter above is available, since the use of the anonymous user and role is always enabled for EJBs.

To enable the use of the anonymous user for a servlet, set the first property to true; to disable it, set it to false. The default value is true.

To remove the anonymous role from a subject, set the second property to true; to retain it, set it to false. The default value is false. Typically, one would want to remove the anonymous user and role after authentication, and only in special circumstances would want to retain them after authentication.

21.1.1 Interceptor Configuration Syntax

The following requirements and characteristics of the specifications apply to all parameters configured for the JpsInterceptor:

The setting of a parameter requires specifying its type (in the element <env-entry-type>).

The setting of a parameter requires the element <injection-target>, which specifies the same class as that of the interceptor (in the element <injection-target-class>), and the parameter name rewritten as a string where the dots are replaced by underscores (in the element <injection-target-name>).

The binding of an interceptor to an EJB is specified by the EJB name and the interceptor's class, that is, the interceptor is referred to by its class, not by name.

21.1.2 Summary of Filter and Interceptor Parameters

The following table summarizes the description of the parameters used by the JpsFilter and the JpsInterceptor:

Table 21-1 Summary of JpsFilter and JpsInterceptor Parameters

Parameter Name

Values

Default

Function

Notes

application.name

Any valid string. The value is case sensitive.

The name of the deployed application.

To specify the subset of policies that the servlet or EJB is to use.

It should be specified if several servlets or EJBs are to share the same subset of policies in the policy store.

add.application.roles

TRUE or FALSE

TRUE

To add application roles to a Subject.

Since it defaults to TRUE, it must be set (to FALSE) only if the application is not to add application roles to a Subject.

enable.anonymous

TRUE or FALSE

TRUE

To enable or disable the anonymous user in a Subject.

If set to TRUE, it creates a Subject with the anonymous user and the anonymous role.

remove.anonymous.role

TRUE or FALSE

FALSE

To keep or remove the anonymous role from a Subject after authentication.

Available for servlets only. For EJBs, the anonymous role is always removed from a Subject. If set to FALSE, the Subject retains the anonymous role after authentication; if set to TRUE, it is removed after authentication.

add.authenticated.role

TRUE or FALSE

TRUE

To allow addition of the authenticated role in a Subject.

Since it defaults to TRUE, it needs be set (to FALSE) only if the authenticated role is not be included in a Subject.

oracle.security.jps.jaas.mode

doAsPrivileged

doAs

off

undefined

subjectOnly

doAsPrivileged

To set the JAAS mode.

21.1.3 Configuring the Application Stripe for Application MBeans

If your application satisfies the following conditions:

It contains MBeans that access the policy store and perform authorization checks.

The application stripe name is not equal to the application name.

then, for the MBean to access the application stripe in the domain security store, the stripe name must be specified by the global parameter (or context parameter) application.name in the file web.xml, as illustrated in the following sample:

21.2 Choosing the Appropriate Class for Enterprise Groups and Users

Note:

If you are using Oracle JDeveloper, the tool chooses the appropriate classes. Therefore, the configuration explained next is only necessary if policies are entered outside the Oracle JDeveloper environment.

The classes specified in members of an application role must be either other application role class or one of the following:

21.3 Packaging a Java EE Application Manually

This section explains the packaging requirements for a servlet or an EJB (using custom policies and credentials) that is to be deployed on WebLogic Application Server or WebSphere Application Server.

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

Servlets are packaged in a WAR file that contains the configuration file web.xml; EJBs are packaged in a WAR file that contains the configuration file ejb-jar.xml. The WAR file must include the configuration of the filter JpsFilter (for servlets) or of the interceptor JpsInterceptor (for EJBs) in the corresponding configuration file.

The description that follows considers the packaging of a servlet and the configuration of the JpsFilter in the file web.xml, but it applies equally to the packaging of an EJB and the configuration of the JpsInterceptor in the file ejb-jar.xml.

Important:

Currently allJpsFilter configurations in allweb.xml files in an EAR file must have the same configuration. Same constrains apply to the JpsInterceptor.

The packaging requirements and assumptions for a Java EE application that wants to use custom policies and credentials are the following:

The application to be deployed must be packaged in a single EAR file.

The EAR file must contain exactly one file META-INF/jazn-data.xml, where application policies and roles are specified; these apply equally to all components in the EAR file.

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 (or ejb-jar.xml) where the JpsFilter (or JpsInterceptor) is configured, and such configurations in all EAR files must be identical.

Component credentials in cwallet.sso files can be packaged in the EAR file. These credentials can be migrated to the credential store when the application is deployed with Oracle Enterprise Manager Fusion Middleware Control.

Note:

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

21.3.1Packaging Policies with Application

Application policies are defined in the file jazn-data.xml. The only supported way to include this file with an application is to package it in the directory META-INF of an EAR file. The EAR file may contain zero or more WAR files, but the policies can be specified only in that XML file located in that EAR directory. 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 as specified above. No other policy package combination is supported in this release, and policy files other than the top jazn-data.xml are disregarded.

21.3.2Packaging Credentials with Application

Application credentials are defined in a file that must be named cwallet.sso. The only supported way to include this file with an application is to package it in the directory META-INF of an EAR file. The EAR file may contain zero or more WAR files, but credentials can be specified only in that cwallet.sso file located in that EAR directory. 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 as specified above. No other credential package combination is supported in this release, and credential files other than the top cwallet.sso are disregarded.

21.4 Configuring Applications to Use OPSS

This section describes several configurations that a developer would perform manually for a Java EE application developed outside the Oracle JDeveloper environment, in the following sections:

Use the system propertyjps.deployment.handler.disabled to disable the migration of application policies and credentials for applications deployed in a WebLogic Server.

When this system property is set to TRUE, the migration of policies and credentials at deployment is disabled for all applications regardless of the particular application settings in the application file weblogic-application.xml.

21.4.1 Parameters Controlling Policy Migration

The migration of application policies at deployment is controlled by several parameters configured in the file META-INF/weblogic-application.xml.

For details about the specification of parameters on WebSphere, see Oracle Fusion Middleware Third-Party Application Server Guide.

The parameters that control migration of policies during application deployment or redeployment, and the removal of policies during undeployment are the following:

The configurations explained next need be entered manually onlyif you are not using Fusion Middleware Control to manage your application.

When deploying an application that is using file-based stores to a managed server running in a computer different from that where the administration server is running, do not use the life cycle listener. Otherwise, the data maintained by the managed server and the administration server would not match, and security may not work as expected. Instead of employing the life cycle listener, use the OPSS script migrateSecurityStore to migrate application policies and credentials to the domain stores.

The above remark applies only when using file-based stores.

jps.policystore.migration

This parameter specifies whether the migration should take place, and, when it does, whether it should merge with or overwrite matching policies present in the target store.

On WebLogic, it is configured as illustrated in the following fragment:

Set to OFF to prevent policy migration; otherwise, set to MERGE to migrate and merge with existing policies, or to OVERWRITE to migrate and overwrite existing policies. The default value (at deploy) is MERGE.

jps.policystore.applicationid

This parameter specifies the target stripe into which policies are migrated.

On WebLogic, it is configured as illustrated in the following fragment:

This parameter's value can be any valid string; if unspecified, Oracle WebLogic Server picks up a stripe name based on the application name and version, namely, application_name#version.

The value of this parameter must match the value of application.name specified for the JpsServlet (in the file web.xml) or for the JpsInterceptor (in the file ejb-jar.xml). For details, see Application Name (Stripe).

The value picked from weblogic-application.xml is used at deploy time; the value picked from web.xml or ejb-jar.xml is used at runtime.

JpsApplicationLifecycleListener

This parameter is supported on WebLogic only, and it must be set as illustrated in the following fragment:

This parameter is supported on WebLogic only, and it specifies whether the policy migration should exclude migrating references to enterprise users or groups, such as application roles grants to enterprise users or groups, and permission grants to enterprise users or groups; thus it allows the migration of just application policies and, when enabled, the migration ignores the mapping of application roles to enterprise groups or users.

Option stands for one of the values TRUE or FALSE. Set to FALSE to exclude the migration of artifacts referencing enterprise users or groups; otherwise, set it to TRUE; if unspecified, it defaults to TRUE.

Important:

When an application is deployed with this parameter set to FALSE (that is, to exclude the migration of non-application specific policies), before the application can be used in the domain, the administrator should perform the mapping of application roles to enterprise groups or users with Fusion Middleware Control or the WebLogic Administration Console.

Note how this setting allows the administrator further control over application roles.

The following examples show fragments of the same jazn-data.xml files. This file, packaged in the application EAR file, describes the application authorization policy.

The file system-jazn-data.xml represents the domain file-based policy store into which application policies are migrated (and used in the example for simplicity).

It is assumed that the parameter jps.apppolicy.idstoreartifact.migration has been set to FALSE.

When set, the parameter's value must be OFF. By default, it is not set.

Set to OFF to prevent the removal of policies; if not set, policies are removed.

The above setting should be considered when multiple applications are sharing the same application stripe. The undeploying application would choose not to remove application policies because other applications may be using the common set of policies.

Note:

Deciding to set this parameter to OFF for a given application requires knowing, at the time the application is deployed, whether the application stripe is shared by other applications.

jps.policystore.migration.validate.principal

This parameter is supported on WebLogic only, and it specifies whether the check for principals in system and application policies at deployment or redeployment should take place.

When set to TRUE the system checks the validity of 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, a warning is issued. When set to FALSE, the check is skipped.

If not set, the parameter value defaults to FALSE.

Validation errors are logged in the server log, and they do not terminate the operation.

21.4.2 Policy Parameter Configuration According to Behavior

This section describes the settings required to manage application policies with the following behaviors:

Any value settings other than the ones described in the following sections are not recommended and may lead to unexpected migration behavior. For more details, see Recommendations.

All behaviors can be specified with Fusion Middleware Control when the application is deployed, redeployed, or undeployed with that tool.

21.4.2.1 To Skip Migrating All Policies

The following matrix shows the settings that prevent the migration from taking place:

Table 21-2 Settings to Skip Policy Migration

Valid at deploy or redeploy

JpsApplicationLifecycleListener

Set

jps.policystore.migration

OFF

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

21.4.2.2 To Migrate All Policies with Merging

The following matrix shows the setting of required and optional parameters that migrates only policies that are not in the target store (optional parameters are enclosed in between brackets):

Table 21-3 Settings to Migrate Policies with Merging

Valid at deploy or redeploy

JpsApplicationLifecycleListener

Set

jps.policystore.migration

MERGE

[jps.policystore.applicationid]

Set to the appropriate string. Defaults to servlet or EJB name.

[jps.apppolicy.idstoreartifact.migration]

Set to FALSE to exclude migrating policies that reference enterprise artifacts; otherwise set to TRUE. Defaults to TRUE.

[jps.policystore.migration.validate.principal]

Set to TRUE to validate enterprise users and roles in application and system policies. Set to FALSE, otherwise. If unspecified, it defaults to FALSE.

Typically, you would choose migrating policies with merging at redeploy when the policies have changed and you want to add to the existing policies.

21.4.2.3 To Migrate All Policies with Overwriting

The following matrix shows the setting that migrates all policies overwriting matching target policies (optional parameters are enclosed in between brackets):

Table 21-4 Settings to Migrate Policies with Overwriting

Valid at deploy or redeploy

JpsApplicationLifecycleListener

Set

jps.policystore.migration

OVERWRITE

[jps.policystore.migration.validate.principal]

Set to TRUE to validate enterprise users and roles in application and system policies. Set to FALSE, otherwise. If unspecified, it defaults to FALSE.

Typically, you would choose migrating policies with overwriting at redeploy when a new set of policies should replace existing policies. Note that if the optional parameter jps.policy.migration.validate.principal is needed, it must be set manually.

21.4.2.4 To Remove (or Prevent the Removal of) Application Policies

The removal of application policies at undeployment is limited since code source grants in the system policy are not removed. For details, see example in What Gets Removed and What Remains.

The following matrix shows the setting that removes policies at undeployment:

Table 21-5 Settings to Remove Policies

Valid at undeploy

JpsApplicationLifecycleListener

Set

jps.policystore.removal

Not set (default)

Note:

The policies removed at undeploy are determined by the stripe that the application specified at deploy or redeploy. If an application is redeployed with a stripe specification different than the original one, then policies in that stripe (the original) are not removed.

The following matrix shows the setting that prevents the removal of application policies at undeployment:

Table 21-6 Settings to Prevent the Removal of Policies

Valid at undeploy

JpsApplicationLifecycleListener

Set

jps.policystore.removal

OFF

Note:

Deciding to set this parameter to OFF for a given application requires knowing, at the time the application has been deployed, whether the application stripe is shared by other applications.

What Gets Removed and What Remains

Consider the application myApp, which has been configured for automatic migration and removal of policies. The following fragment of the application's jazn-data.xml file (packed in the application EAR file) illustrates the application policies that are migrated when the application is deployed with Fusion Middleware Control and those that are and are not removed when the application is undeployed with Fusion Middleware Control:

To summarize: in regards to what gets removed, the important points to remember are the following:

All data inside the element <application> can be automatically removed at undeployment. In case of an LDAP-based policy store, the application scoped authorization policy data nodes get cleaned up.

All data inside the element <jazn-policy>cannot be automatically removed at undeployment.

21.4.2.5 To Migrate Policies in a Static Deployment

Table 21-7 shows the setting that migrates 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 domain.

Table 21-7 Settings to Migrate Policies with Static Deployments

JpsApplicationLifecycleListener

Set

jps.policystore.migration

MERGE or OVERWRITE

Table 21-8 shows the setting that skip the migration of application policies when the application is statically deployed.

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

JpsApplicationLifecycleListener

Set

jps.policystore.migration

OFF

21.4.2.6 Recommendations

Keep in mind the following suggestions:

When a LDAP-based policy store is used and the application is to be deployed to multiple managed servers, then choose to migrate to one of the servers only. The rest of the deployments should choose not to migrate policies. This ensures that the policies are migrated only once from the application store to the policy store.All the deployments must use the same application id.

Attempting policy migration to the same node for the same application multiple times (for example, on different managed servers) can result in policy migration failures. An alternative is to migrate the policy data to the store outside of the deployment process using the OPSS script migrateSecurityStore.

If, however, the application is deployed to several servers and the policy store is file-based, the deployment must include the administration server for the migration to update the policy file $DOMAIN_HOME/config/fmwconfig/system-jazn-data.xml.

21.4.3 Using a Wallet-Based Credential Store

The content of a wallet-based credential store is defined in a file that must be named cwallet.sso. A wallet-based credential store is also referred to as a file-based credential store.

Any value settings other than the ones described in the following sections are not recommended and may lead to unexpected migration behavior.

If the migration target is an LDAP-based credential store, it is recommended that the application be deployed to just one managed server or cluster. Otherwise, application credentials may not work as expected.

Note:

Credentials are not deleted upon an application undeployment. A credential may have started its life as being packaged with an application, but when the application is undeployed credentials are not removed.

21.4.5.1 To Skip Migrating Credentials

The following matrix shows the setting that prevents the migration from taking place:

Table 21-9 Settings to Skip Credential Migration

Valid at deploy or redeploy

jps.credstore.migration

OFF

21.4.5.2 To Migrate Credentials with Merging

The following matrix shows the setting of required and optional parameters that migrates only credentials that are not present in the target store (optional parameters are enclosed in between brackets):

Table 21-10 Settings to Migrate Credentials with Merging

Valid at deploy or redeploy

JpsApplicationLifecycleListener

Set

jps.credstore.migration

MERGE

21.4.5.3 To Migrate Credentials with Overwriting

This operation is valid on WebLogic only and when the server is running in development mode. The following matrix shows the setting that migrates all credentials overwriting matching target credentials:

Table 21-11 Settings to Migrate Credentials with Overwriting

Valid at deploy or redeploy

JpsApplicationLifecycleListener

Set

jps.credstore.migration

OVERWRITE

jps.app.credential.overwrite.allowed

This system property must be set to TRUE

21.4.6 Supported Permission Classes

The components of a permission are illustrated in the following snippet from a system-jazn-data.xml file:

21.4.6.2 Credential Store Permission

When the permission applies to a particular map and a particular key in that map, use the following pattern for the corresponding element <name>:

context=SYSTEM,mapName=myMap,keyName=myKey

When the permission applies to a particular map and all keys in that map, use the following pattern for the corresponding element <name>:

context=SYSTEM,mapName=myMap,keyName=*

The list of values allowed in the corresponding element <actions> are the following (* stands for any allowed action):

*
read
write
update
delete

21.4.6.3 Generic Permission

Class name:

oracle.security.jps.JpsPermission

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

IdentityAssertion

The only value allowed in the corresponding element <actions> is the following:

execute

21.4.7 Specifying Bootstrap Credentials Manually

This topic is for an administrator who is not using Oracle Fusion Middleware Control to perform reassociation to an LDAP-based store.

The credentials needed for an administrator to connect to and access an LDAP directory must be specified in a separate file named cwallet.sso (bootstrap credentials) and configured in the file jps-config.xml. These credentials are stored after the LDAP reassociation process. Bootstrap credentials are always file-based.

Every instance of an LDAP-based policy or credential store must specify bootstrap credentials in a <jpsContex> element that must be named bootstrap_credstore_context, as illustrated in the following excerpt:

In the example above, the bootstrap credential cwallet.sso is assumed located in the directory bootstrap.

An LDAP-based policy or credential store instance references its credentials using the properties bootstrap.security.principal.key and bootstrap.security.principal.map, as illustrated in the following instance of an LDAP-based policy store:

21.4.8Migrating Identities with migrateSecurityStore

Identity data can be migrated manually from a source repository to a target LDAP repository using the OPSS script migrateSecurityStore. The script produces an LDIF file that (after minor manual editing) can be imported into an LDAP-based identity store and can be used with any source 10g or 11g file-based identity store.

For example, this script can be used to convert user and role information in a 10.1.x jazn-data.xml file to user and role information in WebLogic LDIF format; the LDIF output file can then be imported into the WebLogic embedded LDAP identity store after changing the password for each user (see note at the end of this section).

This script is offline, that is, it does not require a connection to a running server to operate; therefore, the configuration file passed to the argument configFile need not be an actual domain configuration file, but it can be assembled just to specify the source and destination repositories of the migration.

This script can be run in interactive mode or in script mode, on WebLogic Server, and in interactive mode only, on WebSphere. In interactive mode, you enter the script at a command-line prompt and view the response immediately after. In script mode, you write scripts in a text file (with a py file name extension) and run it without requiring input, much like the directives in a shell script.

For platform-specific requirements to run an OPSS script, see Important Note.

Script and Interactive Modes Syntaxes

To migrate identities on WebLogic, use the script (first) or interactive (second) syntaxes (arguments are written in separate lines for clarity):

For details about running OPSS scripts on WebSphere Application Server, see

The meaning of the arguments (all required except dstLdifFile) is as follows:

configFile specifies the location of a configuration file jps-config.xml relative to the directory where the script is run.

src specifies the name of a jps-context in the configuration file passed to the argument configFile, where the source store is specified.

dst specifies the name of another jps-context in the configuration file passed to the argument configFile, where the destination store is specified.
The destination store must be an LDAP-based identity store. For list of supported types, see Section 3.1.1, "Supported LDAP Identity Store Types."

dstLdifFile specifies the relative or absolute path to the LDIF file created. Applies only when the destination is an LDAP-based Oracle Internet Directory store, such as the embedded LDAP. Notice that the LDIF file is not imported into the LDAP server and, typically, requires manual editing.

The contexts passed to src and dst must be defined in the passed configuration file and must have distinct names. From these two contexts, the script determines the locations of the source and the target repositories involved in the migration.

Important:

The password of every user in the output LDIF file is not the real user password, but the fake string weblogic. In case the destination is an LDAP-based Oracle Internet Directory store, the fake string is change.

Therefore, before importing the LDIF file into the target LDAP store, the security administrator would typically edit this file and change the fake passwords for real ones.

21.4.9 Example of Configuration File jps-config.xml

The following sample shows a complete jps-config.xml file that illustrates the configuration of several services and properties; they apply to both Java EE and Java SE applications.