Options for Securing Web Application and EJB Resources

Securing WebLogic Resources Using Roles and Policies

Options for Securing Web Application and EJB Resources

The Java EE platform already provides a standard model for securing Web applications and EJBs. In this standard model, you define role mappings and policies in the Web application or EJB deployment descriptors.
Because this Java EE standard can be too inflexible for some environments, WebLogic Server offers a choice of other, more flexible models in addition to supporting the Java EE standard.

If you are implementing security using JACC (Java Authorization Contract for Containers as defined in JSR 115), use the Java EE standard model. Other WebLogic Server models are not available and the security functions for Web applications and EJBs in the Administration Console are disabled. See “Using the Java Authorization Contract for Containers” in Programming WebLogic Security.
You choose a security model when you deploy each Web application or EJB, and your choice is immutable for the lifetime of the deployment. If you want to use a different model, delete and redeploy the Web application or EJB.
The following sections describe options for securing Web application and Enterprise Java Bean (EJB) resources:

Comparison of Security Models for Web Applications and EJBs
Understanding the Advanced Security Model
Securing Web Applications and EJBs

The instructions for EJB resources provided in this section also apply to Message-Driven Beans (MDBs).

Comparison of Security Models for Web Applications and EJBs

Each security model defines two types of behaviors for securing Web applications and EJBs: where roles and policies are defined and which URL patterns and EJB methods trigger the Security Service to perform security checks. Table 4-1 compares the models.

Table 4-1 Security Model Behaviors
This Model... Uses Roles and Policies From... And Performs Security Checks...
Deployment Descriptor Only (Java EE standard) The web.xml, weblogic.xml and ejb-jar.xml, weblogic-ejb-jar.xml deployment descriptors. If roles have been defined for the application that contains the Web application or EJB, all roles are combined using a logical OR operation. Only when clients request URLs or EJB methods that are protected by a policy in the deployment descriptor.
Custom Roles This model uses role mappings from a role mapping provider that you configure for the security realm. You can use the Administration Console to configure the provider. Any role mappings in the deployment descriptors are ignored. The model uses the policies that are defined in the web.xml and ejb-jar.xml deployment descriptors. Only when clients request URLs or EJB methods that are protected by a policy in the deployment descriptor.
Custom Roles and Policies A role mapping provider and an authorization provider that you configure for the security realm. You can use the Administration Console to configure the providers. Any role mappings or policies in the deployment descriptors are ignored. For all URLs and EJB methods.
Advanced Configurable. You can configure this model to use only security data from deployment descriptors, use only the data from security providers, or import security data from deployment descriptors into the security provider databases to provide a baseline for further modifications. Configurable.

Discussion of Each Model

The following sections describe each model and suggest scenarios under which each is appropriate.
Deployment Descriptor Only Model

This is the standard Java EE model and is therefore a widely known technique for adding declarative security to Web applications and EJBs. It uses only roles and policies defined by a developer in the Java EE deployment descriptor (DD) and the WebLogic Server DD. It requires the security administrator to verify that the security principals (groups or users) in the deployment descriptors exist and are mapped properly in the security realm.

This model also affects application-scoped roles that apply to an EAR: with this model, the Security Service uses only the application-scoped roles defined in the WebLogic Server DD.
If a developer changes roles or policies in a deployment descriptor, WebLogic Server recognizes the change as soon as you redeploy the Web application, EJB, or EAR.
With this model, EJBs and URL patterns are not protected by roles and policies of a broader scope (such as a policy scoped to an entire Web application). If an EJB or URL pattern is not protected by a role or policy in the DD, then it is unprotected: anyone can access it. For example, if you create an application-scoped policy for an EAR and the EAR contains an EJB, the EJB will not be protected by the EAR's application-scoped policy.
This model is appropriate if developers and security administrators can closely coordinate their work, both upon initial deployment of the Web application or EJB and upon subsequent redeployments. Table 4-2 shows a typical scenario:
Table 4-2 Deployment Descriptors Only: Typical Scenario
Company A, Developer Company A, Admin/Deployer

Maps EJBs and/or Web URLs to roles in the Java EE DD.
Maps roles to principals in the WebLogic Server DD.
Turns application over to the Admin/Deployer.

Uses the WebLogic Server Administration Console to ensure that groups exist and are properly mapped to users.

Custom Roles Model

This security model uses policies defined in the Java EE DD and ignores any principal mappings in the WebLogic Server DD. The security administrator completes the role mappings using the Administration Console.
The model enables team members to focus on their areas of expertise. Web application and EJB developers need only to declare which URL patterns or EJB methods should be secured. Then the security administrator creates role mappings that fit within the existing hierarchy of roles and principals for a given realm.
If a developer changes policies in a deployment descriptor, WebLogic Server recognizes the change as soon as you redeploy the Web application or EJB. If an administrator changes role mappings, the changes take effect immediately without requiring a redeployment.
This model is appropriate if developers and administrators cannot closely coordinate their work or if role mappings change frequently. Table 4-3 shows a typical scenario:
Table 4-3 Customize Roles Only: Typical Scenario
Company A, ISV Developer or
Company B, Developer Company B, Admin/Deployer

Maps EJBs/URLs to roles in Java EE deployment descriptor.
Turns application over to Admin/Deployer

Uses the WebLogic Server Administration Console to define security roles.

Custom Roles and Policies Model

This security model offers unified and dynamic security management. It uses roles and policies that a security administrator has created using the Administration Console and ignores any roles and policies defined in deployment descriptors.
Instead of requiring developers to modify multiple deployment descriptors when organizational security requirements change, administrators can modify all security configurations from a centralized, graphical user interface. Users, groups, security roles, and security policies can all be defined using the Administration Console. As a result, the process of making changes based on updated security requirements becomes more efficient.
This model is appropriate if you require only that entire Web applications or EJBs be secured, but is less appropriate if you require fine-grained control of a large number of specific URL patterns or EJB methods. Such fine-grained control requires a developer to provide to administrators detailed information about the URL patterns or EJB methods that must be secured. If you require such fine-grained control, consider using the Custom Roles model (see Custom Roles Model).
The model also introduces a slight performance degradation because it checks permissions regardless of which URL a client requests or EJB method a client attempts to invoke.
Table 4-4 shows a typical scenario:
Table 4-4 Customize roles and Policies: Typical Scenario
Company A, Developer Company A, Admin/Deployer

Provides no mappings in the Java EE or WebLogic Server DD.
Turns application over to Admin/Deployer

Uses the WebLogic Administration Console to define roles and policies for EJBs and Web applications.

Advanced Model

WebLogic Server provides this model primarily for backwards compatibility with releases prior to 9.0.
You can configure the following behaviors for this model (see Understanding the Combined Role Mapping Enabled Setting):

Perform security checks for all URLs and EJB methods or only those that are protected in the deployment descriptors.
(Not applicable if you configure this model to perform security checks only for URLs and EJB methods that are secured in deployment descriptors.) Use only roles and policies defined in the deployment descriptors, or use only roles and policies defined in the realm's security providers, or import security data from deployment descriptors into the realm's authorization provider or role mapping provider databases.
Oracle provides the ability to import security data for the following tasks:

As a step toward migrating to full security administration using the Administration Console. The import feature assumes that you want to use the WebLogic Server Administration Console exclusively to secure Web applications and EJBs, but you want to use the security data in deployment descriptors as a baseline.
To reinitialize security configurations for Web application and EJB resources to their original state, as specified in the deployment descriptors.
Once the data is imported, you can use the Administration Console to modify the security data.

WARNING: Importing security data introduces risks to the integrity of your security data. Each time you import the data, the Security Service attempts to remove all associated data from the provider databases and re-imports data from the deployment descriptors. If you modified the imported security data, then your modifications could become invalid or could be removed. If you import security data, follow the recommendations in Manage security for Web applications and EJBs in the Administration Console Online Help.

(Not applicable if you configure this model to use only roles and policies defined in the realm's security providers.) Combine roles in parent applications with roles in the Web application or EJB, or override roles in parent applications.

If you change the configuration of this model, the change applies to all Web applications and EJBs that use this model. For example, you configure the Advanced model to perform security checks for all URLs and methods, and then you deploy several EJBs and configure them to use the Advanced model. The EJB container will request a security check any time a client tries to invoke any method in any of the several EJBs. If you then modify the Advance model to perform security checks only for the EJB methods that are protected in deployment descriptors, then the EJB container immediately begins to request security checks only for protected methods for the several EJBs.

Understanding the Advanced Security Model

This section applies only for those Web applications and EJBs that use the Advanced security model.
Three settings in the Administration Console configure the Advanced model: Check Roles and Policies, When Deploying Web Applications or EJBs, and Combined Role Mapping Enabled. Failure to understand these settings could result in incorrect or lost security data.
If you change the configuration of this model, the change applies to all Web applications and EJBs that use this model.
The following sections describe the settings for the Advanced security model:

Understanding the Check Roles and Policies Setting
Understanding the When Deploying Web Applications or EJBs Setting
How the Check Roles and Policies and When Deploying Web Applications or EJBs Settings Interact
Understanding the Combined Role Mapping Enabled Setting

Understanding the Check Roles and Policies Setting

The Check Roles and Policies setting determines whether the Security Service performs security checks for all URLs and EJB methods or only those that are protected in the deployment descriptors.
Set the value of Check Roles and Policies as follows:

To perform security checks only on Web application and EJB resources that have security specified in their associated deployment descriptors (DDs), select Web applications and EJBs Protected in DD.

This selection is analogous to the Deployment Descriptor Only security model: the Security Service uses only roles and policies defined in a Web application or EJB's deployment descriptors.
To perform security checks on all Web application and EJB resources, regardless of whether there are any security settings in the deployment descriptors for these WebLogic resources, select All Web applications and EJBs.

With this selection, you can also configure the When Deploying Web Applications or EJBs setting.

Understanding the When Deploying Web Applications or EJBs Setting

The When Deploying Web Applications or EJBs setting determines whether the Security Service ignores role and policy data in deployment descriptors or imports the data into role mapping and authorization provider databases each time you deploy a Web application or EJB.

This setting is valid only if you have set Check Roles and Policies to All Web applications and EJBs.
Set the value of When Deploying Web Applications or EJBs as follows:

To secure Web application and EJB resources using only the WebLogic Server Administration Console, select Ignore Roles and Policies From DD (Deployment Descriptors). At this point you can begin to use the Administration Console to secure the resources. See Create scoped security roles and Create policies for resource instances in Administration Console Online Help.
To import security data from the deployment descriptors, select Initialize Roles and Policies from DD.

WARNING: Importing security data introduces risks to the integrity of your security data. Each time you import security data, the Security Service attempts to remove all associated security data from the provider databases and re-imports data from the deployment descriptors. If you modified the imported security data, then your modifications could become invalid or could be removed. If you import security data, follow the recommended procedures in Manage security for Web applications and EJBs in the Administration Console Online Help.

How the Check Roles and Policies and When Deploying Web Applications or EJBs Settings Interact

Table 4-5 shows how to achieve the behavior you want from the WebLogic Security Service using different combinations of the Check Roles and Policies and When Deploying Web Applications and EJBs settings.
Table 4-5 Interaction Between the Check Roles and Policies Setting and the When Deploying Web Applications or EJBs Setting
If you want to control security for... and set security for Web application and EJB resources... then set Check Roles and Policies to... and set When Deploying Web Applications or EJBs to...
All Web application and EJB resources using only the Administration Console All Web applications and EJBs Ignore Roles and Policies from DD
All Web application and EJB resources by copying or reinitializing security data from the deployment descriptors into the configured Authorization and Role Mapping providers' databases when the Web application or EJB resource is deployed, then use one of the other techniques to modify security roles and security policies

Security data is copied/reinitialized each time the Web application or EJB resource is deployed.
All Web applications and EJBs Initialize Roles and Policies from DD Only on Web applications and EJB methods that are specified in the deployment descriptors (default configuration) using only the deployment descriptors Web applications and EJBs Protected in DD --

Understanding the Combined Role Mapping Enabled Setting

The Combined Role Mapping Enabled setting determines how the role mappings in the Enterprise Application, Web application, and EJB containers interact.
WebLogic Server provides this setting for backwards compatibility with 8.x versions. For all applications initially deployed in version 9.x, the default value for this setting is “true” (enabled). For all applications previously deployed in version 8.1 and upgraded to version 9.x, the default value is “false” (disabled). If either of the following is true, consider changing the default value for Combined Role Mapping Enabled:

You selected the Advanced security model for an 8.x application upgrade and want to use the combine role mapping behavior available in version 9.x.
You selected the Advanced security model for a 9.x application and want to use the role mapping behavior in version 8.x.

Table 4-6 compares how this setting affects security for Web applications and EJBs:
Table 4-6 How Combined Role Mapping Affects Security for Web Applications and EJBs
When Combined Role Mapping is disabled... When Combined Role Mapping is enabled...
Role mappings for each container are exclusive to other containers unless defined by the <externally-defined> descriptor element. Application role mappings are combined with EJB and Web application mappings so that all principal mappings are included. The Security Service combines the role mappings with a logical OR operator.
If one or more policies in the web.xml file specifies a role for which no role mapping exists in the weblogic.xml file, the Web application container assumes that the undefined role is the name of a principal. It therefore maps the assumed principal to the role name. For example, if the web.xml file contains the following stanza in one of its policies: <auth-constraint> <role-name>PrivilegedUser</role-name> </auth-constraint> but the weblogic.xml file has no role mapping for PrivilegedUser, then the Web application container creates an in-memory mapping that is equivalent to the following stanza: <security-role-assignment> <role-name>PrivilegedUser</role-name> <principal-name>
PrivilegedUser
</principal-name> </security-role-assignment> If one or more policies in the web.xml file specifies a role for which no mapping exists in the weblogic.xml file, the Web application container creates an empty map for the undefined role (that is, the role is explicitly defined as containing no principal). Therefore, no one can access URL patterns that are secured by such policies.
Role mappings for EJB methods must be defined in the weblogic-ejb-jar.xml file. Role mappings defined in the other containers are not used unless defined by the <externally-defined> descriptor element. If one or more policies in the ejb-jar.xml file specifies a role for which no mapping exists in the weblogic-ejb-jar.xml file, the EJB container creates an empty map for the undefined role (that is, the role is explicitly defined as containing no principal). Therefore, no one can access methods that are secured by such policies.

Usage Examples

The following examples show the differences in role mapping behaviors depending on whether Combined Role Mapping is enabled or disabled.
Example for EAR, WAR and EJB

MyAppEar contains MyAppWAR which contains MyEJB. Role to Principal mappings (p1 and p2) are as follows:

EAR descriptor, myRole = p1
WAR descriptor, myRole = p2
EJB-JAR descriptor, myRole = empty

When Combined Role Mapping is enabled, the role mappings would be:

For the Ear container, myRole maps to p1.
For the WAR container, myRole maps to p1 or p2.
For the EJB container, myRole maps to p1.

When Combined Role Mapping is disabled, the role mappings would be

For the Ear container, myRole maps to p1.
For the WAR container, myRole maps to p2.
For the EJB container: Must be externally-defined or the deployment fails.

Example for EAR and WAR

MyAppEar contains MyAppWAR. Role to Principal mappings are as follows:

In MyAppEAR descriptor, myRole = p1
In MyAppWAR descriptor, myRole = (none defined)

When Combined Role Mapping is enabled, the role mappings would be:

For the Ear container, myRole maps to p1.
For the WAR container, myRole maps to p1.

Note: The mapping is the same because of the combined role behavior.

When Combined Role Mapping is disabled, the role mappings would be

For the Ear container, myRole maps to p1.
For the WAR container, myRole maps to MyRole.

Note: The mapping is the same because if there is no mapping defined for the Web application, WebLogic Server copies the EAR mapping to the WAR mapping.

Securing Web Applications and EJBs

You choose a security model when you deploy each Web application or EJB, and your choice is immutable for the lifetime of the deployment. If you want to use a different model, delete and redeploy the Web application or EJB.
For information on using the Administration Console to deploy applications, choose a security model, modify roles and polices, and complete other related tasks, see Manage Security for Web Applications and EJBs in the Administration Console Help.
If you plan to use deployment descriptors to secure Web applications or EJBs, see “Using Declarative Security With Web Applications” and “Using Declarative Security With EJBs” in Programming WebLogic Security.

This Model...	Uses Roles and Policies From...	And Performs Security Checks...
Deployment Descriptor Only (Java EE standard)	The web.xml, weblogic.xml and ejb-jar.xml, weblogic-ejb-jar.xml deployment descriptors. If roles have been defined for the application that contains the Web application or EJB, all roles are combined using a logical OR operation.	Only when clients request URLs or EJB methods that are protected by a policy in the deployment descriptor.
Custom Roles	This model uses role mappings from a role mapping provider that you configure for the security realm. You can use the Administration Console to configure the provider. Any role mappings in the deployment descriptors are ignored. The model uses the policies that are defined in the web.xml and ejb-jar.xml deployment descriptors.	Only when clients request URLs or EJB methods that are protected by a policy in the deployment descriptor.
Custom Roles and Policies	A role mapping provider and an authorization provider that you configure for the security realm. You can use the Administration Console to configure the providers. Any role mappings or policies in the deployment descriptors are ignored.	For all URLs and EJB methods.
Advanced	Configurable. You can configure this model to use only security data from deployment descriptors, use only the data from security providers, or import security data from deployment descriptors into the security provider databases to provide a baseline for further modifications.	Configurable.

If you want to control security for...	and set security for Web application and EJB resources...	then set Check Roles and Policies to...	and set When Deploying Web Applications or EJBs to...
All Web application and EJB resources	using only the Administration Console	All Web applications and EJBs	Ignore Roles and Policies from DD
All Web application and EJB resources	by copying or reinitializing security data from the deployment descriptors into the configured Authorization and Role Mapping providers' databases when the Web application or EJB resource is deployed, then use one of the other techniques to modify security roles and security policies Security data is copied/reinitialized each time the Web application or EJB resource is deployed.

When Combined Role Mapping is disabled...	When Combined Role Mapping is enabled...
Role mappings for each container are exclusive to other containers unless defined by the <externally-defined> descriptor element.	Application role mappings are combined with EJB and Web application mappings so that all principal mappings are included. The Security Service combines the role mappings with a logical OR operator.
If one or more policies in the web.xml file specifies a role for which no role mapping exists in the weblogic.xml file, the Web application container assumes that the undefined role is the name of a principal. It therefore maps the assumed principal to the role name. For example, if the web.xml file contains the following stanza in one of its policies: <auth-constraint> <role-name>PrivilegedUser</role-name> </auth-constraint> but the weblogic.xml file has no role mapping for PrivilegedUser, then the Web application container creates an in-memory mapping that is equivalent to the following stanza: <security-role-assignment> <role-name>PrivilegedUser</role-name> <principal-name> PrivilegedUser </principal-name> </security-role-assignment>	If one or more policies in the web.xml file specifies a role for which no mapping exists in the weblogic.xml file, the Web application container creates an empty map for the undefined role (that is, the role is explicitly defined as containing no principal). Therefore, no one can access URL patterns that are secured by such policies.
Role mappings for EJB methods must be defined in the weblogic-ejb-jar.xml file. Role mappings defined in the other containers are not used unless defined by the <externally-defined> descriptor element.	If one or more policies in the ejb-jar.xml file specifies a role for which no mapping exists in the weblogic-ejb-jar.xml file, the EJB container creates an empty map for the undefined role (that is, the role is explicitly defined as containing no principal). Therefore, no one can access methods that are secured by such policies.