3 Installing and Configuring a Database

Oracle Identity Manager requires a database. You must install and configure your database before you begin the Oracle Identity Manager installation. Refer to the topics that apply to your database:

• Using an Oracle Database for Oracle Identity Manager

• Using Oracle RAC Databases for Oracle Identity Manager

• Using a Microsoft SQL Server Database for Oracle Identity Manager

3.1 Using an Oracle Database for Oracle Identity Manager

To use Oracle Database as your database, you must perform the tasks described in the following sections:

• Installing Oracle Database

• Creating an Oracle Database

• Preparing the Oracle Database

3.1.1 Installing Oracle Database

Install Oracle9i Database or Oracle Database 10g release 4 by referring to the documentation delivered with Oracle Database. See Oracle Identity Manager Readme for information about supported versions. Oracle recommends using the Basic installation.

Note:

If you select Custom installation, then you must include the JVM option, which is required for XA transaction support.

3.1.2 Creating an Oracle Database

You must create a new Oracle database instance for Oracle Identity Manager. When creating the database, ensure that you configure the Oracle JVM feature and enable query rewrite.

Note:

Oracle recommends that you increase the number of connections allowed to the Oracle Database. For this, you must increase the value of the processes parameter as follows:

1. Log in as the database administrator and then run the following query:

   ALTER SYSTEM SET PROCESSES = 300 SCOPE = SPFILE;
   

2. Restart the database for the changes to take effect.

You can use the Database Configuration Assistant (DBCA) tool to create the database. To configure the Oracle JVM feature, select the Oracle JVM feature on the Standard Database Features page of the DBCA.

To enable the database for query rewrite, set the initialization parameters QUERY_REWRITE_ENABLED to TRUE and QUERY_REWRITE_INTEGRITY to TRUSTED in the All Initialization Parameters field of the DBCA.

Note:

For the Oracle Identity Manager installation, Oracle recommends that you configure a minimum block size of 8K for Oracle Database.

See Oracle Database documentation for detailed instructions on creating a database instance.

3.1.2.1 Configuring the Database for Globalization Support

For globalization support for Oracle Identity Manager, Oracle recommends configuring the database for Unicode. To configure the database for Unicode:

1. Select AL32UTF8 in the Character Sets tab of the DBCA. This character set supports the Unicode standard.

2. Set the NLS_LENGTH_SEMANTICS initialization parameter to CHAR in the All Initialization Parameters field of the DBCA.

See Also:

Oracle Identity Manager Globalization Guide for information about globalization support for Oracle Identity Manager

3.1.3 Preparing the Oracle Database

After you install Oracle Database and created a database instance, you must prepare it for Oracle Identity Manager by completing the following tasks:

• Verify that query rewrite is enabled.

  Note:

  Query rewrite is applicable only if you are using Oracle Database Enterprise Edition.

• Enable XA transactions support.

  Note:

  A Java Virtual Machine (JVM) is required to enable XA transaction support. If you did not install the Oracle JVM component during Oracle Database installation, then you must install it now. See the Oracle Database documentation for specific instructions.

• Create at least one tablespace for storing Oracle Identity Manager data.

• Create a database user account for Oracle Identity Manager.

You can perform the preceding tasks to prepare Oracle Database for Oracle Identity Manager by running one of the following scripts:

• On Microsoft Windows, run the following:

  prepare_xl_db.bat

• On UNIX, run the following:

  prepare_xl_db.sh

These scripts are located in the /installServer/Xellerate/db/oracle/ directory.

Apply the following guidelines when you run this script:

• The script must be run by a user who has DBA privileges. For example, the oracle user on UNIX typically holds these privileges.

• The script must be run on the computer on which the database resides.

The following sections describe how to prepare the Oracle database for Oracle Identity Manager.

Note:

Perform the steps associated with the operating system on the computer hosting the Oracle database.

• Preparing the Database on UNIX

• Preparing the Database on Microsoft Windows

• Evaluating Script Results

3.1.3.1 Preparing the Database on UNIX

To prepare the database on UNIX:

1. Copy the prepare_xl_db.sh and xell_db_prepare.sql scripts from the distribution CD to a directory on the computer hosting your database on which you (as the account user performing this task) have write permission.

2. Run the following command to enable permission to run the script:

   chmod 755 prepare_xl_db.sh

3. Run the prepare_xl_db.sh script by entering the following command:

   ./prepare_xl_db.sh

4. Provide information appropriate for your database and host computer when the script prompts you for the following items:

   • Location of your Oracle home (ORACLE_HOME)

   • Name of your database (ORACLE_SID)

   • Name of the Oracle Identity Manager database user to be created

   • Password for the Oracle Identity Manager database user

   • Name of the tablespace to be created for storing Oracle Identity Manager data

   • Directory in which to store the data file for the Oracle Identity Manager tablespace

   • Name of the data file (do not append the .dbf extension)

   • Name of the temporary tablespace

5. Check the prepare_xl_db.lst log file located in the directory from which you ran prepare_xl_db.sh to see the execution status and additional information.

   Note:

   If you encounter errors after running the prepare_xl_db.sh script, run the following command to ensure that prepare_xl_db.sh is executable on UNIX and Linux and then run the prepare_xl_db.sh script again.

   $ dos2unix prepare_xl_db.sh
   

3.1.3.2 Preparing the Database on Microsoft Windows

To prepare the database on Microsoft Windows:

1. Copy the scripts prepare_xl_db.bat and xell_db_prepare.sql from the distribution CD to a directory on the computer hosting your database on which you (as the account user performing this task) have write permission.

2. Open a command window, navigate to the directory in which you copied the scripts, and then run prepare_xl_db.bat with the following arguments:

   prepare_xl_db.bat ORACLE_SID ORACLE_HOME
   XELL_USER XELL_USER_PWD TABLESPACE_NAME
   DATAFILE_DIRECTORY DATAFILE_NAME
   XELL_USER_TEMP_TABLESPACE SYS_USER_PASSWORD
   

   For example:

   prepare_xl_db.bat XELL C:\oracle\ora92 xladm xladm
   xeltbs C:\oracle\oradata xeltbs_01 TEMP manager
   

   Table 3-1 lists the options used in the preceding example of prepare_xl_db.bat.

   Table 3-1 Options for the prepare_xl_db.bat Script

   Argument	Description
   XELL	Name of the database
   C:\oracle\ora92	Directory in which Oracle Database is installed
   xladm	Name of the Oracle Identity Manager user to be created
   xladm	Password for the Oracle Identity Manager user
   xeltbs	Name of the tablespace to be created
   C:\oracle\oradata	Directory where the data files will be placed
   xeltbs_01	Name of the data file (do not include the .dbf extension)
   TEMP	Name of the temporary tablespace that already exists in the database
   manager	Password for the SYS user

   
   

3. Check the prepare_xell_db.lst log file located in the directory from which you ran prepare_xl_db.bat to see the execution status and additional information.

3.1.3.3 Evaluating Script Results

If the script returns a message indicating successful execution, you can continue to the next task, which is installing Oracle Identity Manager.

If the script does not succeed, you must manually fix all fatal (nonrecoverable) errors so that the database is prepared successfully.

You can ignore all non-fatal errors. For example, when the script tries to drop a non-existent view, it will return the error:

ORA-00942: table or view does not exist

Look for errors in the log file and ignore or resolve them on an individual basis. Remember that you must successfully prepare the database for Oracle Identity Manager before you can install Oracle Identity Manager.

3.1.4 Removing Oracle Identity Manager Entries from an Oracle Database

To remove Oracle Identity Manager entries from an Oracle database after removing (deinstalling) the Oracle Identity Manager product, drop the database user holding the Oracle Identity Manager schema.

3.2 Using Oracle RAC Databases for Oracle Identity Manager

This section explains how to deploy Oracle Real Application Clusters (Oracle RAC) databases for Oracle Identity Manager and contains the following sections:

• Installing Oracle Identity Manager for Oracle RAC

• Oracle RAC Net Services

• JDBC and Oracle RAC

• Configuring JBoss Application Server for Oracle RAC

3.2.1 Installing Oracle Identity Manager for Oracle RAC

Oracle RAC is a cluster database with a shared cache architecture that provides highly scalable and available database solutions. Oracle RAC consists of multiple database instances on different computers. These database instances act in tandem to provide database solutions.

Note:

The Oracle Identity Manager Installer program does not provide support for Oracle RAC. To deploy Oracle Identity Manager for Oracle RAC, you must install Oracle Identity Manager on a single database instance in Oracle RAC and then change the application server settings, specifically the connection pool parameters, to use the Oracle RAC JDBC connection string.

To install Oracle Identity Manager for Oracle RAC:

1. Ensure that Oracle RAC is properly set up and configured with the Oracle Identity Manager schema owner.

2. Start the Oracle Identity Manager Installer.

3. On the Database Parameters page of the installer, enter the host name, port number, and database name of a single database instance in Oracle RAC.

4. Complete the Oracle Identity Manager installation by performing the steps in the installer.

5. Configure your application server for Oracle RAC by referring to Configuring JBoss Application Server for Oracle RAC.

3.2.2 Oracle RAC Net Services

The net services name entry for an Oracle RAC database differs from that of a conventional database. The following is an example of the net services name entry for an Oracle RAC database:

racdb= 
      (DESCRIPTION= 
              (LOAD_BALANCE=off)
              (FAILOVER=on)
              (ADDRESS_LIST=
                      (ADDRESS=(protocol=tcp)(host=node1-vip)(port=1521))
                      (ADDRESS=(protocol=tcp)(host=node2-vip)(port=1521))) 
      (CONNECT_DATA=
              (SERVER=DEDICATED)
              (SERVICE_NAME=racdb)))

Table 3-2 lists and describes the parameters in a net services name entry for an Oracle RAC database.

Table 3-2 Parameters for Oracle RAC Database Net Services Name Entries

Parameter	Description
LOAD_BALANCE	Specifies whether client load balancing is enabled (on) or disabled (off). The default setting is on.
FAILOVER	Specifies whether failover is enabled (on) or disabled (off). The default setting is on.
ADDRESS_LIST	Specifies the list of all the nodes in Oracle RAC, including their host names and the ports at which they listen.

3.2.3 JDBC and Oracle RAC

JDBC client applications using the Thin driver to connect to an Oracle RAC database must use the Oracle RAC net services name as a part of the JDBC URL. The entire Oracle RAC net services name is concatenated and the entire string is used in the JDBC URL so that the client application can connect to Oracle RAC.

The following sample code shows how a JDBC URL is used to connect to an Oracle RAC database:

//String url = "jdbc:oracle:thin:@dbhost:1521:dbservice"
String racUrl =
"jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=off)(FAILOVER=on)(ADDRESS_LIST=(ADDRESS=(protocol=tcp)(host=node1-vip)(port=1521))(ADDRESS=(protocol=tcp)(host=node2-vip)(port=1521)))(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=racdb)))";

       String strUser = "username";
       String strPW = "password";

       // load Oracle driver   
       Class.forName("oracle.jdbc.driver.OracleDriver");   

       // create the connection
       con = DriverManager.getConnection(strURL, strUser, strPW);

The subsequent sections about configuring application servers for Oracle RAC databases explain how to modify connection pools to use a similar JDBC URL so the application server can communicate with Oracle RAC.

3.2.4 Configuring JBoss Application Server for Oracle RAC

This section explains how to configure JBoss Application Server (nonclustered or clustered) for Oracle RAC by ensuring that the data sources and connection pools are configured to use the Oracle RAC JDBC connection string.

See Also:

For information about avoiding split branches of a distributed transaction between Oracle Identity Manager and RAC, see Best Practices for Using XA with RAC document. You can find this document by searching the Oracle Technology Network at

http://www.oracle.com/technology/index.html

To configure nonclustered or clustered JBoss Application Server for Oracle RAC:

1. Get the RAC net services name from the tnsnames.ora file.

2. Construct the RAC JDBC URL. See "JDBC and Oracle RAC" for instructions.

3. Open the OIM_HOME/xellerate/config/xlconfig.xml file.

4. Locate the <DirectDB> section and replace the value of the <url>...</url> tag with the Oracle RAC JDBC URL. For example, the new tag can be similar to the following:

   <url>jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=off)(FAILOVER=on)(ADDRESS_
   LIST=(ADDRESS=(protocol=tcp)(host=node1-vip)(port=1521))(ADDRESS=(protocol=tcp)
   (host=node2-vip)(port=1521)))(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_
   NAME=racdb)))</url>
   

5. Save and close the OIM_HOME/xellerate/config/xlconfig.xml file.

6. If you are configuring a nonclustered JBoss Application Server environment, open the JBOSS_HOME/server/default/deploy/xell-ds.xml file.

   If you are configuring a clustered JBoss Application Server environment, open the JBOSS_HOME/server/all/farm/xell-ds.xml file for each node in the cluster.

   These files contain entries with the XA and non-XA datasources.

7. Locate the <datasources>.<local-tx-datasource>.<connection-url> entry.

8. Change the value of this entry to the JDBC URL described in step 4.

9. Locate the <datasources>.<xa-datasource>.<xa-datasource-property name="URL"> entry.

10. Change the value of this entry to the JDBC URL described in step 4.

11. Save and close the file.

12. Restart JBoss Application Server. For JBoss clusters, restart all nodes in the cluster.

3.3 Using a Microsoft SQL Server Database for Oracle Identity Manager

To use Microsoft SQL Server as the database, perform the procedures described in the following sections:

• Installing and Configuring Microsoft SQL Server

• Configuring JBoss Application Server for Microsoft SQL Server

• Creating a Microsoft SQL Server 2005 Database

• Creating a Microsoft SQL Server Database Account

• Removing Oracle Identity Manager Entries from a Microsoft SQL Server Database

3.3.1 Installing and Configuring Microsoft SQL Server

To install and configure Microsoft SQL Server 2005 for Oracle Identity Manager:

1. Install Microsoft SQL Server 2005 with Service Pack 2.

   During installation, select mixed authentication mode, and then set the password to that of the sa user.

   Note:

   Perform Steps 2 through 4 on the computer hosting the application server.

2. Download SQL Server 2005 JDBC Driver version 1.2 from the Microsoft Web site.

   Note:

   In this chapter, the directory into which you download and extract the driver files is referred to as SQLSERVER2005_JDBC_DRIVER_HOME.

3. Install the SQL Server 2005 JDBC Driver.

   Instructions to install JDBC drivers for SQL Server 2005 are available at the following location:

   SQLSERVER2005_HOME\sqljdbc_1.2\enu\help\html\574e326f-0520-4003-bdf1-62d92c3db457.htm

   Note:

   Specify a short path for the installation folder, such as C:\JDBCjars, so that you can easily add the path to your CLASSPATH in the next step. If the classpath is more than 256 characters, then the installer does not work properly.

4. Locate the JDBC driver file (sqljdbc.jar) from the SQL2005_JDBC_DRIVER_HOME\sqljdbc_1.2\enu directory.

   Add their location to the system CLASSPATH environment variable. If the CLASSPATH environment variable does not exist, you must create it. The string you add should look like the following:

   C:\jdbc_install_folder\sqljdbc.jar;
   

   In this sample string, jdbc_install_folder is the location where the SQL Server 2005 JDBC Driver files is installed.

   Note:

   Perform Steps 5 through 7 on the computer hosting the Microsoft SQL Server database.

5. On the computer hosting the Microsoft SQL Server database, enable distributed transactions by installing SQL Server 2005 JDBC XA procedures.

   Depending on the type of operating system running on the host computer, copy the sqljdbc_xa.dll file from one of the following directories into the SQLSERVER2005_HOME\MSSQL\Binn directory:

   • SQLSERVER2005_JDBC_DRIVER_HOME\sqljdbc_1.2\enu\xa\x86

   • SQLSERVER2005_JDBC_DRIVER_HOME\sqljdbc_1.2\enu\xa\x64

   • SQLSERVER2005_JDBC_DRIVER_HOME\sqljdbc_1.2\enu\xa\IA64

   Note:

   In this chapter, SQLSERVER2005_HOME refers to the directory in which you have installed Microsoft SQL Server 2005.

6. Log in to Microsoft SQL Server as sa and then run the SQLSERVER2005_JDBC_DRIVER_HOME\sqljdbc_1.2\enu\xa\xa_install.sql script.

7. Enable XA transactions as follows:

   1. On the computer on which Microsoft SQL Server is running, click Start, Administrative Tools, and Component Services.

   2. Expand the Component Service tree to locate the computer, right-click the computer name, and then select Properties.

   3. On the MSDTC tab, click Security Configuration.

   4. Under Security Settings, select Enable XA Transactions.

   5. Click OK, and then save the changes.

8. Restart the Distributed Transaction Coordinator (MSDTC) service.

9. Restart Microsoft SQL Server.

3.3.2 Configuring JBoss Application Server for Microsoft SQL Server

After installing JBoss Application Server, set up JBoss to work with SQL Server by copying (not moving) the sqljdbc.jar JDBC driver file to the lib directory of your default JBoss server.

Copy the files from the SQLSERVER2005_JDBC_DRIVER_HOME\sqljdbc_1.2\enu directory to the JBOSS_HOME\server\default\lib directory.

Note:

For a JBoss Application Server cluster, copy (do not move) the files from the SQL Server 2005 JDBC Driver library directory to JBOSS_HOME\server\all\lib.

3.3.3 Creating a Microsoft SQL Server 2005 Database

The following procedure describes how to create a new database for Oracle Identity Manager.

Note:

From this point onward in the guide, the name XELL is used to refer to the database. You can set any name for the database.

To create a SQL Server database:

1. Start the Microsoft SQL Server Management Studio application as follows:

   1. From the Windows Start menu, expand All Programs, expand Microsoft SQL Server 2005, and then select SQL Server Management Studio.

   2. In the Connect to Server dialog box, verify the default settings. Ensure that the name of the computer on which SQL Server is installed is specified in the Server name box. Then, click Connect.

2. On the left pane of the SQL Server Management Studio application window, right-click Databases, and then select New Database.

3. In the New Database Properties dialog box, on the left pane, select General, and then enter XELL in the Database Name field.

4. In the Database Files section, for the Initial Size and Filegroup columns in the Database files matrix, enter the information from the corresponding columns in Table 3-3.

   Table 3-3 Database Files

   Logical Name	File Type	File Group	Initial Size in Megabytes (MB)	Auto Growth	Path	File Name
   XELL_PRIMARY	Data	PRIMARY	100	By 1 MB, unrestricted growth (by default)	Specify the default path to save the datafiles	Left Blank (Default)
   XELL_DATA	Data	XELL_DATA	500	By 1 MB, unrestricted growth (by default)	Specify the default path to save the datafiles	Left Blank (Default)
   XELL_INDEX	Data	XELL_INDEX	300	By 1 MB, unrestricted growth (by default)	Specify the default path to save the datafiles	Left Blank (Default)
   XELL_TEXT	Data	XELL_TEXT	500	By 1 MB, unrestricted growth (by default)	Specify the default path to save the datafiles	Left Blank (Default)
   XELL_UPA	Data	XELL_UPA	1000	By 1 MB, unrestricted growth (by default)	Specify the default path to save the datafiles	Left Blank (Default)

   
   

   Note:

   • Table 3-3 lists initial sizes for a production environment. For non-production installations, you can use the default initial sizes provided for the filegroups.

   • To ensure successful installation of Oracle Identity Manager, filegroup names must be entered exactly as they appear in Table 3-3. You can vary the File Name and Location strings to match the database name and the location of your SQL Server installation.

   • The PRIMARY filegroup contains the system objects required for SQL Server to operate. The XELL_DATA filegroup stores the physical data and primary keys, XELL_INDEX filegroup stores indexes, XELL_TEXT stores large text fields and XELL_UPA stores physical data and primary keys of the User Profile Audit component.

5. Select the log file, then change the initial size to 500 MB. Leave all the other options on the tab at their default values.

   Note:

   For nonproduction installations, you can use the default initial size for the log file.

6. Click OK to start creating the database.

3.3.4 Creating a Microsoft SQL Server Database Account

The following procedure describes how to create a database account for Oracle Identity Manager and assign appropriate permissions to that account.

Note:

The following procedure assumes the account name xladm. If you want to use an account name other than xladm, then specify that login instead of xladm throughout the following procedure and also when installing Oracle Identity Manager.

To create a Microsoft SQL Server database account and permissions:

1. Start the Microsoft SQL Server Management Studio application.

2. On the left pane of the SQL Server Management Studio application window, select Security, right-click Logins, and then select New Login.

3. In the SQL Server Login Properties dialog box, from the left pane, click the General tab, and perform the following steps:

   1. In the Login Name field, enter xladm (or a different account name that you prefer).

   2. Select the Enforce Password Policy check box. Deselect all other check boxes.

4. Select SQL Server Authentication, and then enter the password associated with the account you specified in the Password field.

5. In the Database box within the Defaults section, select XELL from the list.

6. Leave the Language box set to <default>, and then click OK.

7. On the left pane of the SQL Server Management Studio application window, select Security, right-click xladm, and then select Properties.

8. Select the User Mapping option from the left pane.

9. In the Users mapped to this login table, select the check box associated with the XELL database. Enter xladm in the User and Default Schema columns.

10. In the Database role membership for table, select the check boxes associated with the following:

    • public

    • db_owner

    • db_accessadmin

    • db_securityadmin

    • db_ddladmin

    • db_datareader

    • db_datawriter

11. In the Users mapped to this login table, select the check box associated with the master database. Enter xladm in the User and Default Schema columns.

12. In the Database role membership for table, select the check boxes associated with the following:

    • public

    • SqlJDBCXAUser

13. Click OK to commit your changes.

14. On the Microsoft SQL Server Management Studio, in the left pane, right-click registered server, click Properties. In the Properties dialog box, select the Security option, and then verify that Authentication is set to SQL Server and Windows.

15. Start the Microsoft SQL Server 2005 Surface Area Configuration application. To do so:

    1. From the Start menu, expand All Programs, expand Microsoft SQL Server 2005, expand Configuration Tools, and then click SQL Server 2005 Surface Area Configuration. A dialog box is displayed.

    2. Click Surface Area Configuration for Services and Connection. On the left pane, select the MSSQLSERVER-> Database Engine, and then verify that the Startup Type is set to Automatic.

    3. If Autostart SQL Server Agent is selected, do not change the existing setting, because that setting may be required by other applications. Click OK to close the SQL Server Properties page.

3.3.5 Removing Oracle Identity Manager Entries from a Microsoft SQL Server Database

To remove Oracle Identity Manager entries from a Microsoft SQL Server 2005 database after removing (deinstalling) the Oracle Identity Manager product:

1. Delete the Oracle Identity Manager database.

2. Delete the Oracle Identity Manager login.