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

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

2. 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

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

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

3. 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.

4. 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

• Configuration Data Store Parameters

• Multi-Server Deployment Parameters

• User Data Store Parameters

• Site Configuration Parameters

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

Depending on your security requirements, consider making a snapshot of your deployment using the OpenSSO Diagnostic Tool. Then, you can run the Tamper Detection test periodically to very the integrity of your deployment. For more information, see Chapter 7, Running the OpenSSO Diagnostic Tool.