This is part one of the Sun Java System Access ManagerTM 7 2005Q4 Administration Guide. It discusses configuration options that you can perform after Access Manager installation. This part contains the following chapters:
This chapter describes how to configure and deploy Sun JavaTM System Access Manager using the amconfig script and the sample silent mode input file (amsamplesilent). Topics include:
For a new installation, always install the first instance of Access Manager 7 2005Q4 by running the Sun Java Enterprise System (Java ES) installer. When you run the installer, you can select either of these configuration options for Access Manager:
The Configure Now option allows you to install and configure the first instance during the installation by the choices (or default values) that you select on the Access Manager installation panels.
The Configure Later option installs the Access Manager 7 2005Q4 components, and then after installation, you must manually configure them or run the Access Manager scripts as described in Configuring and Reconfiguring an Instance of Access Manager. If you choose this option, then none of the products that you are currently installing will be configured. For example, if you choose to install Access Manager and Application Server and select the Configure Later option, neither application will be configured.
If you are installing BEA WebLogic or IBM WebSphere Application Server as the Access Manager web container, you must choose the Configure Later option when installing Access Manager. See Chapter 2, Installing and Configuring Third-Party Web Containers for more information.
For information about the installer, refer to the Sun Java Enterprise System 2005Q4 Installation Guide for UNIX.
The Java Enterprise System installer installs the Access Manager 7 2005Q4 amconfig script and sample silent mode input file (amsamplesilent) in the AccessManager-base /SUNWam/bin directory on Solaris systems or the AccessManager-base/identity/bin directory on Linux systems.
AccessManager-base represents the Access Manager base installation directory. On Solaris systems, the default base installation directory is /opt, and on Linux systems, it is /opt/sun. However, you can specify another directory, if you prefer, when you run the installer.
The amconfig script is a top-level script that calls other scripts as needed to perform the requested operation. For more information, see the Access Manager amconfig Script.
The sample configuration script input file (amsamplesilent) is a template that you can use to create the input file that you must specify when you run the amconfig script in silent mode.
This sample configuration script input file is an ASCII text file that contains Access Manager configuration variables. Before you run the amconfig script, copy (and rename, if you wish) the amsamplesilent file, and then edit the variables in the file based on your system environment. The configuration variables are in the following format:
variable-name=value
For example:
DEPLOY_LEVEL=1 NEW_INSTANCE=true SERVER_HOST=ishost.example.com
For a list of the variables you can set in a configuration script input file, see the Access Manager Sample Configuration Script Input FileAccess Manager Sample Configuration Script Input File.
The format of the sample configuration script input file used when you run the amconfig script in silent mode does not follow the same format or necessarily use the same variable names as a Java Enterprise System silent installation state file. This file contains sensitive data, such as the administrator password. Make sure to protect or delete this file as appropriate.
After you install first instance of Access Manager using the Sun Java Enterprise System installer, you can run the amconfig script to perform the following operations, depending on the values of the variables in the silent mode input file:
Deploy and configure the first instance of Access manager or deploy and configure for additional instances of Access Manager on the same host system. For example, after you configure an additional instance of a web container, you can then deploy and configure a new Access Manager instance for that web container instance.
Reconfigure both the first instance and any additional instances of Access Manager.
Deploy and configure the Access Manager full server services or only the SDK services, which enables support for these products:
Deploy and configure specific Access Manager components such as the console or Federation Management module.
Uninstall instances and components of Access Manager that you deployed using the amconfig script.
After you run the Java Enterprise System installer, the Access Manager sample configuration script input file (amsamplesilent) is available in the AccessManager-base/SUNWam/bin directory on Solaris systems or the AccessManager-base/identity/bin directory on Linux systems.
To set configuration variables, first copy and rename the amsamplesilent file. Then set the variables in the copy for the operation you want to perform. For an example of this file, see Example Configuration Script Input File.
This sample silent mode input file contains the following configuration variables:
This section describes the values for the required DEPLOY_LEVEL variable. This variable determines the operation you want the amconfig script to perform.
Table 1–1 Access Manager DEPLOY_LEVEL Variable
Operation |
DEPLOY_LEVEL Variable Value and Description |
---|---|
Install |
1 = Full Access Manager installation for a new instance (default) 2 = Install Access Manager console only 3 = Install Access Manager SDK only 4 = Install SDK only and configure the container 5 = Install Federation Management module only 6 = Install server only 7=Install Access Manager and configure the container for deploying with Portal Server. Caution DEPLOY_MODE=7 is intended only for deploying Access Manager with Portal Server. For some deployments, you might want to install the console only and server only on a single host server using different web containers. First, run the Java ES installer to install all Access Manager subcomponents using the Configure Later option. Then, run the amconfig script to configure both the console and server instances. |
Uninstall (unconfigure) |
11 = Full uninstall 12 = Uninstall console only 13 = Uninstall SDK only 14 = Uninstall SDK only and unconfigure the container 15 = Uninstall Federation Management module 16 = Uninstall server only Uninstall Access Manager and unconfigure the container when deployed with Portal Server. Caution DEPLOY_MODE=7 is intended only when Access Manager is deployed with Portal Server. |
Re-install (also referred to as re-deploy or re-configure) |
21 = Redeploy all (console, password, services, and common) web applications. 26 = Undeploy all (console, password, services, and common) web applications. |
This section describes the Access Manager configuration variables.
Table 1–2 Access Manager Configuration Variables
Variable |
Description |
---|---|
AM_REALM |
Indicates the Access Manager mode:
Default: enabled Caution – Access Manager Realm Mode is enabled by default. If you are deploying Access Manager with Portal Server, Messaging Server, Calendar Server, Delegated Administrator, or Instant Messaging, you must select Legacy Mode (AM_REALM=disabled) before you run the amconfig script. |
BASEDIR |
Base installation directory for Access Manager packages. Default: PLATFORM_DEFAULT For Solaris systems, PLATFORM_DEFAULT is /opt For Linux systems, PLATFORM_DEFAULT is /opt/sun |
SERVER_HOST |
Fully qualified host name of the system where Access Manager is running (or will be installed). For a remote SDK installation, set this variable to the host where Access Manager is (or will be) installed and not the remote client host. This variable should match the counterpart variable in the web container configuration. For example, for Application Server 8, this variable should match AS81_HOST. |
SERVER_PORT |
Access Manager port number. Default: 58080 For a remote SDK installation, set this variable to the port on the host where Access Manager is (or will be) installed and not the remote client host. This variable should match the counterpart variable in the web container configuration. For example, for Application Server 8, this variable should match AS81_PORT. |
SERVER_PROTOCOL |
Server protocol: http or https. Default: http For a remote SDK installation, set this variable to the protocol on the host where Access Manager is (or will be) installed and not the remote client host. This variable should match the counterpart variable in the web container configuration. For example, for Application Server 8, this variable should match AS81_PROTOCOL. |
CONSOLE_HOST |
Fully qualified host name of the server where the console is installed. Default: Value provided for the Access Manager host |
CONSOLE_PORT |
Port of the web container where the console is installed and listens for connections. Default: Value provided for the Access Manager port |
CONSOLE_PROTOCOL |
Protocol of the web container where the console is installed. Default: Server protocol |
CONSOLE_REMOTE |
Set to true if the console is remote from the Access Manager services. Otherwise, set to false. Default: false |
DS_HOST |
Fully qualified host name of Directory Server. |
DS_PORT |
Directory Server port. Default: 389. |
DS_DIRMGRDN |
Directory manager DN: the user who has unrestricted access to Directory Server. Default: "cn=Directory Manager" |
DS_DIRMGRPASSWD |
Password for the directory manager See the note about special characters in the description of Access Manager Configuration Variables. |
ROOT_SUFFIX |
Initial or root suffix of the directory. You must make sure that this value exists in the Directory Server you are using. See the note about special characters in the description of Access Manager Configuration Variables. |
ADMINPASSWD |
Password for the administrator (amadmin). Must be different from the password for amldapuser. Note: If the password contains special characters such as a slash (/) or backslash (\\), the special character must be enclosed by single quotes (”). For example: ADMINPASSWD=’\\\\\\\\\\####///’ However, the password cannot have a single quote as one of the actual password characters. |
AMLDAPUSERPASSWD |
Password for amldapuser. Must be different from the password for amadmin. See the note about special characters in the description of Access Manager Configuration Variables. |
CONSOLE_DEPLOY_URI |
URI prefix for accessing the HTML pages, classes and JAR files associated with the Access Manager Administration Console subcomponent. Default: /amconsole |
SERVER_DEPLOY_URI |
URI prefix for accessing the HTML pages, classes, and JAR files associated with the Identity Management and Policy Services Core subcomponent. Default: /amserver |
PASSWORD_DEPLOY_URI |
URI that determines the mapping that the web container running Access Manager will use between a string you specify and a corresponding deployed application. Default: /ampassword |
COMMON_DEPLOY_URI |
URI prefix for accessing the common domain services on the web container. Default: /amcommon |
COOKIE_DOMAIN |
Names of the trusted DNS domains that Access Manager returns to a browser when it grants a session ID to a user. At least one value should be present. In general, the format is the server’s domain name preceded with a period. Example: .example.com |
JAVA_HOME |
Path to the JDK installation directory. Default: /usr/jdk/entsys-j2se. This variable provides the JDK used by the command line interface’s (such as amadmin) executables. The version must be 1.4.2 or later. |
AM_ENC_PWD |
Password encryption key: String that Access Manager uses to encrypt user passwords. Default: none. When the value is set to none, amconfig will generate a password encryption key for the user, so a password encryption will exist for the installation that is either specified by the user or created through amconfig . Important: If you are deploying multiple instances of Access Manager or the remote SDK, all instances must use the same password encryption key. When you deploy an additional instance, copy the value from the am.encryption.pwd property in the AMConfig.properties file for the first instance. |
PLATFORM_LOCALE |
Locale of the platform. Default: en_US (US English) |
NEW_OWNER |
New owner for the Access Manager files after installation. Default: root |
NEW_GROUP |
New group for the Access Manager files after installation. Default: other For a Linux installation, set NEW_GROUP to root. |
PAM_SERVICE_NAME |
Name of the PAM service from the PAM configuration or stack that comes with the operating system and is used for the Unix authentication module (normally other for Solaris or password for Linux). Default: other. |
XML_ENCODING |
XML encoding. Default: ISO-8859-1 |
NEW_INSTANCE |
Specifies whether the configuration script should deploy Access Manager to a new user-created web container instance:
|
SSL_PASSWORD |
Is not used in this release. |
To specify the web container for Access Manager, set the WEB_CONTAINER variable in the silent mode input file. For the versions of the web containers supported by Access Manager 7 2005Q4, see the Sun Java System Access Manager 7 2005Q4 Release Notes.
Table 1–3 Access Manager WEB_CONTAINER Variable
Value |
Web Container |
---|---|
WS6 (default) | |
AS8 | |
WL8 | |
WAS5 |
This section describes the configuration variables for Web Server 6.1 2005Q4 SP5 in the silent mode input file.
Table 1–4 Web Server 6.1 Configuration Variables
Variable |
Description |
---|---|
WS61_INSTANCE |
Name of the Web Server instance on which Access Manager will be deployed or un-deployed. Default: https-web-server-instance-name where web-server-instance-name is the Access Manager host (Access Manager Configuration Variables variable) |
WS61_HOME |
Web Server base installation directory. Default: /opt/SUNWwbsvr |
WS61_PROTOCOL |
Protocol used by the Web Server instance set by the Sun Java System Web Server 6.1 SP5 variable where Access Manager will be deployed: http or https. Default: Access Manager protocol (Access Manager Configuration Variables variable) |
WS61_HOST |
Fully qualified host name for the Web Server instance ( Sun Java System Web Server 6.1 SP5 variable). Default: Access Manager host instance (Access Manager Configuration Variables variable) |
WS61_PORT |
Port on which Web Server listens for connections. Default: Access Manager port number (Access Manager Configuration Variables variable) |
WS61_ADMINPORT |
Port on which the Web Server Administration Server listens for connections. Default: 8888 |
WS61_ADMIN |
User ID of the Web Server administrator. Default: "admin" |
This section describes the configuration variables for Application Server 8.1 in the silent mode input file.
Table 1–5 Application Server 8.1 Configuration Variables
Variable |
Description |
---|---|
AS81_HOME |
Path to the directory where Application Server 8.1 is installed. Default: /opt/SUNWappserver/appserver |
AS81_PROTOCOL |
Protocol used by the Application Server instance: http or https. Default: Access Manager protocol (Access Manager Configuration Variables variable) |
AS81_HOST |
Fully qualified domain name (FQDN) on which the Application Server instance listens for connections. Default: Access Manager host (Access Manager Configuration Variables variable) |
AS81_PORT |
Port on which Application Server instance listens for connections. Default: Access Manager port number (Access Manager Configuration Variables variable) |
AS81_ADMINPORT |
Port on which the Application Server administration server listens for connections. Default: 4849 |
AS81_ADMIN |
Name of the user who administers the Application Server administration server for the domain into which Application Server is being displayed. Default: admin |
AS81_ADMINPASSWD |
Password for the Application Server administrator for the domain into which Application Server is being displayed. See the note about special characters in the description of Access Manager Configuration Variables. |
AS81_INSTANCE |
Name of the Application Server instance that will run Access Manager. Default: server |
AS81_DOMAIN |
Path to the Application Server directory for the domain to which you want to deploy this Access Manager instance. Default: domain1 |
AS81_INSTANCE_DIR |
Path to the directory where Application Server stores files for the instance. Default: /var/opt/SUNWappserver/domains/domain1 |
AS81_DOCS_DIR |
Directory where Application Server stores content documents. Default: /var/opt/SUNWappserver/domains/domain1/docroot |
AS81_ADMIN_IS_SECURE |
Specifies whether the Application Server administration instance is using SSL:
|
This section describes the configuration variables for BEA WebLogic Server 8.1 in the silent mode input file.
Table 1–6 BEA WebLogic Server 8.1 Configuration Variables
Variable |
Description |
---|---|
WL8_HOME |
WebLogic home directory. Default: /usr/local/bea |
WL8_PROJECT_DIR |
WebLogic project directory. Default: user_projects |
WL8_DOMAIN |
WebLogic domain name. Default: mydomain |
WL8_SERVER |
WebLogic server name. Default: myserver |
WL8_INSTANCE |
WebLogic instance name. Default: /usr/local/bea/weblogic81 ($WL8_HOME/weblogic81) |
WL8_PROTOCOL |
WebLogic protocol. Default: http |
WL8_HOST |
WebLogic host name. Default: Host name of the server |
WL8_PORT |
WebLogic port. Default: 7001 |
WL8_SSLPORT |
WebLogic SSL port. Default: 7002 |
WL8_ADMIN |
WebLogic administrator. Default: "weblogic" |
WL8_PASSWORD |
WebLogic administrator password. See the note about special characters in the description of Access Manager Configuration Variables. |
WL8_JDK_HOME |
WebLogic JDK home directory. Default: BEA WebLogic Server 8.1 /jdk142_04 |
WL8_CONFIG_LOCATION |
Should be set to the parent directory of the location of the WebLogic start script. |
This section describes the configuration variables for IBM WebSphere Server 5.1 in the silent mode input file.
Table 1–7 IBM WebSphere 5.1 Configuration Variables
Variable |
Description |
---|---|
WAS51_HOME |
WebSphere home directory. Default: /opt/WebSphere/AppServer |
WAS51_JDK_HOME |
WebSphere JDK home directory. Default: /opt/WebSphere/AppServer/java |
WAS51_CELL |
WebSphere cell. Default: hostname value |
WAS51_NODE |
WebSphere node name. Default: host name of the server where WebSphere is installed. Default: hostname value |
WAS51_INSTANCE |
WebSphere instance name. Default: server1 |
WAS51_PROTOCOL |
WebSphere protocol. Default: http |
WAS51_HOST |
WebSphere host name. Default: Hostname of the server |
WAS51_PORT |
WebSphere port. Default: 9080 |
WAS51_SSLPORT |
WebSphere SSL port. Default: 9081 |
WAS51_ADMIN |
WebSphere administrator. Default: "admin" |
WAS51_ADMINPORT |
WebSphere administrator port. Default: 9090 |
For the versions of Directory Server supported by Access Manager 7 2005Q4, see the Sun Java System Access Manager 7 2005Q4 Release Notes. This section describes the Directory Server configuration variables in the silent mode input file.
Table 1–8 Directory Server Configuration Variables
Variable |
Description |
---|---|
DIRECTORY_MODE |
Directory Server modes: 1 = Use for a new installation of a Directory Information Tree (DIT). 2 = Use for an existing DIT. The naming attributes and object classes are the same, so the configuration scripts load the installExisting.ldif and umsExisting.ldif files. The configuration scripts also update the LDIF and properties files with the actual values entered during configuration (for example, BASE_DIR, SERVER_HOST, and ROOT_SUFFIX). This update is also referred to as “tag swapping,” because the configuration scripts replace the placeholder tags in the files with the actual configuration values. 3 = Use for an existing DIT when you want to do a manual load. The naming attributes and object classes are different, so the configuration scripts do not load the installExisting.ldif and umsExisting.ldif files. The scripts perform tag swapping (described for mode 2). You should inspect and modify (if needed) the LDIF files and then manually load the LDIF files and services. 4 = Use for an existing multi-server installation. The configuration scripts do not load the LDIF files and services, because the operation is against an existing Access Manager installation. The scripts perform tag swapping only (described for mode 2) and adds a server entry in the platform list. 5 = Use for an existing upgrade. The scripts perform tag swapping only (described for mode 2). Default: 1 |
USER_NAMING_ATTR |
User naming attribute: Unique identifier for the user or resource within its relative name space. Default: uid |
ORG_NAMING_ATTR |
Naming attribute of the user’s company or organization. Default: o |
ORG_OBJECT_CLASS |
Organization object class. Default: sunismanagedorganization |
USER_OBJECT_CLASS |
User object class. Default: inetorgperson |
DEFAULT_ORGANIZATION |
Default organization name. Default: none |
After you run the Java Enterprise System installer, the amconfig script is available in the AccessManager-base /SUNWam/bin directory on Solaris systems or the AccessManager-base/identity/bin directory on Linux systems.
The amconfig script reads a silent configuration input file and then calls other scripts in silent mode, as needed, to perform the requested operation.
To run the amconfig script, use this syntax:
amconfig -s input-file |
where:
-s runs amconfig in silent mode.
input-file is the silent configuration input file that contains the configuration variables for the operation you want to perform. For more information, see Access Manager Sample Configuration Script Input File.
Several considerations for running the amconfig script are:
You must be running as superuser (root).
Specify the full path to the amsamplesilent file (or copy of the file). For example:
# cd /opt/SUNWam/bin # ./amconfig -s ./amsamplesilent
or
# ./amconfig -s /opt/SUNWam/bin/amsamplesilent
In the Access Manager 7 2005Q4 release, the following scripts are not supported:
Also, by default amserver start starts only the authentication amsecuridd and amunixd helpers. The amsecuridd helper is available only on the Solaris OS SPARC platform.
After you have installed the first instance of Access Manager using the Java Enterprise System installer, you can deploy and configure additional Access Manager instances by editing the configuration variables in the silent configuration input file and then running the amconfig script.
This section describes the following scenarios:
Before you can deploy a new instance of Access Manager, you must create and start the new web container instance using the administration tools for the web container. For information, refer to the specific web container documentation:
For Web Server, see http://docs.sun.com/coll/1308.1
For Application Server, see http://docs.sun.com/coll/1310.1
The steps described in this section only apply to an Access Manager instance that has been installed with the Configure Now option. If you are planning to use WebLogic or WebSphere as web containers, you must use the Configure Later option when installing Access Manager. See Chapter 2, Installing and Configuring Third-Party Web Containers for more information.
This section describes how to deploy an additional Access Manager instance on a different host server and update the Platform Server List.
Log in as an administrator, depending on the web container for the instance. For example, if Web Server 6.1 will be the web container for the new instance, log in either as superuser (root) or as the user account for the Web Server Administration Server.
Copy the amsamplesilent file to a writable directory and make that directory your current directory. For example, you might create a directory named /newinstances.
Tip Rename the copy of the amsamplesilent file to describe the new instance you want to deploy. For example, the following steps use an input file named amnewws6instance to install a new instance for Web Server 6.1.
Set the following variables in the new amnewws6instance file:
DEPLOY_LEVEL=1 NEW_INSTANCE=true |
Set other variables in the amnewws6instance file as required for the new instance you want to create. For a description of these variables, refer to the tables in the following sections:
Access Manager Configuration Variables
Directory Server Configuration Variables
Important All Access Manager instances must use the same value for the password encryption key. To set the AM_ENC_PWD variable for this instance, copy the value from the am.encryption.pwd property in the AMConfig.properties file for the first instance.
In case you might need to uninstall this instance later, save the amnewws6instance file.
Run the amconfig, specifying the new amnewws6instance file. For example, on Solaris systems:
# cd opt/SUNWam/bin/ # ./amconfig -s ./newinstances/amnewws6instance |
The -s option runs the amconfig script in silent mode.
The amconfig script calls other configuration scripts as needed, using variables in the amnewws6instance file to deploy the new instance.
When you crate an additional container instance, you must update the Access Manager Platform Server list to reflect the addition of the container(s).
Log in to the Access Manager Console as the top-level administrator.
Click on the Service Configuration tab.
Click on the Platform service.
Enter the following information for the new instance in the Server List:
protocol://fqdn:port|instance-number
The instance number should be the next available number that is not in use.
Click Add.
Click Save.
You can configure an instance of Access Manager that was installed with the Configure Later option or reconfigure the first instance that was installed using Configure Now option in the Java Enterprise System installer by running the amconfig script.
For example, you might want to reconfigure an instance to change the Access Manager owner and group.
Log in as an administrator, depending on the web container for the instance. For example, if Web Server 6.1 is the web container, log in either as superuser (root) or as the user account for Web Server Administration Server.
Copy the silent configuration input file you used to deploy the instance to a writable directory and make that directory your current directory. For example, to reconfigure an instance for Web Server 6.1, the following steps use an input file named amnewinstanceforWS61 in the /reconfig directory.
In the amnewinstanceforWS61 file, set the DEPLOY_LEVEL variable to one of the values described for a Deployment Mode Variable operation. For example, set DEPLOY_LEVEL=21 to reconfigure a full installation.
In the amnewinstanceforWS61 file, set the NEW_INSTANCE variable to false:
NEW_INSTANCE=false |
Set other variables in the amnewinstanceforWS61 file to reconfigure the instance. For example, to change the owner and group for the instance, set the NEW_OWNER and NEW_GROUP variables to their new values.
For a description of other variables, refer to the tables in the following sections:
Run the amconfig script, specifying your edited input file. For example, on Solaris systems:
# cd opt/SUNWam/bin/ # ./amconfig -s ./reconfig/amnewinstanceforWS61 |
The -s option runs the script in silent mode. The amconfig script calls other configuration scripts as needed, using variables in the amnewinstanceforWS61 file to reconfigure the instance.
You can uninstall an instance of Access Manager that was installed by running the amconfig script. You can also temporarily unconfigure an instance of Access Manager, and unless you remove the web container instance, it is still available for you to re-deploy another Access Manager instance later.
Log in as an administrator, depending on the web container for the instance. For example, if Web Server 6.1 is the web container, log in either as superuser (root) or as the user account for Web Server Administration Server.
Copy the silent configuration input file you used to deploy the instance to a writable directory and make that directory your current directory. For example, to unconfigure an instance for Web Server 6.1, the following steps use an input file named amnewinstanceforWS61 in the /unconfigure directory.
In the amnewinstanceforWS61 file, set the DEPLOY_LEVEL variable to one of the values described for an Deployment Mode Variable operation. For example, set DEPLOY_LEVEL=11 to uninstall (or unconfigure) a full installation.
Run the amconfig script, specifying your edited input file. For example, on Solaris systems:
# cd opt/SUNWam/bin/ # ./amconfig -s ./unconfigure/aminstanceforWS61 |
The -s option runs the script in silent mode. The amconfig script reads the amnewinstanceforWS61 file and then uninstalls the instance.
The web container instance is still available if you want to use it to re-deploy another Access Manager instance later.
This scenario completely removes all Access Manager 7 2005Q4 instances and packages from a system.
Log in as or become superuser (root).
In the input file you used to deploy the instance, set the DEPLOY_LEVEL variable to one of the values described for an Deployment Mode Variable operation. For example, set DEPLOY_LEVEL=11 to uninstall (or unconfigure) a full installation.
Run the amconfig script using the file you edited in Uninstalling All Access Manager Instances. For example on Solaris systems:
# cd opt/SUNWam/bin/ # ./amconfig -s ./newinstances/amnewws6instance |
The amconfig script runs in silent mode to uninstall the instance.
Repeat these steps for any other Access Manager instances you want to uninstall, except for the first instance, which is the instance you installed using the Java Enterprise System installer.
To uninstall the first instance and remove all Access Manager packages from the system, run the Java Enterprise System uninstaller. For information about the uninstaller, refer to the Sun Java Enterprise System 2005Q4 Installation Guide for UNIX.
The following section includes an example of an Access Manager configuration script input file for deployment with WebLogic 8.1.
DEPLOY_LEVEL=1 BASEDIR=/opt SERVER_HOST=ide-56.example.company.com SERVER_PORT=7001 SERVER_PROTOCOL=http CONSOLE_HOST=$SERVER_HOST CONSOLE_PORT=$SERVER_PORT CONSOLE_PROTOCOL=$SERVER_PROTOCOL CONSOLE_REMOTE=false DS_HOST=ide-56.example.company.com DS_PORT=389 DS_DIRMGRDN=”cn=Directory Manager” DS_DIRMGRPASSWD=11111111 ROOT_SUFFIX=”dc=company,dc=com” ADMINPASSWD=11111111 AMLDAPUSERPASSWD=00000000 CONSOLE_DEPLOY_URI=/amconsole SERVER_DEPLOY_URI=/amserver PASSWORD_DEPLOY_URI=/ampassword COMMON_DEPLOY_URI=/amcommon COOKIE_DOMAIN=.iplanet.com JAVA_HOME=/usr/jdk/entsys-j2se AM_ENC_PWD=”” PLATFORM_LOCALE=en_US NEW_OWNER=root NEW_GROUP=other XML_ENCODING=ISO-8859-1 NEW_INSTANCE=false WEB_CONTAINER=WL8 WL8_HOME=/export/bea8 WL8_PROJECT_DIR=user_projects WL8_DOMAIN=mydomain WL8_CONFIG_LOCATION=$WL8_HOME/$WL8_PROJECT_DIR/domains WL8_SERVER=myserver WL8_INSTANCE=/export/bea8/weblogic81 WL8_PROTOCOL=http WL8_HOST=ide-56.example.company.com WL8_PORT=7001 WL8_SSLPORT=7002 WL8_ADMIN=”weblogic” WL8_PASSWORD=”11111111” WL8_JDK_HOME=$WL8_HOME/jdk142_04 DIRECTORY_MODE=1 USER_NAMING_ATTR=uid ORG_NAMING_ATTR=o ORG_OBJECT_CLASS=examplemanagedorganization USER_OBJECT_CLASS=inetorgperson DEFAULT_ORGANIZATION= Sample Configuration Script Input File for WebLogic 8.1.x |
This chapter describes the procedures for installing and configuring third-party web containers deployed with Sun Java™ System Access Manager. For this release, Access Manager supports BEA WebLogic 8.1 (and its current patches) and IBM WebSphere 5.1 (and its current patches).
WebLogic and WebSphere are not part of the Java Enterprise System, so you must install and configure them independently of the Java ES Install program. In general the procedures are:
Install, configure, and start the web container instance.
Install the Directory Server from the Java ES installer.
Install Access Manager from the Java ES Installer in Configure Later Mode, which will leave Access Manager in an unconfigured state.
Run the Access Manager configuration scripts to deploy Access Manager in the web container.
Restart the web container.
Before you install WebLogic, make sure that your host domain is registered in DNS. Also, verify that you are installing the correct version of the WebLogic software. For more information, go to the BEA product site at http://commerce.bea.com/index.jsp.
Unpack the downloaded software image, either in .zip or .gz format. Make sure that the zip/gzip utility is for the correct platform or you may receive a checksum error during the unpackaging.
Run the installation program from a shell window of your target system.
Follow the procedures provided by the WebLogic installation utility (detailed installation instructions can be found at http://e-docs.bea.com/wls/docs81/).
During the installation process, make sure that you record the following information, to be used later in the Access Manager configuration:
Once installation is complete, run the WebLogic configuration tool to configure the domain and server instance from the following location:
WebLogic-base/WebLogic-instance/common/bin/quickstart.sh
By default, WebLogic defines the server instance as myserver and the domain as mydomain. It is unlikely that you will choose to use these defaults. If you create a new domain and instance, make sure that you record the information for Access Manager configuration and deployment. See the WebLogic 8.1 documentation for instructions.
If you are installing on an administration instance, start WebLogic by using the startWebLogic.sh utility from the following location:
WebLogic-base/WebLogic-Userhome/domains/ WebLogic-domain/startWebLogic.sh
If you are installing on a managed instance, start WebLogic by using the following command:
WebLogic-base/WebLogic-Userhome/domains/ WebLogic-domain/startManagedWebLogic WebLogic-managed-instancename admin-url
Before you install WebSphere, make sure that your host domain is registered in DNS and verify that you are installing the correct version of the WebSphere software for your platform. For more information, go to the IBM product support website at http://www-306.ibm.com/software/websphere/support/.
Unpack the downloaded software image, either in .zip or .gz format. Make sure that the zip/gzip utility is for the correct platform or you may receive a checksum error during the unpackaging.
Run the installation program from a shell window of your target system. If you are planning on installing a patch, install the 5.1 version first and apply the patch later. Detailed installation instructions can be found at http://publib.boulder.ibm.com/infocenter/ws51help/index.jsp.
During the installation process, make sure that you record the following information to be used later in the Access Manager configuration:
hostname
domain name
cell name
node name
port number
installation directory
WebSphere instance name
administration port
By default, WebSphere defines the server instance as server1, however it is unlikely that you will the default. If you create a new instance, make sure that you record the information for Access Manager configuration and deployment. See the WebSphere 5.1 documentation for instructions.
Verify that the installation was successful.
Make sure the server.xml file exists in the following directory:
/opt/WebSphere/AppServer/config/cells/cell-name/noes/
node-name/servers/server1
Use the startServer.sh command to start the server, for example:
/opt/WebSphere/AppServer/bin/startServer.sh server1
In a web browser, enter the corresponding URL of the following format to view the sample web application:
http:// fqdn:portnumber/snoop
Once you have verified a successful installation, stop the server using the stopServer.sh utility. For example:
opt/WebSphere/AppServer/bin/stopServer.sh server1
If you are installing WebSphere 5.1 patch, use the updateWizard.sh command line utility to install the patch over the original 5.1 instance.
Restart WebSphere and verify that the installation was successful.
Access Manager installation involves two separate invocations of the Java Enterprise System (Java ES) Installer.
Run the first Java ES invocation to install Directory Server (either local or remote) with the Configure Now option. The Configure Now option allows you to configure the first instance during the installation by the choices (or default values) that you select.
Run the second Java ES invocation to install Access Manager with the Configure Later option. This option Installs the Access Manager 2005Q4 components. After installation, you must configure Access Manager.
WebLogic and WebSphere are installed independently of Java ES, so the Installer does not contain the necessary configuration data to automatically deploy the containers. Because of this, you must select the Configure Later option when installing Access Manager. This option leaves your Access Manager deployment in the following state:
The active Directory Server (either Local or Remote) does not have Access Manager DIT data loaded.
Access Manager configuration files are not automatically loaded.
Access Manager web application .war files are not generated.
Access Manager deployment and post-installation configuration processes are not automatically started and run.
For detailed installation instructions, refer to the Sun Java Enterprise System Installation Guide located at http://download.oracle.com/819-0056.
After you have completed Access Manager installation on the target system’s local drive, you need to manually configure Access Manager with either WebLogic 8.1 or WebSphere 5.1. This is a three-step process:
The Access Manager configuration script input file contains all of the deployment level, Access Manager, web container, and Directory Server variable definitions. Access Manager contains a sample configuration script input file template (amsamplesilent) which is available in the AccessManager-base /SUNWam/bin directory on Solaris systems or the AccessManager-base /identity/bin directory on Linux systems.
You can use the amsamplesilent template to construct your configuration script input file. Instructions for editing the file, as well as the variable definitions, are described in Access Manager Sample Configuration Script Input File.
Before you edit the file, make sure that you have the following information available from your web container installation:
installation location
instance name and location
hostname
FQDN
port number to which it is listening
administration ID
protocol used
administration password
shared library location
domain name and location
project directory name
JDK location
cell name
node name
JDK location
When you have saved the configuration script input file, you run the amconfig script to complete the configuration process. For example:
AccessManager-base/SUMWam/bin/amconfig -s silentfile
silentfile should be the absolute path to the configuration input file.
Running this script performs the following functions:
Loads the Access Manager schema to the active Directory Server instance.
Loads the Access Manager service data to the Directory Server instance.
Generates the Access Manager configuration files used by the active Access Manager instance.
Deploys the Access Manager web application data to the web container.
Customizes the web container configuration to match the Access Manager requirements.
After you have completed the configuration process, you must restart the web container. Refer to your product’s documentation for instructions.
For BEA WebLogic 8.1, see http://e-docs.bea.com/wls/docs81.
For IBM WebSphere 5.1, see http://publib.boulder.ibm.com/infocenter/ws51help/index.jsp.
Using Secure Socket Layer (SSL) with simple authentication guarantees confidentiality and data integrity. To enable Access Manager in SSL, mode you would typically:
Configure Access Manager with a secure web container
Configure Access Manager to a secure Directory Server
To configure Access Manager in SSL mode with Web Server, see the following steps:
In the Access Manager console, go to the Service Configuration module and select the Platform service. In the Server List attribute, remove the http:// protocol, and add the https:// protocol. Click Save.
Be sure to click Save. If you don’t, you will still be able to proceed with the following steps, but all configuration changes you have made will be lost and you will not be able to log in as administrator to fix it.
Steps 2 through 24 describe the Web Server.
Log on to the Web Server console. The default port is 8888.
Select the Web Server instance on which Access Manager is running, and click Manage.
This displays a pop-up window explaining that the configuration has changed. Click OK.
Click on the Apply button located top right corner of the screen.
Click Apply Changes.
The Web Server should automatically restart. Click OK to continue.
Stop the selected Web Server instance.
Click the Security Tab.
Click on Create Database.
Enter the new database password and click OK.
Ensure that you write down the database password for later use.
Once the Certificate Database has been created, click on Request a Certificate.
Enter the data in the fields provided in the screen.
The Key Pair Field Password field is the same as you entered in Step 9. In the location field, you will need to spell out the location completely. Abbreviations, such as CA, will not work. All of the fields must be defined. In the Common Name field, provide the hostname of your Web Server.
Once the form is submitted, you will see a message such as:
--BEGIN CERTIFICATE REQUEST--- afajsdllwqeroisdaoi234rlkqwelkasjlasnvdknbslajowijalsdkjfalsdflasdf alsfjawoeirjoi2ejowdnlkswnvnwofijwoeijfwiepwerfoiqeroijeprwpfrwl --END CERTIFICATE REQUEST-- |
Copy this text and submit it for the certificate request.
Ensure that you get the Root CA certificate.
You will receive a certificate response containing the certificate, such as:
--BEGIN CERTIFICATE--- afajsdllwqeroisdaoi234rlkqwelkasjlasnvdknbslajowijalsdkjfalsdflasdf alsfjawoeirjoi2ejowdnlkswnvnwofijwoeijfwiepwerfoiqeroijeprwpfrwl --END CERTIFICATE--- |
Copy this text into your clipboard, or save the text into a file.
Go to the Web Server console and click on Install Certificate.
Click on Certificate for this Server.
Enter the Certificate Database password in the Key Pair File Password field.
Paste the certificate into the provided text field, or check the radio button and enter the filename in the text box. Click Submit.
The browser will display the certificate, and provide a button to add the certificate.
Click Install Certificate.
Click Certificate for Trusted Certificate Authority.
Install the Root CA Certificate in the same manner described in steps 16 through 21.
Once you have completed installing both certificates, click on the Preferences tab in the Web Server console.
Select Add Listen Socket if you wish to have SSL enabled on a different port. Then, select Edit Listen Socket.
Change the security status from Disabled to Enabled, and click OK to submit the changes, click Apply and Apply Changes.
Steps 26–29 apply to Access Manager.
Open the AMConfig.properties file. By default, the location of this file is etc/opt/SUNWam/config.
Replace all of the protocol occurrences of http:// to https://, except for the Web Server Instance Directory. This is also specified in AMConfig.properties, but must remain the same.
Save the AMConfig.properties file.
In the Web Server console, click the ON/OFF button for the Access Manager hosting web server instance.
The Web Server displays a text box in the Start/Stop page.
Enter the Certificate Database password in the text field and select Start.
Setting up Access Manager to run on an SSL-enabled Application server is a two-step process. First, secure the Application Server instance to the installed Access Manager, then configure Access Manager itself.
This section describes the steps to set up Application Server 6.2 in SSL mode.
Log into the Sun Java System Application Server console as an administrator by entering the following address in your browser:
http://fullservername:port
The default port is 4848.
Enter the username and password you entered during installation.
Select the Application Server instance on which you installed (or will install) Access Manager. The right frame displays that the configuration has changed.
Click Apply Changes.
Click Restart. The Application Server should automatically restart.
In the left frame, click Security.
Click the Manage Database tab.
Click Create Database, if it is not selected.
Enter the new database password and confirm, then click the OK button. Make sure that you write down the database password for later use.
Once the Certificate Database has been created, click the Certificate Management tab.
Click the Request link, if it is not selected.
Enter the following Request data for the certificate
Select it if this is a new certificate or a certificate renewal. Many certificates expire after a specific period of time and some certificate authorities (CA) will automatically send you renewal notification.
Specify the way in which you want to submit the request for the certificate.
If the CA expects to receive the request in an E-mail message, check CA E-mail and enter the E-mail address of the CA. For a list of CAs, click List of Available Certificate Authorities.
If you are requesting the certificate from an internal CA that is using the Certificate Server, click CA URL and enter the URL for the Certificate Server. This URL should point to the certificate server’s program that handles certificate requests.
Enter the password for your key-pair file (this is the password you specified in step 9).
Enter the following identification information:
Common Name. The full name of the server including the port number.
Requestor Name. The name of the requestor.
Telephone Number. The telephone number of the requestor
Common Name . The fully qualified name of the Sun Java System Application Server on which the digital certificate will be installed.
E-mail Address. The E-mail address of the administrator.
Organization Name. The name of your organization. The certificate authority may require any host names entered in this attribute belong to a domain registered to this organization.
Organizational Unit Name. The name of your division, department, or other operational unit of your organization.
Locality Name (city). The name of your city or town.
State Name. The name of the state or province in which your organization operates if your organization is in the United States or Canada, respectively. Do not abbreviate.
Country Code. The two-letter ISO code for your country. For example, the code for the United States is US.
Click the OK button. A message will be displayed, for example:
--BEGIN NEW CERTIFICATE REQUEST--- afajsdllwqeroisdaoi234rlkqwelkasjlasnvdknbslajowijalsdkjfalsdfla alsfjawoeirjoi2ejowdnlkswnvnwofijwoeijfwiepwerfoiqeroijeprwpfrwl --END NEW CERTIFICATE REQUEST-- |
Copy all of this text to a file and click OK. Make sure that you get the Root CA certificate.
Select a CA and follow the instructions on that authority’s web site to get a digital certificate. You can get the certificate from CMS, Verisign or Entrust.net
After you receive your digital certificate from the certificate authority, you can copy the text into your clipboard, or save the text into a file.
Go to the Application Server console and click on the Install link.
Select Certificate For This Server.
Enter the Certificate Database password in the Key Pair File Password field.
Paste the certificate into the provided text field, Message text (with headers), or enter the filename in the Message that is in this file text box. Select the appropriate radio button.
Click OK button. The browser displays the certificate, and provides a button to add the certificate.
Click Add Server Certificate.
Install the Root CA Certificate in the same manner described above. However, select Certificate for Trusted Certificate Authority.
Once you have completed installing both certificates, expand the HTTP Server node in the left frame
Select HTTP Listeners under HTTP Server.
Select http-listener-1. The browser displays the socket information.
Change the value of the port used by http-listener-1 from the value entered while installing application server, to a more appropriate value such as 443.
Select SSL/TLS Enabled.
Select Certificate Nickname.
Specify the Return server. This should match the common name specified in Step 12.
Click Save.
Select the Application Server instance on which you will install the Access Manager software. The right frame shows that the configuration has changed.
Click Apply Changes.
Click Restart. The application server should automatically restart.
The basic steps to configure Application Server 8.1 with SSL are as follows. See the Application Server 8.1 documentation for detailed instructions.
Create a secure port on the Application server through the Application Server Administration console. For more information, see “Configuring Security” in the Sun Java System Application Server Enterprise Edition 8.1 Administration Guide at the following location:
Verify that the certificate authority (CA) that trusts the server's certificate is present in the web container's trust database. Then, obtain and install a server certificate for the web container. For more information, see “Working with Certificates and SSL” in the Sun Java System Application Server Enterprise Edition 8.1 Administration Guide at the following location:
Restart the web container.
This section describes the steps to configure Access Manager in SSL mode. Before you set up SSL for Access Manager, make sure that you configured the web container for your deployment.
In the Access Manager console, go to the Service Configuration module and select the Platform service. In the Server List attribute, add the same URL with the HTTPS protocol and an SSL-enabled port number. Click Save.
If a single instance of Access Manager is listening on two ports (one in HTTP and one in HTTPS) and you try to access Access Manager with a stalled cookie, Access Manager will become unresponsive. This is not a supported configuration.
Open the AMConfig.properties file from the following default location:
/etc/opt/SUNWam/config. |
Replace all of the protocol occurrences of http:// to https:// and change the port number to an SSL-enabled port number.
Save the AMConfig.properties file.
Restart the Application Server.
The BEA WebLogic Server must first be installed and configured as a web container before you configure it with the AMSDK in SSL. For installation instructions, see the BEA WebLogic server documentation. To configure WebLogic as a web container for Access Manager, see Chapter 1, Access Manager 7 2005Q4 Configuration Scripts.
Create a domain using the quick start menu
Go to the WebLogic installation directory and generate the certificate request.
Apply for the server certificate using the CSR text file to a CA.
Save the approved certificate in to a text file. For example, approvedcert.txt.
Load the Root CA in cacerts by using the following commands:
cd jdk141_03/jre/lib/security/
jdk141_03/jre/bin/keytool -keystore cacerts -keyalg RSA -import -trustcacerts -alias "<alias name>" -storepass changeit -file /opt/bea81/cacert.txt
Load the Server certificate by using the following command:
jdk141_03/jre/bin/keytool -import -keystore <keystorename> -keyalg RSA -import -trustcacerts -file approvedcert.txt -alias "mykey"
Login to WebLogic console with your username and password.
Browse to the following location:
yourdomain> Servers> myserver> Configure Keystores
Select Custom Identity and then Java Standard Trust
Enter the keystore location. For example, /opt/bea81/keystore .
Enter Keystore Password and Keystore Pass Phrase. For example:
Keystore Password: JKS/Java Standard Trust (for WL 8.1 it is only JKS)
Key Store Pass Phrase: changeit
Review the SSL Private Key Settings Private Key alias and password.
You must use the full strength SSL licence or SSL startup will fail
In Access Manager, the following parameters in AmConfig.properties are automatically configured during installation. If they are not, you can edit them appropriately:
com.sun.identity.jss.donotInstallAtHighestPriority=true [ this is not required for AM 6.3 and above] com.iplanet.security.SecureRandomFactoryImpl=com.iplanet.am.util.SecureRandomFactoryImpl com.iplanet.security.SSLSocketFactoryImpl=netscape.ldap.factory.JSSESocketFactory com.iplanet.security.encryptor=com.iplanet.services.util.JCEEncryption |
If your JDK path is the following:
com.iplanet.am.jdk.path=/usr/jdk/entsys-j2se |
then use the keytool utility to import the root CA in the certificate database. For example:
/usr/jdk/entsys-j2se/jre/lib/security /usr/jdk/entsys-j2se/jre/bin/keytool -keystore cacerts -keyalg RSA -import -trustcacerts -alias "machinename" -storepass changeit -file /opt/bea81/cacert.txt |
The keytool utility is located in the following directory:
/usr/jdk/entsys-j2se/jre/bin/keytool |
Remove -D"java.protocol.handler.pkgs=com.iplanet.services.comm" from the Access Manager amadmin command line utility.
Configure Access Manager in SSL Mode. For more information, see Configuring Access Manager in SSL Mode.
The IBM WebSphere Server must first be installed and configured as a web container before you configure it with the AMSDK in SSL. For installation instructions, see the WebSphere server documentation. To configure WebLogic as a web container for Access Manager, see Chapter 1, Access Manager 7 2005Q4 Configuration Scripts.
Start ikeyman.sh, located in the Websphere /bin directory.
From the Signer menu, import the certification authority’s (CA) certificate.
From the Personal Certs menu, generate the CSR.
Retrieve the certificate created in the previous step.
Select Personal Certificates and import the server certificate.
From the WebSphere console, change the default SSL settings and select the ciphers.
Set the default IBM JSSE SSL provider.
Enter the following command to import the Root CA certificate from the file you just created into application server JVM Keystore:
$ appserver_root-dir/java/bin/ keytool -import -trustcacerts -alias cmscacert -keystore ../jre/lib/security/cacerts -file /full_path_cacert_filename.txt |
app-server-root-dir is the root directory for the application server and full_path_cacert_filename.txt is the full path to the file containing the certificate.
In Access Manager, update the following parameters in AmConfig.properties to use JSSE:
com.sun.identity.jss.donotInstallAtHighestPriority=true com.iplanet.security.SecureRandomFactoryImpl=com.iplanet. am.util.SecureRandomFactoryImpl com.iplanet.security.SSLSocketFactorImpl=netscape.ldap.factory. JSSESocketFactory com.iplanet.security.encyptor=com.iplanet.services.unil.JCEEncryption |
Configure Access Manager in SSL Mode. For more information, see Configuring Access Manager in SSL Mode.
To provide secure communications over the network, Access Manager includes the LDAPS communications protocol. LDAPS is the standard LDAP protocol, but it runs on top of the Secure Sockets Layer (SSL). In order to enable SSL communication, you must first configure the Directory Server in SSL mode and then connect Access Manager to Directory Server. The basic steps are as follows:
Obtain and install a certificate for your Directory Server, and configure the Directory Server to trust the certification authority’s (CA) certificate
Turn on SSL in your directory.
Configure the authentication, policy and platform services to connect to an SSL-enabled Directory Server.
Configure Access Manager to securely connect to the Directory Server backend.
In order to configure the Directory Server in SSL mode, you must obtain and install a server certificate, configure the Directory Server to trust the CA’s certificate and enable SSL. Detailed instructions on how to complete these tasks are included in Chapter 11, “Managing Authentication and Encryption” in the Directory Server Administration Guide. This document can be found in the following location:
http://docs.sun.com/coll/DirectoryServer_04q2
If your Directory Server is already SSL-enabled, go to the next section for details on connecting Access Manager to Directory Server.
Once the Directory Server has been configured for SSL mode, you need to securely connect Access Manager to the Directory Server backend.
In the Access Manager Console, go to the LDAP Authentication service in the Service Configuration module.
Go to the Membership Authentication service in the Service Configuration module.
Go to the Policy Configuration service located in Service Configuration.
Open the serverconfig.xml in a text editor. The file is in the following location:
/etc/opt/SUNWam/config
Open the AMConfig.properties file from the following default location:
/etc/opt/SUNWam/config.
Change the following properties:
Restart the server