Simplified ADF 11g Application Credential and Policy Migration to Standalone WebLogic Servers

Abstract

This paper outlines how to simplify the process of migrating credentials and policies of an ADF 11g application to a standalone WebLogic server for testing or production use.

Contents

1 Introduction

JDeveloper 11g automatically migrates identities, credentials and policies when it deploys an application to the integrated WebLogic server (WLS), which is the one used by JDeveloper whenever you run or debug a Java EE application from inside the IDE. However, automatic security migration is not available for deployment to a standalone WLS, for example the one your team might use for test or production use. This section explains briefly what credentials, identities, and policies are, helps you understand whether your application depends on them, and highlights the key use cases for which this article provides a simplified approach to migrate credentials and policies to a standalone WebLogic server.

1.1 What Are Credentials, Identities, and Policies?

When building Oracle ADF web-based applications, you will typically use a combination of security features like:

• credentials — encrypted passwords for database and other connections used by the data controls in your application
• identities — users who are allowed to use the application and the roles to which they belong
• policies — grants that affect which roles are allow to perform certain operations in your application

1.2 How Do I Know If My Application Depends on Any Credentials, Identities, or Policies?

Even the simplest ADF application that uses the default JDBC URL connection type to reference an Application Resources database connection for its application module data control depends on at least one credential entry for the connection's encrypted password. If the application includes data controls that reference other kinds of Application Resources connections — for example a Web Services data control, a URL data control, or others — then it will depend on other credentials, too. In contrast, an ADF application whose data control provider is configured to use a container-provided JDBC Datasource by JNDI name like java:comp/env/SomeConnectionNameDS and which does not use any additional data controls requiring their own connection credentials, would not have any credential dependencies.

If the application is configured to use authentication, then it will depend on identities at runtime to secure access to some or all of the pages in the application to appropriate roles and the users who belong to them. Furthermore, if the application using authentication also takes advantage of ADF authorization, then will depend in addition on security policies that grant access to particular operations to appropriate roles.

1.3 Overview of Simplified Credential and Policy Migration to Standalone WLS

JDeveloper 11g includes the Oracle Platform Security Services command-line tool for migrating credentials and policy to standalone WLS. This tool comprises a set of scripts shipped with JDeveloper 11g in the MIDDLEWARE_HOME/jdeveloper/modules/oracle.jps_11.1.1/scripts directory, which are designed to be used in concert with the WebLogic Scripting Tool (WLST) utility. These scripts are explained in detail in the JDeveloper 11g documentation in the Migrating the Security Repository to a Production Environment topic of the Developing Secure Applications section of the JDeveloper online help. However, since many users may find the scripts complicated to use, this document describes a simplified approach to achieve the two most common use cases:

• Migrating the credentials in an application's cwallet.sso file to the standalone WebLogic domain's cwallet.sso file
• Migrating the security policies in an application jazn-data.xml file to the standalone WebLogic domain's system-jazn-data.xml file.

2 Prerequisites

In order to use the tips in this document you need the following prerequisites:

• A standalone WebLogic server (WLS) for deployment

  Steps to accomplish this are described in detail in Appendix 1 below.

• Apache Ant is available in your system path

  JDeveloper 11g ships with Apache Ant in the MIDDLEWARE_HOME/jdeveloper/ant directory, so one way to meet this prerequisite is to add MIDDLEWARE_HOME/jdeveloper/ant/bin to your system path.

3 Migrating Credentials and Policies to Standalone WebLogic

The techniques described in this section simplify migrating credentials and policies from an application to a standalone WebLogic server.

3.1 Setting Up Standalone WebLogic Server for Simplified Application Credentials and Policy Migration

To migrate credentials and policies from an application to a standalone WebLogic server, do the following:

1. Setup the Domain Environment

   Run the MIDDLEWAREHOME/user_projects/domains/domainname/bin/setDomainEnv script to setup required environment variables. Among other variables, this sets the DOMAIN_HOME environment variable to point to the home directory of the domain to which you want to migrate credentials and policies.

2. Create a Migration Directory Under the Domain Home

   To create a migration directory used by the scripts, do the following:

   • cd %DOMAIN_HOME%
   • mkdir migration

3. Copy Scripts to Migration Directory

   • Use your browser's "Save link as..." command (or equivalent) to download this build.xml file
   • Similarly, download this jps-config.xml file.
   • Copy both the build.xml and jps-config.xml files downloaded above to the %DOMAIN_HOME%/migration directory.

3.2 Migrating Application Credentials to Standalone WebLogic

To migrate an application's credentials from its cwallet.sso file to the %DOMAIN_HOME%/config/oracle/cwallet.sso file, run the following commands:

$ cd %DOMAIN_HOME%/migration
$ ant -Dapp-credstore=APPWORKSPACEDIR/src/META-INF/cwallet.sso

3.3 Migrating Application Policies to Standalone WebLogic

To migrate an application's policies from its jazn-data.xml file to the %DOMAIN_HOME%/config/oracle/system-jazn-data.xml file, run the following commands. While formatted here for readability, you should enter the ant command on a single line. You can omit -DdstApp=DEPLOYAPPNAME if the deployed application name is the same as the source application name you supplied in the -DsrcApp=APPNAME argument.

$ cd %DOMAIN_HOME%/migration
$ ant -Dapp-jazn-data=APPWORKSPACEDIR/src/META-INF/jazn-data.xml
      -DsrcApp=APPNAME
      -DdstApp=DEPLOYAPPNAME

After running this command, see Manual Changes Required to Policy Grantee Class Names After Migration below for manual changes required.

3.4 Migrating Both Credentials and Application Policies to Standalone WebLogic

To migrate both an application's credentials and policies, run the following commands. While formatted here for readability, you should enter the ant command on a single line. You can omit -DdstApp=DEPLOYAPPNAME if the deployed application name is the same as the source application name you supplied in the -DsrcApp=APPNAME argument.

$ cd %DOMAIN_HOME%/migration
$ ant -Dapp-credstore=APPWORKSPACEDIR/src/META-INF/cwallet.sso
      -Dapp-jazn-data=APPWORKSPACEDIR/src/META-INF/jazn-data.xml
      -DsrcApp=APPNAME
      -DdstApp=DEPLOYAPPNAME

After running this command, see Manual Changes Required to Policy Grantee Class Names After Migration below for manual changes required.

3.5 Manual Changes Required to Policy Grantee Class Names After Migration

Application policy grantee class names must be manually corrected in system-jazn-data.xml after migration. The application's src/META-INF/jazn-data.xml principal and role classes are Oracle Platform Security Services class names. These must be changed to the corresponding WebLogic server class names after policy migration to %DOMAIN_HOME%/config/oracle/system-jazn-data.xml. Please correct the class names in system-jazn-data.xml as follows:

• For Role (Group) Grantees

  • Change: oracle.security.jps.internal.core.principals.JpsXmlEnterpriseRoleImpl
  • To: weblogic.security.principal.WLSGroupImpl

• For User Grantees

  • Change: oracle.security.jps.internal.core.principals.JpsXmlUserImpl
  • To: weblogic.security.principal.WLSUserImpl

3.6 Known Limitation on Credential Migration

Credentials connection names migrated to the standalone WebLogic server domain credential store must be unique. For example, you can have only one connection named Connection1 in the %DOMAIN_HOME%/config/oracle/cwallet.sso file. If a Connection1 credentials key already exists in the credential store, migrating a new Connection1 will overwrite the existing Connection1 credentials. This is not a problem if both Connnection1 credentials are identical. However, if they are different then applications that use the original Connection1 will fail with incorrect credentials.

4 Defining Required Application Identities on Standalone WLS

While JDeveloper 11g migrates identities for an application to the integrated WebLogic server for single-user running and debugging purposes, neither the JDeveloper 11g IDE nor the Oracle Platform Security Services migration tool supports identity store migration to a standalone WLS identity store. You must use WebLogic admin console — by default available at http://servername:7001/console — to create users and groups required by the deployed app prior to running the deployed application. Of course, an alternative would be to create a custom WebLogic Scripting Tool (WSLT) script to accomplish the job.

Appendix 1: Installing and Configuring a Standalone WebLogic Server for ADF Application Deployment

1. Run the JDeveloper 11g Installer

   java -jar jdevstudio11110install.jar

2. Enter Directory Name for Standalone WebLogic Server Installation

   On the Choose Middleware Home Directory page of the Oracle Installer, as shown in Figure 1, ensure the Create a new Middleware Home radio group button is selected. In the Middleware Home Directory field, enter a directory name to use for the standalone WebLogic server installation and then click (Next).

   
   Figure 1: Choosing a Middleware Home Directory for a Standalone WLS

3. Select a Custom Install Type

   On the Choose Install Type page, as shown in Figure 2, choose a Custom install, then click (Next).

   
   Figure 2: Choosing a Custom Install Type

4. Choose the Required Products for Installation

   On the Choose Products and Components page, as shown in Figure 3, uncheck the JDeveloper Studio checkbox since it is not required for a standalone WLS installation, then press (Next).

   
   Figure 3: Deselecting JDeveloper Studio Since It's Not Required for Standalone WLS

5. Confirm Java Developer's Kit (JDK) Selection

   On the JDK Selection, as shown in Figure 4, confirm the directory where the JDK resides that you want to use to run the standalone WLS. If the ./bin directory of a Java Developer's Kit (JDK) was already available in your system path, then it will appear in the Local JDK list, otherwise you'll need to click the (Browse...) button to select the desired directory using the file chooser. Then click (Next)

   
   Figure 4: Confirming a Java Developer's Kit (JDK) to Use

6. Confirm the Product Installation Directories

   On the Confirm Product Installation Directories page, double-check the product installation directories and click (Next) if they are ok. If necessary, you can return to previous steps to adjust the WLS home directory name.

7. If Appropriate, Choose Whether to Install a Windows Service

   If you're installing on Windows, the Install Windows Service page appears. Choose whether you want to install a node manager Windows service to enable remote start and health monitoring of the standalone WLS you are installing. You can safely leave the default of "No", and decide later to enable this. Then click (Next).

8. If Appropriate, Choose a Shortcut Location

   If you're installing on Windows, the Choose Shortcut Service page appears. Choose whether you want to create a shortcut for all users or only the current user. Then click (Next).

9. Confirm the Installation Summary to Begin

   On the Installation Summary page, click (Next) to begin the installation.

10. When Installation Completes, Launch the Quickstart

    After some time, when the Installation Complete page appears, ensure the Run Quickstart checkbox is checked and click (Done).

11. Configure a Domain with Oracle ADF

    When the Quickstart dialog appears, as shown in Figure 5, click the Configure domains for Oracle ADF item text to start the Oracle WebLogic Configuration Wizard.

    
    Figure 5: Launching the Domain Configuration Wizard

12. Create a New WebLogic Domain

    On the Welcome page of the Oracle WebLogic Configuration Wizard, ensure the Create a new WebLogic domain radio group is checked and click (Next).

13. Enable ADF for the New Domain

    On the Select Domain Source page, as shown in Figure 6, ensure the Generate domain configured automatically to support the following products radio group is selected, and check the Application Development Framework checkbox nested inside it, then click (Next).

    
    Figure 6: Enabling ADF for the New Domain

14. Configure Administrator Username and Password

    On the Configure Administrator Username and Password page, enter the username for the administrator and the password twice, then press (Next).

15. Configure Server Start Mode and JDK

    On the Configure Server Start Mode and JDK page, select a sever startup mode and JDK directory, then press (Next).

16. Skip Customizing Environment and Services Settings

    On the Customize Environment and Services Settings page, for now leave the default No radio group selected and click (Next).

17. Create the WebLogic Domain

    On the Create WebLogic Domain page, choose a domain name or leave the default name of base_domain, then click (Create). After a short delay, your domain is created with ADF pre-installed. Click (Done) to exit.

    
    

    TIP:	When you define an application server connection in JDeveloper to deploy to this standalone server, you'll need to remember the name of the domain you chose in this step.

    
    

18. Starting Up and Shutting Down the Standalone Server

    The scripts to startup and shutdown the standalone WLS server you just created live in the MIDDLEWAREHOME/user_projects/domains/domainname/bin directory. Run the startWebLogic script from the command-line to start the server, and the stopWebLogic script to stop it.

Revision History