Chapter 4 Configuring OpenSSO Enterprise Using the GUI Configurator

Sun^TM OpenSSO Enterprise includes the Configurator to perform the initial configuration of an OpenSSO Enterprise server instance. This chapter describes how to run the GUI Configurator, including:

To run the Configurator from the command-line, see Chapter 5, Configuring OpenSSO Enterprise Using the Command-Line Configurator.

Starting the Configurator

To Start the Configurator

Before You Begin

Important: If you plan to use Sun Java System Directory Server to store configuration or user data, Directory Server must be installed and running before you launch the Configurator.

Launch OpenSSO Enterprise.

When you access OpenSSO Enterprise for the first time, you will be directed to the Configurator, to perform the OpenSSO Enterprise initial configuration.

To start the Configurator, specify the following URL in your browser:
```
protocol://host.domain:port/deploy_uri
```
For example: http://opensso.example.com:8080/opensso

The Configurator starts and display the Configuration Options page:

Select the configuration option:
- Default Configuration: You specify and confirm passwords for the OpenSSO Enterprise administrator (amAdmin) and the default policy agent user (UrlAccessAgent), which is the policy agent user that connects to OpenSSO Enterprise server. The Configurator uses default values for the other configuration settings.
  
  The default policy agent user is also referred to as an application user. This user can connect to OpenSSO Enterprise server from a client such as the client SDK or a distributed authentication UI server.
  
  Choose Default Configuration for development environments or simple demonstration purposes when you just want to evaluate OpenSSO Enterprise features.
  
  Click Create Default Configuration and continue with Configuring OpenSSO Enterprise With the Default Configuration.
  
  or
- Custom Configuration: You specify the configuration settings that meet the specific requirements for your deployment (or accept the default settings).
  
  Choose Custom Configuration for production and more complex environments. For example, a multi-server installation with several OpenSSO Enterprise instances behind a load balancer.
  
  Click Create New Configuration and continue with Configuring OpenSSO Enterprise With a Custom Configuration.

Configuring OpenSSO Enterprise With the Default Configuration

In this scenario, you launched the Configurator and clicked Create Default Configuration.

To Configure OpenSSO Enterprise With the Default Configuration

On the Default Configuration Options page, enter and confirm the following passwords:
- Default User (amAdmin) is the OpenSSO Enterprise administrator.
- Default Policy Agent (UrlAccessAgent) is the policy agent user that connects to OpenSSO Enterprise server.

Click Create Configuration to continue.

Next Steps

When the configuration is complete, the Configurator displays a link to the OpenSSO Enterprise Administration Console to perform any additional configuration required for your deployment.

If a problem occurred during the configuration, the Configurator displays an error message. If you can, correct the error and retry the configuration.

Also, check the web container log files and the install.log, which if created, will be in the configuration directory (default /opensso). These logs might contain information about the cause of a configuration problem.

Configuring OpenSSO Enterprise With a Custom Configuration

In this scenario, you launched the Configurator and clicked Create New Configuration.

To Configure OpenSSO Enterprise With a Custom Configuration

On the Default User Password page, enter and confirm the amAdmin password:

Click Next to continue.

On the Server Settings page, specify the OpenSSO Enterprise server information:
- Server URL is the host server where you deployed OpenSSO Enterprise. It can be one of the following values:
  - localhost
  - Fully qualified domain name (FQDN). For example: http://host.example.com:8080
    
    If you plan to use the OpenSSO Enterprise client SDK or a policy agent, you must specify the FQDN.
  The default is the host where you deployed the opensso.war file.
- Cookie Domain is the name of the trusted DNS domain that OpenSSO Enterprise returns to a browser when it grants a single sign-on (SSO) token to a user.
  
  Specify a value only if the FQDN is used as the Server URL. For example, if the FQDN for Server URL is http://host.example.com:8080, the value is .example.com.
- Platform Locale is the default language subtype for OpenSSO Enterprise. The default is en_US (US English).
  
  Other values can be de (German), es (Spanish), fr (French), ja (Japanese), zh_CN (Simplified Chinese), or zh_TW (Traditional Chinese).
- Configuration Directory is the location of the OpenSSO Enterprise configuration directory.
  
  Important: The runtime user of the OpenSSO Enterprise web container instance must have write access to the location where this directory will be created. For example, if the web container instance is running as the webservd user, then the webservd user must be able to write to the configuration directory.
Click Next to continue.

Specify the Configuration Data Store Settings:

Check whether the instance you are configuring is the First Instance (or the only instance) or if you want to Add to an Existing Deployment.

If you check Add to Existing Deployment, enter the Server URL of the first already configured existing OpenSSO Enterprise server.

Configuration Store Details:
- Configuration Data Store:
  - OpenSSO stores OpenSSO Enterprise configuration data under the configuration_directory/opends directory on the local server.
    
    The OpenSSO configuration data store must be deployed on a local file system. It is not supported on an NFS-mounted file system.
    
    Replication. If you set up the OpenSSO configuration data store for replication, you must restart all OpenSSO Enterprise servers after you set up the replication. For more information, see Chapter 5, Deploying and Configuring OpenSSO Enterprise, in Deployment Example: Single Sign-On, Load Balancing and Failover Using Sun OpenSSO Enterprise 8.0.
  - Sun Java System Directory Server stores OpenSSO Enterprise configuration data in Sun Java System Directory Server.
- SSL Enabled: Check if you want to use LDAPS to connect to the directory server hosting the configuration data store.
- Host Name is the directory server host name.
- Port is the directory server port number. Default is 50389.
- Encryption Key is a random number used to encrypt passwords. Either accept the default encryption key value or specify a new value. The encryption key must be at least 12 characters.
  
  Important: If you are deploying multiple OpenSSO Enterprise instances in a multiple server deployment, you must use the same password encryption key value for each instance.
- Root Suffix is the directory server initial or root suffix.
Note –
If you are configuring a second instance in an OpenSSO Enterprise site and the first instance in the site is SSL-enabled, you must import the root CA certificate of the server certificate of the first OpenSSO Enterprise instance into the second OpenSSO Enterprise instance's web container's JVM key store.

By default, the JDK key store is the JAVA_HOME/jre/lib/security/cacerts file, where JAVA_HOME is where you installed the JDK you are using.

For example, to import a root CA certificate to this key store:

keytool -keystore /usr/jdk/entsys-j2se/jre/lib/security/cacerts -keyalg RSA -import -trustcacerts -alias "OpenSSO CA" -storepass changeit -file /tmp/cacertfile.txt

Then, to verify that the root CA certificate was stored correctly in the key store:

keytool -list -keystore JAVA_HOME/jre/lib/security/cacerts -storepass changeit

After you the import the certificate, restart the web container for the second instance.

You must also import the root CA certificate into the web container's JVM trust store for any instance that is attempting to connect to an LDAPS enabled directory server.

Click Next to continue.

Specify the User Data Store Settings:
- OpenSSO User Data Store stores user data in the OpenSSO user data store.
  
  Note: Storing user data in the OpenSSO data store is recommended only for prototype, proof of concept (POC), or developer deployments that have a small number of users. It is not recommended for production deployments.
- Other User Data Store stores user data in a data store such as Sun Java System Directory Server, Microsoft Active Directory, or IBM Tivoli Directory Server.
  
  Multiple OpenSSO Enterprise instances. If you are configuring multiple OpenSSO Enterprise server instances to use the same Directory Server as the user data store, see Chapter 4, Installing Sun Java System Directory Server and Creating Instances for Sun OpenSSO Enterprise User Data, in Deployment Example: Single Sign-On, Load Balancing and Failover Using Sun OpenSSO Enterprise 8.0.
User Store Details:
- SSL Enabled: Check if you want to use LDAPS to connect to the directory server hosting the user data store.
  
  Note –
  Before you continue with the configuration, the JVM of the web container instance on which OpenSSO Enterprise is deployed must trust the root CA certificate of the certificate on the LDAPS-enabled directory server. The root CA certificate for the directory server certificate must be imported into the web container JVM's trust store.
  
  The default trust store is JAVA_HOME/jre/lib/security/cacerts. If this certificate is not imported, use the keytool utility to import the directory server root CA, where JAVA_HOME is where you installed the JDK you are using.
  
  For example, to import a root CA certificate to this key store:
  
  keytool -keystore /usr/jdk/entsys-j2se/jre/lib/security/cacerts -keyalg RSA -import -trustcacerts -alias "OpenSSO CA" -storepass changeit -file /tmp/cacertfile.txt
  
  Then, verify that the root CA certificate was stored correctly in the key store:
  
  keytool -list -keystore JAVA_HOME/jre/lib/security/cacerts -storepass changeit
  
  After you the import the certificate, restart the web container.
  
  You must also import the root CA certificate into the web container's JVM trust store for any instance that is attempting to connect to an LDAPS enabled directory server.
- Directory Name is the hostname of the directory server that will serve as the user store.
- Port is the user directory server port number. Default is 389. If SSL Enabled is checked the Port value should the LDAPS port of the directory server instance.
- Root Suffix is the user directory server initial or root suffix.
- Login ID is the administrator who has access to the user directory server.
- Password is the password for the user specified in Login ID.
  
  The Configurator automatically check the validity of this password.
- User Data Store Type:
  - LDAP with OpenSSO Schema: The directory server already has the OpenSSO Enterprise schema loaded. With this option, on a Sun Java System Directory Server instance, you can manage additional identity types such as roles and filtered roles as well as users and groups.
  - Generic LDAP: The directory server does not have the OpenSSO Enterprise schema loaded.
Click Next to continue.

On the Site Configuration page, specify whether this OpenSSO Enterprise instance will be deployed behind a load balancer as part of a site configuration.

If No, click Next to continue.

If Yes, specify the Site Configuration Details:
- Site Name is the name of the site.
- Load Balancer URL is the URL of the load balancer in the site.
Click Next to continue.

Considerations about multiple OpenSSO Enterprise server instances:
- Multiple server instances as a site without stickiness. For multiple OpenSSO Enterprise server instances deployed behind a load balancer without stickiness configured, to do additional configuration using the Admin Console, specify the URL of one of the OpenSSO Enterprise server instances and not the URL for the load balancer.
  
  If you are configuring an OpenSSO Server instance using ssoadm, see Using ssoadm With OpenSSO Enterprise Configured as a Site.
  
  For more information about configuring multiple OpenSSO Enterprise server instances as a site and using a load balancer, see Chapter 5, Deploying and Configuring OpenSSO Enterprise, in Deployment Example: Single Sign-On, Load Balancing and Failover Using Sun OpenSSO Enterprise 8.0.
- Two instances not configured as a site. If you are deploying two OpenSSO Enterprise server instances that share the same configuration data store but not configured as a site, you can log in to the Admin Console for first server instance and access the second server instance; however, after you configure the second server instance, you must restart the first server instance.

Specify and confirm the password for the UrlAccessAgent user:

Click Next to continue.

Check the Summary page:

If the settings in the summary are correct, click Create Configuration.

To make changes, click Previous or Edit to return to previous pages to make changes to your configuration (or click Cancel to start over).

If a problem occurred during the configuration, the Configurator displays an error message. If you can, correct the error and retry the configuration.

Also, check the web container log files to help determine the problem. In some cases, there might be an amSetupServlet debug log (/opensso/deploy_uri/debug/amSetupServlet) containing errors or exceptions.

Next Steps

When the configuration is complete, the Configurator displays a link to the OpenSSO Enterprise Administration Console so you can perform any additional configuration required for your deployment.

Login to the Console as amAdmin using the password you specified during the initial configuration using the Configurator.

The Console includes Common Tasks to help you configures common deployment scenarios. For information about the Common Tasks as well as other configuration tasks you can do in the Console, see the Console online Help.

If a problem occurred during the configuration, the Configurator displays an error message. If you can, correct the error and retry the configuration.