Chapter 5 Configuring OpenSSO Enterprise Using the Command-Line Configurator

To configure OpenSSO Enterprise server using the command-line Configurator, you set parameters in a configuration file and then run the Configurator from the command line using the configuration file as input. You can run the Configurator on the same system as OpenSSO Enterprise server or from a remote system.

Requirements to Run the Command-Line Configurator

The requirements to install and run the command-line Configurator include:

You have downloaded and unzipped the opensso_enterprise_80.zip file, as described in Chapter 3, Installing OpenSSO Enterprise.
You have deployed the opensso.war file in a supported web container, as described in Deploying the OpenSSO Enterprise WAR File.
The web container must be started.
Your JAVA_HOME environment variable must point to a JDK 1.5 or later.

Installing the Command-Line Configurator

After you unzip the opensso_enterprise_80.zip file, the command-line Configurator and related files are in the following file:

zip-root/opensso/tools/ssoConfiguratorTools.zip

where zip-root is the directory where you unzipped opensso_enterprise_80.zip.

To Install the Command-Line Configurator

Change to the zip-root/opensso/tools directory.

Unzip the ssoConfiguratorTools.zip file to get these files:
- README.setup describes how to run the Configurator.
- configurator.jar contains the binary files (OpenSSOConfigurator.class and OpenSSOConfigurator.properties).
- sampleconfiguration is a sample input file that you edit before you run the Configurator.
- license.txt describes the Common Development and Distribution License (CDDL).
Remote system. If you plan to run the Configurator on a remote system, copy the ssoConfiguratorTools.zip file to the remote system before you unzip it.

Configuring OpenSSO Enterprise Server

To Configure OpenSSO Enterprise Using the Command-Line Configurator

Make sure your JAVA_HOME environment variable points to JDK 1.5 or later.

Change to the directory where you unzipped the ssoConfiguratorTools.zip file.

Create a configuration file and set the properties required for your deployment.

Sun provides the OpenSSO Enterprise server configuration parameters in the sampleconfiguration file. Either edit sampleconfiguration and use it when you run the Configurator, or copy this file and edit the new file.

See OpenSSO Enteprise Configuration Parameters For the Command-Line Configurator for the properties you can set.

Run the Configurator. For example:

# java -jar configurator.jar -f configuration-file

where configuration-file contains the configuration properties you set in the previous step.

OpenSSO Enteprise Configuration Parameters For the Command-Line Configurator

General and Server Parameters

SERVER_URL is the URL of the web container on which OpenSSO Enterprise server is deployed. For example: SERVER_URL=http://ssohost.example.com:58080
DEPLOYMENT_URI is the OpenSSO Enterprise server deployment URI. Default: DEPLOYMENT_URI=/opensso
BASE_DIR is the configuration directory. Default: BASE_DIR=/opensso
PLATFORM_LOCALE is the OpenSSO Enterprise server locale. Default: locale=en_US

The default is en_US (US English). Other values can be de (German), es (Spanish), fr (French), ja (Japanese), zh (Chinese), or zh_TW (Simplified Chinese).
AM_ENC_KEY is the password encryption key. In a multi-server installation, this parameter must have the same value as the other servers. By default, AM_ENC_KEY is set to blank, which means that OpenSSO Enterprise server will generate a random password encryption key.

If you specify a password encryption key, the key must be at least 8 characters. If this configuration will be part of an existing deployment, the password encryption key you enter must match that of the original deployment.
ADMIN_PWD is the password for the default OpenSSO Enterprise administrator, amAdmin. The password must be at least 8 characters in length. If this configuration will be part of an existing deployment, the password you enter must match that of the original deployment.
COOKIE_DOMAIN is the name of the trusted DNS domain that OpenSSO Enterprise server returns to a browser when it grants a session ID to a user. For example: COOKIE_DOMAIN=.example.com
AMLDAPUSERPASSWD is the password for default policy agent user [UrlAccessAgent].

Configuration Data Store Parameters

DATA_STORE is the type of configuration data store. Values can be:

embedded - OpenSSO configuration data store

dirServer - Sun Java System Directory Server

If DATA_STORE=dirServer is specified:
- The value for USERSTORE_TYPE under the “User Data Store Parameters” must be either LDAPv3ForAMDS or LDAPv3. The USERSTORE_TYPE cannot be blank or commented out.
  
  You must specify all of the relevant parameters for the user data store. For example:
```
#Config Store Details
DATA_STORE=dirServer
DIRECTORY_SSL=SIMPLE
DIRECTORY_SERVER=configurationdatastore.example.com
DIRECTORY_PORT=5002
ROOT_SUFFIX=dc=opensso,dc=java,dc=net
DS_DIRMGRDN=cn=puser,ou=DSAME Users,dc=opensso,dc=java,dc=net
DS_DIRMGRPASSWD=password

# User Store Details
USERSTORE_TYPE=LDAPv3ForAMDS
USERSTORE_SSL=SIMPLE
USERSTORE_HOST=userdatastore.example.com
USERSTORE_PORT=5002
USERSTORE_SUFFIX=dc=opensso,dc=java,dc=net
USERSTORE_MGRDN=cn=puser,ou=DSAME Users,dc=opensso,dc=java,dc=net
USERSTORE_PASSWD=password
```
- If the configuration data store contains the configuration of existing OpenSSO Enterprise servers, this OpenSSO Enterprise server will be added to the existing multi-server setup.
DIRECTORY_SSL specifies if the configuration data store is using SSL. Values can be:
- SSL: SSL is used.
- SIMPLE: SSL is not used.
For example: DIRECTORY_SSL=SIMPLE
DIRECTORY_SERVER is the fully qualified host name of the configuration data store. For example: DIRECTORY_SERVER=ds.example.com
DIRECTORY_PORT is the port on which the configuration data store is listening for connections. For example: DIRECTORY_PORT=50389
ROOT_SUFFIX is the initial or root suffix of the configuration data store. For example: ROOT_SUFFIX=dc=opensso,dc=java,dc=net
DS_DIRMGRDN is the user who has read and write privileges to the root suffix and schema (cn=schema) in the configuration data store. Default: DS_DIRMGRDN=cn=Directory Manager
DS_DIRMGRPASSWD is the password for the DS_DIRMGRDN user.

Multi-Server Deployment Parameters

DS_EMB_REPL_FLAG is a flag that enables the configuration data store in a multi-server setup. This flag is valid only if DATA_STORE=embedded. To enable this flag, set the value to embReplFlag. For example: DS_EMB_REPL_FLAG=embReplFlag
DS_EMB_REPL_REPLPORT1 is the replication port of the configuration data store of the new OpenSSO Enterprise server. For example: DS_EMB_REPL_REPLPORT1=58989
DS_EMB_REPL_HOST2 is the host name of the existing OpenSSO Enterprise server. For example: DS_EMB_REPL_HOST2=host2.example.com
DS_EMB_REPL_PORT2 is the listening port of the configuration data store of the existing OpenSSO Enterprise server. For example: DS_EMB_REPL_PORT2=50389
DS_EMB_REPL_REPLPORT2 is the replication port of the configuration data store of the existing OpenSSO Enterprise server. For example: DS_EMB_REPL_REPLPORT2=50889

User Data Store Parameters

USERSTORE_TYPE is the type of user data store. Values can be:
- LDAPv3ForAMDS: LDAP with OpenSSO Schema
- LDAPv3: Generic LDAP (no OpenSSO Schema)
- blank (USERSTORE_TYPE=): The configuration data store will be the same as the user data store. DATA_STORE must be embedded. The remaining user data store properties will be ignored.
USERSTORE_SSL specifies if the user data store is using SSL. Values can be:
- SSL: SSL is used.
- SIMPLE: SSL is not used.
USERSTORE_HOST is the host name of the user data store. For example: ssohost.example.com
USERSTORE_PORT is the port on which the user data store is listening for connections. Default is 389.
USERSTORE_SUFFIX is the initial or root suffix of the user data store. For example: dc=opensso,dc=java,dc=net
USERSTORE_MGRDN is the DN (distinguished name) of the directory manager, which is the user who has unrestricted access to the user data store. Default is cn=Directory Manager
USERSTORE_PASSWD is the password for the directory manager of the user data store.

Site Configuration Parameters

LB_SITE_NAME is the name of the site.
LB_PRIMARY_URL is the load balancer URL. For example: http://lb.example.com:58080/opensso