Moving to Production Mode

Tutorial 19: Copying and Reinitializing Security Configurations

This tutorial describes how to copy a security configuration from deployment descriptors into the configured Authorization and Role Mapping providers' databases, so that you can use the Administration Console for subsequent modifications to security policies and security roles. It also describes how to reinitialize a security configuration using the original deployment descriptors.

The tutorial includes the following sections:

- Prerequisites
- Procedure
- Best Practices
- The Big Picture
- Related Reading

Prerequisites

Before starting this tutorial:

- Create MedRecDomain and MedRecServer, and start MedRecServer. See Tutorial 1: Creating a WebLogic Domain and Server Instance for Development.
- Obtain the "AdminWebApp Web Application" (available under Code Samples for WebLogic Server 8.1 on the dev2dev Web site), and unzip the adminWebApp.zip file to a temporary directory (for example, C:\adminWebApp).
- If you deployed the Enterprise Application named MedRecEAR as part of any prior tutorial, use the Administration Console to delete it.
- Read Using the Combined Technique to Secure Your URL (Web) and Enterprise JavaBean (EJB) Resources in Securing WebLogic Resources.

Procedure

This tutorial consists of three main steps:

- Step 1: Copy a security configuration.
- Step 2: Modify a security policy using the Administration Console.
- Step 3: Reinitialize a security configuration.

Step 1: Copy a security configuration.

To copy security configurations for the adminWebApp Web application from its deployment descriptors into the configured Authorization and Role Mapping providers' databases, follow these steps:

- Step 1: Specify security realm settings and deploy the Web application.
- Step 2: Verify the copied security policies (optional).
- Step 3: Verify the copied security roles (optional).
- Step 4: Revert the On Future Redeploys setting.

Step 1: Specify security realm settings and deploy the Web application.

1. In the navigation tree at the left side of the Administration Console, expand Security->Realms.

2. Click the myrealm security realm.

3. On the General tab, select All Web Applications and EJBs as the value for the Check Roles and Policies drop-down menu.

   This setting causes the WebLogic Security Service to perform security checks on all URL (Web) and EJB resources. For more information, see Understanding How to Check Security Roles and Security Policies in Securing WebLogic Resources.

   If All Web Applications and EJBs was already selected as the value of the Check Roles and Policies drop-down menu, just continue to step 4.

4. Select Initialize Roles and Polices From DD from the On Future Redeploys drop-down menu.

   This setting causes WebLogic Server to copy security configurations for URL (Web) and EJB resources from deployment descriptors into the configured Authorization and Role Mapping providers' databases each time you deploy the resource. For more information, see Understanding What to Do on Future Redeploys of the WebLogic Resource in Securing WebLogic Resources.

5. Click Apply to save your changes.

6. If you had to set the Check Roles and Policies drop-down menu to All Web Applications and EJBs in step 2 (that is, it was not already set this way), restart the server. (For help, see "Starting and Stopping WebLogic Servers: Quick Reference" in the WebLogic Server Administration Guide.)

   If you did not have to modify the value of the Check Role and Policies drop-down menu in step 3, continue to step 7 without restarting the server.

7. Deploy the adminWebApp Web Application module and target it to the MedRecServer.

   For instructions about how to deploy Web Applications, see Deploying WebLogic Server Applications.

Step 2: Verify the copied security policies (optional).

1. Open the web.xml deployment descriptor for the adminWebApp Web application, and record the content of any <url-pattern> and <http-method> elements, as well as any <role-name> subelements of the <auth-constraint> element. Listing 1 shows the relevant portions of the web.xml deployment descriptor file in bold font.

   Listing 1: The adminWebApp Web Application web.xml Deployment Descriptor

   >     <!DOCTYPE web-app (View Source for full doctype...)>

   >     <web-app>

   >           ...

   >           <security-constraint>

   >                 <web-resource-collection>

   >                       <web-resource-name>images</web-resource-name>

   >                       <url-pattern>*.gif</url-pattern>

   >                 </web-resource-collection>

   >           </security-constraint>

   >           <security-constraint>

   >                 <web-resource-collection>

   >                       <web-resource-name>UnsecureLoginAction

   >                       </web-resource-name>

   >                       <url-pattern>login.do</url-pattern>

   >                 </web-resource-collection>

   >           </security-constraint>

   >           <security-constraint>

   >                 <web-resource-collection>

   >                       <web-resource-name>UnsecureLoginPages

   >                       </web-resource-name>

   >                       <url-pattern>Login.jsp</url-pattern>

   >                 </web-resource-collection>

   >           </security-constraint>

   >           <security-constraint>

   >                 <web-resource-collection>

   >                       <web-resource-name>AdminActions</web-resource-name>

   >                       <description>These pages are only accessible by authorized
   >     administrators.</description>

   >                       <url-pattern>*.do</url-pattern>

   >                       <url-pattern>*.jsp</url-pattern>

   >                       <http-method>POST</http-method>

   >                       <http-method>GET</http-method>

   >                 </web-resource-collection>

   >                 <auth-constraint>

   >                       <description>These are the roles who have access.</description>

   >                       <role-name>admin</role-name>

   >                 </auth-constraint>

   >                 ...

   >           </security-constraint>

   >           ...

   >           <security-role>

   >                 <description>An administrator</description>

   >                 <role-name>admin</role-name>

   >           </security-role>

   >     </web-app>

2. In the navigation tree at the left side of the Administration Console, expand Web Application Modules, then right-click adminWebApp.

3. From the menu, select Define Security Policy to display the General tab.

   There are five hyperlinked URL patterns that correspond to those you recorded in step 1 listed under the Already Defined URL Patterns heading.

4. Click the hyperlinked URL pattern *.do to display the Policy Editor page.

5. Using the Methods drop-down menu, select POST.

   The Caller is Granted the Role Policy Condition is highlighted and the Policy Statement list box reads:

   Caller is Granted the Role

   admin

   If you click a hyperlinked URL pattern that did not have a corresponding <http-method> element in the web.xml deployment descriptor, the Policy Statement list box displays the appropriate security policy when the Methods drop-down menu contains the value ALL. For example, the security policy for the URL pattern *.gif from Listing 1 can be viewed when the Methods drop-down reads ALL.

   If the URL pattern does not have a corresponding <auth-constraint> element in the web.xml deployment descriptor, the security policy for that URL pattern will be created using the Anonymous global role (for example, the security policy for the URL pattern *.gif from Listing 1). For more information about default global roles, see Default Global Roles in Securing WebLogic Resources.

6. Repeat steps 2 - 5 to verify multiple security policies.

Step 3: Verify the copied security roles (optional).

1. Open the weblogic.xml deployment descriptor for the adminWebApp Web Application, and record the content of any <security-role-assignment> elements, specifically focusing on the <role-name> and <principal-name> subelements. Listing 2 shows the relevant portions of the weblogic.xml deployment descriptor file in bold font.

   Listing 2: The adminWebApp Web Application weblogic.xml Deployment Descriptor

   >     <!DOCTYPE weblogic-web-app (View Source for full doctype...)>

   >           <weblogic-web-app>

   >                 <context-root>admin</context-root>

   >                 <security-role-assignment>

   >                       <role-name>admin</role-name>

   >                       <principal-name>admin</principal-name>

   >                 </security-role-assignment>

   >           </weblogic-web-app>

2. In the navigation tree at the left side of the Administration Console, right-click on the adminWebApp Web Application.

3. From the menu, select Define Scoped Role to display the General tab.

4. Click the hyperlinked URL pattern /*.

   The Scoped Roles page displays all the scoped roles for this Web Application that are currently defined in the WebLogic Role Mapping provider's database, including the scoped role called admin.

   Security roles obtained from deployment descriptors are always copied into the configured Role Mapping provider's database as scoped roles, with a URL pattern of /*.

5. Click the hyperlinked scoped role admin.

6. Select the Conditions tab.

   The Role Statement list box contains a Role Statement based on the content of the deployment descriptor's corresponding <principal-name> element, which in this case is a user or group called admin.

Step 4: Revert the On Future Redeploys setting.

Caution: You must perform this step. Failure to revert this setting may result in inconsistent security configurations when your URL (Web) resources are redeployed. If you do not perform this step or perform this step incorrectly, you see the following message the next time you load the Policy Editor page:

The information presented below may not be accurate. To ensure that you are viewing accurate information, you may need to delete and redeploy your WebLogic resources.

1. In the navigation tree at the left side of the Administration Console, expand Security->Realms.

2. Click the myrealm security realm.

3. On the General tab, select Ignore Roles and Polices From DD as the value for the On Future Redeploys drop-down menu.

   This setting indicates that you will set security for URL (Web) and EJB resources using the Administration Console, not deployment descriptors. For more information, see Understanding What to Do on Future Deploys of the WebLogic Resource in Securing WebLogic Resources.

4. Click Apply to save your changes.

Step 2: Modify a security policy using the Administration Console.

1. In the navigation tree at the left side of the Administration Console, expand Web Application Modules, then right-click adminWebApp.

2. From the menu, select Define Security Policy to display the General tab.

   Five hyperlinked URL patterns correspond to those you recorded in Step 2: Verify the copied security policies (optional). listed under the Already Defined URL Patterns heading.

3. Click the hyperlinked URL pattern *.do to display the Policy Editor page.

4. Using the Methods drop-down menu, select POST.

   The Caller is Granted the Role Policy Condition is highlighted and the Policy Statement list box reads:

   Caller is Granted the Role

   admin

5. In the Policy Condition list box, highlight the Hours of Access are Between policy condition.

6. Click Add, then click OK in the Time Constraint window to select the default start and end times.

   The Policy Statement list box reads as follows:

   Caller is Granted the Role

   developers

   and Hours of Access are Between

   08:00:00 and 19:00:00

7. Click Apply to save your changes.

Step 3: Reinitialize a security configuration.

To reinitialize security configurations for the adminWebApp Web Application from its deployment descriptors, follow these steps:

- Step 1: Modify the On Future Redeploys setting.
- Step 2: Redeploy the adminWebApp Web application.
- Step 3: Verify that the security configuration has been reinitialized (optional).
- Step 4: Revert the On Future Redeploys setting.

Step 1: Modify the On Future Redeploys setting.

1. In the navigation tree at the left side of the Administration Console, expand Security->Realms.

2. Click the myrealm security realm.

3. On the General tab, from the On Future Redeploys drop-down menu, select Initialize Roles and Polices From DD.

   This setting means that WebLogic Server will copy security configurations for URL (Web) and EJB resources from deployment descriptors into the configured Authorization and Role Mapping providers' databases each time you deploy the resource. For more information, see Understanding What to Do on Future Redeploys of the WebLogic Resource in Securing WebLogic Resources.

   If All Web Applications and EJBs was already selected as the value of the Check Roles and Policies drop-down menu, just continue to step 4.

4. Click Apply to save your changes.

Step 2: Redeploy the adminWebApp Web application.

1. In the navigation tree at the left side of the Administration Console, expand Deployments->Web Application Modules.

2. Click the adminWebApp Web application.

   A table that lists all the Web application or EJB modules appears in the right pane.

3. Click the trash can icon that is located in the same row as the adminWebApp Web Application.

4. Click Yes, then the Continue link to delete the adminWebApp Web Application.

   The adminWebApp Web Application no longer appears in the table.

5. Click the Deploy button that corresponds to MedRecServer, to which you targeted the adminWebApp Web Application module.

6. Re-deploy the adminWebApp Web Application, targeting it to MedRecServer.

   Note: For instructions about how to deploy Web Application and EJB modules, see Deploying WebLogic Server Applications.

Step 3: Verify that the security configuration has been reinitialized (optional).

1. In the navigation tree at the left side of the Administration Console, right-click adminWebApp.

2. From the menu, select Define Security Policy to display the General tab.

   Five hyperlinked URL patterns correspond to those you recorded in step 1 listed under the Already Defined URL Patterns heading.

3. Click the hyperlinked URL pattern *.do to display the Policy Editor page.

4. Using the Methods drop-down menu, select POST.

   The Caller is Granted the Role Policy Condition is highlighted and the Policy Statement list box reads:

   Caller is Granted the Role

   admin

   The policy statement you created using the Hours of Access are Between policy condition in Step 2: Modify a security policy using the Administration Console. is gone, because it was not defined in the deployment descriptor from which you just initialized the security configuration.

Step 4: Revert the On Future Redeploys setting.

Caution: You must perform this step. Failure to revert this setting may result in inconsistent security configurations when your URL (Web) resources are redeployed. If you do not perform this step or perform this step incorrectly, you see the following message the next time you load the Policy Editor page:

The information presented below may not be accurate. To ensure that you are viewing accurate information, you may need to delete and redeploy your WebLogic resources.

1. In the navigation tree at the left side of the Administration Console, expand Security->Realms.

2. Click the myrealm security realm.

3. On the General tab, select Ignore Roles and Polices From DD as the value for the On Future Redeploys drop-down menu.

   Note: This setting means that you will set security for URL (Web) and EJB resources using the Administration Console, not deployment descriptors. For more information, see Understanding What to Do on Future Deploys of the WebLogic Resource in Securing WebLogic Resources.

4. Click Apply to save your changes.

Best Practices

- Do not use blank spaces, commas, hyphens, or any characters in this comma-separated list for user, group, or security role names: \t, < >, #, |, &, ~, ?, ( ), { }. User, group, and security role names are case sensitive. The proper syntax for a security role name is as defined for an Nmtoken in the Extensible Markup Language (XML) recommendation. The BEA convention is that group names are plural, and security role names are singular.
- Remember that redeploying a WebLogic resource with the On Future Redeploys drop-down menu set to Ignore Roles and Policies From DD does not affect the security configuration (that is, security policies or security roles) of the resource.
- When the On Future Redeploys drop-down menu is set to Initialize Roles and Policies From DD, any redeploy of a WebLogic resource will update the security configuration. This includes targeting a new server and setting a server with an application or module targeted to it to bounce. Take care when altering security policies and security roles that are specified in a deployment descriptor when the On Future Redeploys drop-down menu is set to Initialize Roles and Policies From DD.
- If you initialize a security configuration from deployment descriptors and then customize security policies and security roles using the Administration Console, make sure that you never boot a server when the value of the On Future Redeploys drop-down menu is Reinitialize Roles and Policies From DD. If you do, then all the security policy and security role customizations you performed using the Administration Console for all of your Web applications (and EJBs) will be lost.
- Always have the On Future Redeploys set to Ignore Roles and Policies From DD except when:

- You are about to deploy a new Web Application or EJB module

- You want to redeploy a Web Application or EJB module and initialize its security configuration (security policies and security roles).

The Big Picture

This tutorial shows you how to copy the security configuration for a Web Application from its deployment descriptors into the configured Authorization and Role Mapping providers' databases, so that you can use the Administration Console for subsequent modifications to the Web Application's security roles and security policies. The same example shows you how to reinitialize the security configuration using the Web Application's original deployment descriptors.

The full MedRec application uses the principles described in Tutorial 17: Securing Application and URL (Web) Resources Using the Administration Console and Tutorial 18: Securing Enterprise JavaBean (EJB) Resources Using the Administration Console (as well as programmatic security) to secure EJB resources for both MedRec administrators and patients.

Related Reading

- Securing WebLogic Resources
- Tutorial 17: Securing Application and URL (Web) Resources Using the Administration Console
- Tutorial 18: Securing Enterprise JavaBean (EJB) Resources Using the Administration Console