1 Installing OpenSSO Security Token Service

This chapter provides important prerequisite information and instructions for installing the Oracle OpenSSO Security Token Service (OpenSSO STS) server. The following topics are contained in this chapter:

Meeting the System Requirements
Installing a Web Container
Installing the OpenSSO STS Server
Installing the OpenSSO STS Command-Line Utility
Configuring OpenSSO STS Using the Command-Line Configurator
Configuring the OpenSSO STS Administrator Password
Uninstalling the OpenSSO STS Server

1.1 Meeting the System Requirements

For information about system hardware requirements and supported platforms, see http://www.oracle.com/technology/software/products/ias/files/fusion_certification.html

Also be sure you meet the additional database logging requirements.

1.2 Installing a Web Container

Before you can install OpenSSO STS, you must install a supported web container. See the product documentation for installation instructions for the web container into which you will deploy OpenSSO STS. The following sections provide useful links and important information about additional steps you must complete for supported web containers.

1.2.1 Using Oracle WebLogic Server

Download site

http://www.oracle.com/technology/software/products/ias/htdocs/101310.html

Product Documentation

http://download.oracle.com/docs/cd/E14571_01/doc.1111/e14142/toc.htm

Java Permission

Required if Java Security Manager is enabled: server.policy

OpenSSO STS Pre-Deployment Steps

After installing Oracle WebLogic Server, complete the following steps.

Set the MaxPermSize JVM option to a minimum value of 256 MB. For example:

-XX:MaxPermSize=256M
If the Java Security Manager is enabled, add the security permissions to the weblogic.policy file. After you edit the file, restart the web container.

1.2.2 Using GlassFish Application Server

Download Sites

GlassFish V2 UR1: https://glassfish.dev.java.net/downloads/v2ur1-b09d.html
GlassFish V2 UR2: https://glassfish.dev.java.net/downloads/v2ur2-b04.html

Product Documentation

https://glassfish.dev.java.net/

Java Permission

Required if Java Security Manager is enabled: server.policy

OpenSSO STS Pre-Deployment Steps

After installing GlassFish Application Server, complete the following steps.

In the GlassFish domain where you plan to deploy OpenSSO STS server, change the following JVM options either using the GlassFish administration console or by editing the domain.xml file:
- Change -client to -server.
- Change -Xmx512m to -Xmx1024m.
If the Java Security Manager is enabled:
- Set the following JVM option:
  
  -Dcom.sun.enterprise.server.ss.ASQuickStartup=false
- Add the security permissions to the server.policy file. After you edit the file, restart the web container.

1.3 Installing the OpenSSO STS Server

Before you can install the OpenSSO STS Server, a supported web container must already be installed and running.

1.3.1 Downloading the OpenSSO STS WAR

OpenSSO STS is contained in the openssosts_11gr1.zip file. Download openssosts_11gr1.zip from the Oracle Downloads site:

http://www.oracle.com/technology/software/products/middleware/htdocs/fmw_11_download.html

1.3.2 Unpacking openssosts.war

To unzip the openssosts_11gr1.zip file, run the following command:

# unzip openssosts_11gr1.zip

The following table describes the file layout after you unzip the opensssts.zip file. The directory where you unzip the file is represented by zip-root.

Table 1-1 OpenSSO STS opensso_sts.zip File Layout

File or Directory	Description
openssosts.war	WAR file containing all OpenSSO STS components. Use this file you to deploy the OpenSSO STS server.
tools	Directory containing the following: stsAdminTools.zip contains files to setup and run the OpenSSO STS command-line (CLI) ssoadm utility. sts.Configurator.zip contains files the interface for configuring OpenSSO STS at first-time login.
version	File containing version and release indentifiers.

File or Directory

Description

openssosts.war

WAR file containing all OpenSSO STS components. Use this file you to deploy the OpenSSO STS server.

tools

Directory containing the following:

stsAdminTools.zip contains files to setup and run the OpenSSO STS command-line (CLI) ssoadm utility.
sts.Configurator.zip contains files the interface for configuring OpenSSO STS at first-time login.

version

File containing version and release indentifiers.

1.3.3 Deploying the OpenSSO STS WAR File

Caution:

If you plan to use the OpenSSO configuration data store, you must deploy OpenSSO STS on a local file system and not on an NFS-mounted file system. The OpenSSO STS configuration data store, which is deployed with OpenSSO STS, is not supported on an NFS-mounted file system.

1.3.4 To Deploy the OpenSSO STS WAR

Be sure you have proper access permissions on the host computer where you will openssosts.war.
- If you plan to deploy openssosts.war using the web container administration console, then set permissions for accessing the administration console.
- If you plan to deploy openssosts.war using the web container's deploy command-line utility, then set permissions for accessing the command-line utility.
Log in to the host computer where you want to deploy openssosts.war.
Copy openssosts.war to the host computer where you want to deploy OpenSSO STS.
Deploy openssosts.war using either the web container administration console or deploy command.

See Section 1.3.4.2, "Deploying openssosts.war GlassFish Version 3" and Section 1.3.4.1, "Deploying openssosts.war on Oracle WebLogic Application Server".

1.3.4.1 Deploying openssosts.war on Oracle WebLogic Application Server

When deploying openssosts.war, WebLogic Application takes a python script as a configuration parameter. See http://download.oracle.com/docs/cd/E14571_01/web.1111/e13715/using_wlst.htm#i1063337 for information about using the WebLogic Scripting Tool.

Create a python script that includes the following:

evaluatePrompt()
connect('weblogic','password','hostname.domain.com:port')
updateGlobals()
print ''
restoreDisplay()
deploy(appName='openssosts', path='/export/deploy-directory/openssosts.war', targets='AdminServer', plan='true')
restoreDisplay()
disconnect()
 
now run the command
 
$MIDDLEWARE_HOME/wlserver_10.3/common/bin/wlst.sh $PYTHON_DEPLOY_SCRIPT_FILE

Run the following command:

$MIDDLEWARE_HOME/wlserver_10.3/common/bin/wlst.sh $PYTHON_DEPLOY_SCRIPT_FILE

1.3.4.2 Deploying openssosts.war GlassFish Version 3

The following command deploys opensso.war on the GlassFishv3 container on Solaris systems:

# cd /opt/glassfishv3/glassfish/bin
# ./asadmin deploy --user admin --passwordfile /tmp/pwdfile
--port 4848 zip-root/opensso/deployable-war/opensso.war

where:

zip-root is where you unzipped the openssosts_11gr1.zip Or, if you copied openssosts.war to a different location, use that location in the command.
/tmp/pwdfile is the GlassFishv3 password file. This ASCII text file contains the AS_ADMIN_PASSWORD variable set to the administrator password.

1.4 Configuring OpenSSO STS Using the Command-Line Configurator

OpenSSO STS includes the command-line Configurator to perform the initial configuration of an OpenSSO STS server instance. To configure the OpenSSO STS 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 STS server or from a remote system.

1.4.1 Before You Begin

Before running the command-line Configurator, be sure you have met the following requirements:

You have downloaded and unzipped the openssosts_11gr1.zip file.
You have deployed the opensso.war file in a supported web container.
The web container is running.
Your JAVA_HOME environment variable points to a JDK 1.6 or later.

1.4.2 Installing the Command-Line Configurator

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

zip-root/opensso/tools/stsConfiguratorTools.zip

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

1.4.2.1 To Install the Command-Line Configurator

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

Unzip the stsConfiguratorTools.zip file to get these files:

File	Description
README.setup	Explains how to run the Configurator.
configurator.jar	Contains the binary files OpenSSOConfigurator.class and OpenSSOConfigurator.properties.
sampleconfiguration	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 stsConfiguratorTools.zip file to the remote system before you unzip it.

1.4.3 To Configure the OpenSSO STS Server

Make sure your JAVA_HOME environment variable points to JDK 1.6 or later.
Change to the directory where you unzipped the stsConfiguratorTools.zip file.
Create a configuration file and set the properties required for your deployment.

OpenSSO STS provides 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 Section 1.4.3.1, "OpenSSO STS Configuration Parameters For the Command-Line Configurator" for more information.
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.

1.4.3.1 OpenSSO STS Configuration Parameters For the Command-Line Configurator

The following table lists General and Server parameters with a description for each parameter.

Table 1-2 Configurator - General and Server Parameters

Parameter	Description
SERVER_URL	The URL of the web container on which OpenSSO STS server is deployed. For example: SERVER_`URL=http://stshost.example.com:58080`
DEPLOYMENT_URI	The OpenSSO STS server deployment URI. Default: `DEPLOYMENT_URI=/opensso`
BASE_DIR	The configuration directory. Default: `BASE_DIR=/opensso`
PLATFORM_LOCALE	The OpenSSO STS 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	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 STS 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	The password for the default OpenSSO STS 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	The name of the trusted DNS domain that OpenSSO STS server returns to a browser when it grants a session ID to a user. For example: `COOKIE_DOMAIN=.example.com`
AMLDAPUSERPASSWD	The password for default policy agent user [UrlAccessAgent].

The following table lists Configuration Date Store parameters with a description for each parameter.

Table 1-3 Configurator - Configuration Data Store Parameters

Parameter	Description
DATA_STORE	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, then: 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 STS servers, this OpenSSO STS server will be added to the existing multi-server setup.
DIRECTORY_SSL	Specifies if the configuration data store is using SSL. SSL specifies that SSL is used. SIMPLE specifies that SSL is not used. Example: `DIRECTORY_SSL=SIMPLE`
DIRECTORY_SERVER	The fully qualified host name of the configuration data store. For example: `DIRECTORY_SERVER=ds.example.com`
DIRECTORY_PORT	The port on which the configuration data store is listening for connections. For example: `DIRECTORY_PORT=50389`
ROOT_SUFFIX	The initial or root suffix of the configuration data store. For example: `ROOT_SUFFIX=dc=opensso,dc=java,dc=net`
DS_DIRMGRDN	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	The password for the `DS_DIRMGRDN` user.

The following table lists Multi-Server Deployment parameters with a description for each parameter.

Table 1-4 Configurator - Multi-Server Deployment Parameters

Parameter	Description
S_EMB_REPL_FLAG	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	The replication port of the configuration data store of the new OpenSSO STS server. For example: `DS_EMB_REPL_REPLPORT1=58989`
DS_EMB_REPL_HOST2	The host name of the existing OpenSSO STS server. For example: `DS_EMB_REPL_HOST2=host2.example.com`
S_EMB_REPL_PORT2	The listening port of the configuration data store of the existing OpenSSO STS server. For example: `DS_EMB_REPL_PORT2=50389`
DS_EMB_REPL_REPLPORT2	The replication port of the configuration data store of the existing OpenSSO STS server. For example: `DS_EMB_REPL_REPLPORT2=50889`

1.4.3.2 User Data Store Parameters

The following table lists User Data Store parameters with a description for each parameter.

Table 1-5 Configurator - User Data Store Parameters

Parameter	Description
USERSTORE_TYPE	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 specifies that SSL is used. SIMPLE specifies that SSL is not used.
USERSTORE_HOST	The host name of the user data store. For example: `ssohost.example.com`
USERSTORE_PORT	The port on which the user data store is listening for connections. Default is 389.
USERSTORE_SUFFIX	The initial or root suffix of the user data store. For example: `dc=opensso,dc=java,dc=net`
USERSTORE_MGRDN	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	The password for the directory manager of the user data store.

The following table lists Site Configuration parameters with a description for each parameter.

Table 1-6 Configurator - Site Configuration Parameters

Parameter	Description
LB_SITE_NAME i	The name of the site.
LB_PRIMARY_URL	The load balancer URL. For example: `http://lb.example.com:58080/opensso`

1.4.4 To Configure Multiple OpenSSO STS Servers with Identical Configuration Settings

You can install multiple OpenSSO STS servers with the same configuration settings. This is useful in high availability deployments where the primary OpenSSO STS server and a backup OpenSSO STS server must have the same settings.

Create a configuration file following the instructions in Configuring OpenSSO STS Using the Command-Line Configurator.
Use the file to install the first OpenSSO STS server.
Make a copy of the file, and replace the OpenSSO STS server host name and port number with the server host name and port number the second OpenSSO STS server.
Use the edited file to run the Configurator again on the second host computer.

1.5 Configuring the OpenSSO STS Administrator Password

Log in to the OpenSSO STS administration console to configure the administrator passwords and policy agent passwords. See Chapter 3, "Getting Started Using the OpenSSO STS Console."

1.6 Installing the OpenSSO STS Command-Line Utility

The ssoadm command-line utility has two main purposes: to load configuration data into the data store, and to perform batch administrative tasks. For detailed command-line reference, see Chapter A, "Using the ssoadm Command-Line Interface."

The stsAdminTools.zip file is in the following directory:zip-root/toolswhere zip-root is where you unzipped the openssosts_11gr1.zip file.

The following table describes the files after you unzip stsAdminTools.zip.

Table 1-7 ssoadmTools.zip Files

File or Directory	Description
README.setup	Description of the stsAdminTools.zip file.
license.txt	CDDL license agreement.
setup	Script to install the tools on Solaris and Linux systems.
setup.bat	Script to install the tools on Windows systems.
lib	JAR files required to run the scripts.
resources	Properties files required for the scripts for the various locales.
template	Script templates for Solaris, Linux, and Windows systems.

1.6.1 To Install the ssoadm Command-Line Utility

Make sure the OpenSSO STS web container is running.
Make sure that your JAVA_HOME environment variable points to JDK 1.5 or later.
Create a new directory to unzip the stsAdminTools.zip file. For example: tools-zip-root.
Unzip the stsAdminTools.zip file in the new directory.
In the directory where you unzipped the stsAdminTools.zip file, run the setup script on Solaris and Linux systems or the setup.bat script on Windows. For example, on Solaris and Linux systems:

# ./setup
When you are prompted, enter the path to the OpenSSO STS configuration, log, and debug directories. For example: /opensso

You can now run the OpenSSO STS CLI tools and utilities from the following directory:tools-zip-root/deploy_uri/binwhere:

tools-zip-root is the directory where you unzipped the stsAdminTools.zip file.
deploy_uri is the name of the OpenSSO STS deploy URI. For example: opensso

See Appendix A, "Using the ssoadm Command-Line Interface"for detailed command information.

1.7 Uninstalling the OpenSSO STS Server

Before you begin. If the OpenSSO STS server instance was using the OpenSSO STS data store, the data store port was in use by the LISTEN socket. Stopping the web container server instance or domain should release this port. To check the data store port, use the netstat command. For example, if the OpenSSO data store used default port 50389:

netstat -a | grep 50389

Port 50389 should not be in use for the LISTEN socket. If necessary, release this port.

1.7.1 To Uninstall the OpenSSO STS Server

Undeploy opensso.war in the web container using the web container administration console or command-line utility.
Stop the OpenSSO STS web container.
Remove the following directories and all of their contents:
- ConfigurationDirectory is the directory created when the OpenSSO STS instance is initially configured.
  
  The default directory is opensso in the home directory of the user running the Configurator. If the Configurator is run by root, ConfigurationDirectory is created in the root home directory (/).
- user-home-directory.openssocfg where user-home-directory is the home directory of the user who deployed the opensso.war file. If this user is root, the directory is /.openssocfg.
Optionally, remove the penssosts_11gr1.zip file and extracted files.

1.7.2 To Uninstall the OpenSSO STS Utilities and Scripts

Remove the directory and its contents where stsAdminTools.zip was extracted.
Optionally, remove the stsAdminTools.zip file.