Sun OpenSSO Enterprise 8.0 Integration Guide

Installing Identity Manager on Application Server

To install Identity Manager on Application Server, follow these steps:

To Install the Application Server

Follow the installations instructions in the Application Server product documentation.

See the Application Server product documentationhttp://docs.sun.com/coll/1343.4.

Start the Application Server.

# /opt/SUNWappserver91/bin/asadmin start-domain domain1

To Install Identity Manager on the Application Server

The idm.war file is used because you will make manual changes to the deployed WAR in a subsequent procedure.

Follow the installation instructions (with one exception) in the Identity Manager Installation Guide for deploying theidm.war file on the Application Server. This is the exception:

Do not recreate the file suggested in the Identity Manager Installation Guide. Use the idm.war file that is available in the downloaded zip distribution.

See the Sun Identity Manager 8.0 Installation Guide at http://docs.sun.com/app/docs/coll/1514.5.

Remove the following file:

/opt/SUNWappserver91/domains/domain1/applications/j2ee-modules/idm/WEB-INF/lib/j2ee.jar

This file causes conflicts with the j2ee.jar file that ships with Application Server.

Set the Application Server classpath.

In the left frame, click Application Server.

In the right frame, navigate to the “JVM Settings | Path Settings” tab.

Add the following entries to the Server Classpath in this exact order:

/opt/SUNWappserver91/lib/appserv-admin.jar
/opt/SUNWappserver91/lib/appserv-rt.jar
/opt/SUNWappserver91/imq/lib/imq.jar
/opt/SUNWappserver91/lib/j2ee.jar
/opt/SUNWappserver91/domains/domain1/applications/j2ee-modules/idm/
  WEB-INF/lib/mysql-connector-java-5.0.8-bin.jar

The mysql-connector-java-5.0.8-bin.jar will not be available at this file location at this time. The JAR will be added to that directory later. See To Configure the Application Server Data Source to Work with Identity Manager.

Click Save.

Set the Application Server JVM options.

In the right frame of the Application Server console, navigate to the "JVM Settings | JVM Options" tab.

To add or modify the following JVM options, click the Add JVM Option button.
1. Increase the JVM heap size to -Xmx1024M.
2. Set the Identity Manager home location to:
  
  -Dwaveset.home=/opt/SUNWappserver91/domains/domain1/applications/j2ee-modules/idm
3. Add the following option to ensure you can create resources in Identity Manager.
  
  -Dcom.sun.enterprise.server.ss.ASQuickStartup=false
4. Click Save.

Stop the Application Server.

# /opt/SUNWappserver91/bin/asadmin stop-domain domain1

To Create Identity Manager Tables in MySQL

Run the following commands:

# cd /opt/SUNWappserver91/domains/domain1/applications/j2ee-modules/idm/sample
# /opt/mysql/bin/mysql -uroot -ppassword < create_waveset_tables.mysql

Verify that the Waveset database was successfully created.

-$ /opt/mysql/bin/mysqlshow  -uroot -ppassword
+--------------------+
|     Databases      |
+--------------------+
| information_schema |
| mysql              |
| test               |
| waveset            |
+--------------------+
-$

You should see the waveset database name in the output above.

To Configure the Application Server Data Source to Work with Identity Manager

Download the MySQL Connector/J 5.0.

Extract the archive mysql-connector-java-5.0.8.tar.gz.

Copy mysql-connector-java-5.0.8-bin.jar from the above download to /opt/SUNWappserver91/domains/domain1/applications/j2ee-modules/idm/WEB_INF/lib/

Set the password for the Waveset user in MySQL.

# cd /opt/mysql

# ./bin/mysql -u root -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 6
Server version: 5.0.45-log MySQL Community Server (GPL)

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> SET PASSWORD FOR 'waveset'@'localhost' = PASSWORD('password');
Query OK, 0 rows affected (0.00 sec)

mysql> exit
Bye
#

Start the Application Server.

# /opt/SUNWappserver91/bin/asadmin start-domain domain1

Connect to the data source.

# cd /opt/SUNWappserver91/domains/domain1/applications/
  j2ee-modules/idm/bin

# chmod +x lh

# export WSHOME=/opt/SUNWappserver91/domains/domain1/applications/
  j2ee-modules/idm

# export CLASSPATH=/opt/SUNWappserver91/lib/appserv-rt.jar:
  /opt/SUNWappserver91/lib/javaee.jar:$CLASSPATH

# ./lh setRepo -v -tMySQL   -ujdbc:mysql://localhost/waveset -Uwaveset -Ppassword
Defaulting administrator to 'configurator'.
Defaulting credentials to 'configurator'.
DB Server @ jdbc:hsqldb:hsql://127.0.0.1:53878/idm
Defaulting jdbcDriver to 'org.gjt.mm.mysql.Driver'.
Checking 'MysqlDataStore:jdbc:mysql://localhost/waveset'...
Switching to 'MysqlDataStore:jdbc:mysql://localhost/waveset'...
Getting current location....
Current Location is 'MysqlDataStore:jdbc:mysql://localhost/waveset'
userid is 'waveset'
password is '(set)'
jdbcDriver is 'org.gjt.mm.mysql.Driver'
#

To Configure Identity Manager to Work with Application Server

Set the environment variables that will be required for the setup program:

# export WSHOME=/opt/SUNWappserver91/domains/domain1/applications/j2ee-modules/idm

# export JAVA_HOME=/usr/java

# export PATH=/usr/java/bin:$PATH

Start an X server on your local machine, and set the DISPLAY variable on the Application Server host computer.

Run the following commands:

# cd /opt/SUNWappserver91/domains/domain1/applications/j2ee-modules/idm/bin

# ./lh setup

Select MySQL (JDBC Driver) as the Repository Type.

Enter the same password for the waveset user that you set earlier in MySQL.

Click the Next button.

Accept the default setting to setup a demo environment.

Enter information about the demo user.

In this case, enter following credentials:

User Name:

demoapprover

Password:

password

In the next screen, select the option for a Notification File for the Mail Settings.

You may accept the default file or customize it.

In the next screen, click Execute.

The lh program logs the details of the execution steps in the screen. See the Example in the Sample Outputat the end of this chapter.

Click Done.

Change permissions so that Identity Manager can perform certain actions.

Add the following lines to /opt/SUNWappserver91/domains/domain1/config/server.policy:

grant {
        permission java.lang.RuntimePermission "accessClassInPackage.sun.io";
        permission java.lang.RuntimePermission "getClassLoader";
        permission java.lang.RuntimePermission "createClassLoader";
        permission java.lang.RuntimePermission "accessDeclaredMembers";
        permission com.waveset.repository.test.testConcurrentLocking "read";
        permission java.net.SocketPermission "*", "connect,resolve";
        permission java.io.FilePermission "*", "read";
        permission java.util.PropertyPermission "*", "read,write";
};
grant codeBase "file:${waveset.home}/-" {
        permission java.util.PropertyPermission "waveset.home", "read,write";
        permission java.util.PropertyPermission "security.provider", "read,write";
        permission java.io.FilePermission "${waveset.home}${/} *", 
            "read,write,execute";
        permission java.io.FilePermission "${waveset.home}/help/index/-", 
            "read,write,execute,delete";
        permission java.io.FilePermission "$(java.io.tmpdir)$(/)*", 
            "read,write,delete";
        permission java.util.PropertyPermission "*", "read,write";
        permission java.lang.RuntimePermission "accessClassInPackage.sun.io";
        permission java.net.SocketPermission "*", "connect,resolve";
};

To enable Identity Manager to connect to OpenSSO Enterprise with the SunAccessManagerRealmResourceAdapter, add the two following policies:

grant {
        permission java.lang.RuntimePermission "shutdownHooks";
        permission java.io.FilePermission "${waveset.home}/WEB-INF/spe/config/spe.tld", "read";
};

Restart the Application Server.

# /opt/SUNWappserver91/bin/asadmin stop-domain domain1

# /opt/SUNWappserver91/bin/asadmin start-domain domain1

Watch for any errors in the Application Server server.log file.

Verify that you can successfully log in to Identity Manager.

Go to the Identity Manager console at http://ApplicationServerHost:Port/idm/login.jsp
1. Log in using the following credentials:
  
  Username:
  
  configurator
  
  Password:
  
  configurator
  
  To minimize security risk, it is a good practice to change the default password for this administrator.
2. Log out.
3. Log in using the following credentials:
  
  Username:
  
  administrator
  
  Password:
  
  administrator
4. Log out.
5. Log in using the following credentials:
  
  Username:
  
  demoapprover
  
  Password:
  
  password
6. Log out.

To Configure Application Server to Work with Identity Manager

Before You Begin

In the following steps, you configure the AMConfig.properties you generate in the first step. Use the credentials of the amadmin user to connect with the OpenSSO Enterprise server. You could use a user other than amadmin as long as the user has privileges to read the OpenSSO Enterprise configuration data. This should not be a security concern because the AMConfig.properties file is required only to perform the initial configuration and to test the Access Manager Realm Resource adapter instance. The AMConfig.properties file is not needed after the Policy Agent has been installed on the Identity Manager server, and the file can be deleted afterward.

Generate the OpenSSO Enterprise client configuration file.

Go to the directory, where you extracted the OpenSSO Enterprise zip distribution, and unzip the opensso/samples/opensso-client.zip archive in a temporary directory. Then run the following commands:

# cd opensso/samples/tmp/sdk

# chmod +x scripts/compile-samples.sh

# scripts/compile-samples.sh

# chmod +x scripts/setup.sh

# scripts/setup.sh
Debug directory (make sure this directory exists): 
  /opt/SUNWappserver91/domains/idm/logs/opensso_debug
Application user (e.g. URLAccessAgent)passord: password
Protocol of the server: http
Host name of the server: host1.example.com
Port of the server: 8280
Server's deployment URI: /opensso
Naming URL (hit enter to accept default value, 
  http://host1.example.com:8280//opensso/namingservice):
  http://host1.example.com8280/opensso/namingservice
#

You should now see a AMConfig.properties file created in the sdk/resources directory.

Install the OpenSSO Enterprise command-line tools.

They are present in the OpenSSO Enterprise zip distribution, in the opensso/tools/ssoAdminTools.zip archive.

# mkdir /opt/opensso-tools

# cd /opt/opensso-tools

# unzip /export/software/
  FAM_80_B3_QA_Test/opensso_zip/opensso/tools/ssoAdminTools.zip

# export JAVA-HOME=/usr/java
# ./setup
Path to config files of OpenSSO server (example: /openSSO):
/opt/fam80-qatest-server1
Debug Directory: /opt/opensso-tools/debug
Log Directory: /opt/opensso-tools/log
The scripts are properly setup under directory: 
/opt/opensso-tools/opensso
Debug directory is /opt/opensso-tools/debug.
Log directory is /opt/opensso-tools/logs.
The version of this tools.zip is: Express build 5b(2008-September-22 07:55)
The version of your server instance is: Express build 5b(2008-September-22 07:55)
#

You will now see an opensso directory (or a directory with the name of the context-root of your OpenSSO Enterprise deployment), in the /opt/opensso-tools directory.

Encrypt the password for the amadmin user using the ampassword utility.

First, you need to create a text file containing the password of the amadmin user in plain text. In the following example, the password file /export/software/amadmin_pwd is created:
# cd /opt/opensso-tools/opensso/bin # ./ampassword --encrypt /export/software/amadmin_pwd AQICSw+UrU2DJyY1KBeoC0iuzv3gQTGkbI39 #

Customize the AMConfig.properties file that was created in step 1.
1. In the OpenSSO Enterprise console, navigate to Configuration > Servers and Sites > server-entry > Security.
2. Copy the value from the property Password Encryption Key, and use the value to modify the following property:
  
  am.encryption.pwd=AQICrPmBjI5aThg1H6kKcJr0/Lu4D9LdTlqe
3. Modify the following property as shown:
  
  com.sun.identity.agents.app.username=amadmin
4. For security purposes, either comment out the following line, or leave the value empty:
  #com.iplanet.am.service.password=
5. Modify the following property using the value from the encrypted password generated in step 3 above:
  
  com.iplanet.am.service.secret=AQICSw+UrU2DJyY1KBeoC0iuzv3gQTGkbI39

Copy the OpenSSO Enterprise Client files to the Identity Manager application directory. You will need the following files:

The openssoclientsdk.jar library that is present in the /sdk/lib directory from the fam-client.zip archive in the OpenSSO Enterprise zip distribution.

# cp /export/software/
  FAM_80_IDM_80_Integration/fam_zip/opensso/samples/
tmp/sdk/lib/openssoclientsdk.jar  /opt/SUNWappserver91/domains/domain1/
  applications/j2ee-modules/idm/WEB-INF/lib/

The AMConfig.properties generated above.

# mkdir /opt/SUNWappserver91/domains/domain1/applications/j2ee-modules/
idm/WEB-INF/classes
# cp /export/software/FAM_80_IDM_80_Integration/fam_zip/opensso/samples/
tmp/sdk/resources/AMConfig.properties /opt/SUNWappserver91/domains/domain1/
applications/j2ee-modules/
idm/WEB-INF/classes

Update the Application Server classpath.
1. Login to the Application Server Console.
2. Navigate to Application Server | JVM Settings | Path Settings
3. Update the Classpath Suffix to contain the following entries:
  /opt/SUNWappserver91/domains/domain1/applications/j2ee-modules/idm/ WEB-INF/lib/openssoclientsdk.jar /opt/SUNWappserver91/domains/domain1/applications/j2ee-modules/idm/WEB-INF/classes
4. Click Save to save your changes.
5. Log out from the Application Server Console.

Restart the Application Server.

# /opt/SUNWappserver91/bin/asadmin stop-domain domain1

# /opt/SUNWappserver91/bin/asadmin start-domain domain1

Watch for any errors in the Application Server server.log log file.

Creating an OpenSSO Enterprise Realm Administrator

If you plan to use Identity Manager to manage objects in the OpenSSO Enterprise top-level realm, then create a user in the OpenSSO Enterprise root realm. Give this user the same privileges as the Top-Level Admin Role. The privileges should allow this user "Read and write access to all realm and policy properties.” This user will be used to configure the Identity Manager Resource adapter.

If you plan to use Identity Manager to manage objects in the OpenSSO Enterprise sub-realm, then create a user in the OpenSSO Enterprise sub-realm. Give this user privileges to "Read and write access to all realm and policy properties.” This user will have the privileges of a sub-realm administrator, and will be used to configure the Identity Manager Resource adapter. In this example, a realm administrator sradmin with the password password was created in the sub-realm (Top-Level Realm) > idm.

To Create an OpenSSO Enterprise Realm Resource Object

Access the Identity Manager console.

In this example, go to http://ApplicationServerHost:Port/idm/login.jsp. The Identity Manager login page is displayed.

Add the OpenSSO Enterprise realm adapter to the resource classpath.
1. Navigate to Resources | Configure Types.
2. At the bottom of the page, click “Add Custom Resource.”
3. Add the following to the Resource Classpath:
  com.waveset.adapter.SunAccessManagerRealmResourceAdapter
  In earlier versions of OpenSSO Enterprise, it was possible to install Access Manager in the legacy mode of operation. In legacy mode, a different Identity Manager resource adapter com.waveset.adapter.SunAccessManagerResourceAdapter, should be configured on Identity Manager. Both types of adapters have the same functionality. But com.waveset.adapter.SunAccessManagerResourceAdapter uses the legacy Access Manager AMSDK API, while the com.waveset.adapter.SunAccessManagerRealmResourceAdapteruses the OpenSSO Enterprise idRepo API.
4. Click Save.

Configure the OpenSSO Enterprise Realm adapter.
1. Navigate to Resources | List Resources
2. Choose --Resource Type Actions-- | New Resource
3. Choose Sun Access Manager Realm from the list of resources. Click New.
4. In the Create Sun Access Manager Realm Resource Wizard screen, click Next.
5. In the Resource Parameters screen, provide the following information:
  
  Host:
  
  Fully-qualified hostname of the OpenSSO Enterprise server. Example: host1.example.com
  
  TCP Port:
  
  Port number of the OpenSSO Enterprise server. In this example, 48080.
  
  User:
  
  sradmin
  
  You must use an OpenSSO Enterprise realm administrator, and not a non-administrator user, because it requires special permissions. If you use a non-administator user, this test will fail. Use the realm administrator configured in the previous section.
  
  Password:
  
  password
  
  This is the plain-text password of the user realm administrator.
  
  Protocol:
  
  Protocol of the OpenSSO Enterprise server realm or Identity Manager. In this example, enter http.
  
  Realm:
  
  This is the realm name of the OpenSSO Enterprise server. In this example, enter /idm. If the user entered above were in the top-level realm, you would enter just a slash (/).
  
  Encryption Key:
  
  This is the value of the am.encryption.pwd property in the AMConfig.properties file.
  
  You can obtain the value of am.encryption.pwd from the OpenSSO console. Navigate to Configuration > Servers and Sites > server-entry > Security .
  
  JCE Encryptor Class :
  
  This is the value of the com.iplanet.security.encryptor property in the AMConfig.properties file.
  
  In this example, enter: com.iplanet.services.util.JCEEncryption.
  
  Naming Service URL:
  
  This is the value of the com.iplanet.am.naming.url property in the AMConfig.properties file.
  
  In this example, enter :http://host1.example.com:48080/opensso/namingservice.
  
  Error Log Level:
  
  message
  
  Error Log Directory:
  
  Directory into which the Identity Manager Access Manager Resource will write debug logs. This directory must already exist.
  
  In this example, enter:/opt/SUNWappserver91/domains/domain1/logs/opensso_debug.

Click Test Configuration.

The following message will be displayed: “Test connection succeeded for resource(s): SunAccessManagerRealm.” If you don't see this message, then you must troubleshoot by looking at the following logs:
- Application Server server.log
  
  /opt/SUNWappserver91/domains/domain1/logs/server.log
- Access Manager client logs at /opt/SUNWappserver91/domains/domain1/logs/opensso_debug (specified in the form above)
Click Next.

In the Account Attributes page, set the following mapping:

Identity System Attribute:

fullname

Resource User Attribute:

cn

Attribute Type:

string

Required:

yes

Click Next.

In the Identity Template page, make sure you have this entry:
$accountId$
Click Next.

In the Identity System Parameters page, select uid for the Display Name Attribute parameter.

Click Save to save the value.

The Resource List page is displayed. You should see a resource of the type Sun Access Manager Realm. To expand this branch, click the arrow next to it.
1. Expand the Sun Access Manager Realm type by clicking the arrow next to it.
  
  You should see an entry SunAccessManagerRealm.
2. Expand the SunAccessManagerRealm branch by clicking the arrow next to it.
  
  You should see a listing of all OpenSSO Enterprise roles and groups under this branch that exist in the OpenSSO Enterprise sub-realm that the Identity Manager Resource was configured with in step 4e above.