h1. Install / Uninstall OpenSSO Web Services Security Agent 3.0 Using Installer
Starting from 6/15/2009 OpenSSO nightly build, the OpenSSO Web Services Security Agent 3.0 for Glassfish is bundled with an installer. The installer can be used to install and uninstall the WSS Agent. It also has other functionalities, such as version display, encryption key generation, password encryption, etc.
In the following sections, we will describe the steps on how to use these features.
Assume OpenSSO server has been deployed using the nightly build [OpenSSO nightly build download | https://opensso.dev.java.net/public/use/index.html]
The opensso server url is http://myhost.red.iplanet.com:8080/opensso.
The glassfish is installed at /space/products/glassfishv2/glassfish.
h2. Install OpenSSO Web Services Security Agent 3.0 nightly build for glassfish
{noformat}
1. Stop the agent container.
2. Download openssowssproviders.zip from http://download.java.net/general/opensso/nightly/latest/wssagents/openssowssproviders.zip.
3. Unzip it to an install directory say /myagent.
The installer will ask for the name of the agent profile which is used for authenticating the agent and accessing
the WSC/WSP/STSClient profiles. By default, OpenSSO has an agent profile named "agentAuth". Its password is set to
"changeit". This agent profile has the permission to read the profiles of the default WSC/WSP/STSClient (named as
"wsc", "wsp", "SecurityTokenService" respectively) created out of box. This install process will use "agentAuth"
as the agent profile name.
Create a text file /myagent/passwordfile that contains the agent user password "changeit" (quotes not included) in
clear text.
4. cd to /myagent/bin
5. chmod 755 wssagentadmin
6. Start installation: ./wssagentadmin --install
************************************************************************
Welcome to the OpenSSO WSS Agent 3.0 for Sun Java System Application Server 9.1.
************************************************************************
Enter the complete path to the directory which is used by Application Server
to store its configuration Files. This directory uniquely identifies the
Application Server instance that is secured by this Agent.
[ ? : Help, ! : Exit ]
Enter the Application Server Config Directory Path
[/opt/SUNWappserver/domains/domain1/config]: /space/products/glassfishv2/glassfish/domains/domain1/config
Enter the URL where the OpenSSO server is running. Please include the
deployment URI also as shown below:
(http://opensso.sample.com:58080/opensso)
[ ? : Help, < : Back, ! : Exit ]
OpenSSO server URL: http://myhost.red.iplanet.com:8080/opensso
Enter the Agent profile name
[ ? : Help, < : Back, ! : Exit ]
Enter the Agent Profile name: agentAuth
Enter the path to a file that contains the password to be used for identifying
the Agent.
[ ? : Help, < : Back, ! : Exit ]
Enter the path to the password file: /myagent/passwordfile
-----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
Application Server Config Directory :
/space/products/glassfishv2/glassfish/domains/domain1/config
Application Server Instance name : server
OpenSSO server URL : http://myhost.red.iplanet.com:8080/opensso
Agent Profile name : agentAuth
Agent Profile Password file name : /myagent/passwordfile
Verify your settings above and decide from the choices below.
1. Continue with Installation
2. Back to the last interaction
3. Start Over
4. Exit
Please make your selection [1]:
Creating directory layout and configuring WSSAgent file for WSSAgent_001
instance ...DONE.
Reading data from file /tmp/passwdfile and encrypting it ...DONE.
Creating tag swapped AMConfig.properties file for instance WSSAgent_001
...DONE.
Creating a backup for file
/space/products/glassfishv2/glassfish/domains/domain1/config/domain.xml
...DONE.
Adding Agent parameters to
/space/products/glassfishv2/glassfish/domains/domain1/config/domain.xml
file ...DONE.
Creating a backup for file
/space/products/glassfishv2/glassfish/lib/webservices-rt.jar
...DONE.
Creating a backup for file
/space/products/glassfishv2/glassfish/lib/webservices-tools.jar
...DONE.
Creating a backup for file
/space/products/glassfishv2/glassfish/lib/endorsed/webservices-api.jar
...DONE.
DONE.
SUMMARY OF AGENT INSTALLATION
-----------------------------
Agent instance name: WSSAgent_001
Agent Debug directory location: /myagent/WSSAgent_001/logs/debug
Install log file location:
/myagent/installer-logs/audit/install.log
Thank you for using OpenSSO WSS Agent 3.0.
7. Restart the agent container.
Agent install is completed.
{noformat}
h2. Uninstall OpenSSO Web Services Security Agent 3.0
{noformat}
1. Stop the agent container.
2. cd to /myagent/bin
3. Start uninstall: ./wssagentadmin --uninstall
************************************************************************
Welcome to the OpenSSO WSS Agent 3.0 for Sun Java System Application Server
9.1.
************************************************************************
Enter the complete path to the directory which is used by Application Server
to store its configuration Files. This directory uniquely identifies the
Application Server instance that is secured by this Agent.
[ ? : Help, ! : Exit ]
Enter the Application Server Config Directory Path
[/opt/SUNWappserver/domains/domain1/config]: /space/products/glassfishv2/glassfish/domains/domain1/config
Enter the name of the Application Server instance that is secured by this Agent.[ ? : Help, < : Back, ! : Exit ]
Enter the Application Server Instance name [server]: server
-----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
Application Server Config Directory :
/space/products/glassfishv2/glassfish/domains/wsc/config
Application Server Instance name : server
Verify your settings above and decide from the choices below.
1. Continue with Uninstallation
2. Back to the last interaction
3. Start Over
4. Exit
Please make your selection [1]:
DONE.
Removing Agent parameters from
/space/products/glassfishv2/glassfish/domains/domain1/config/domain.xml
file ...DONE.
Deleting the config directory
/myagent/WSSAgent_001/config ...DONE.
Uninstall log file location:
/myagent/installer-logs/audit/uninstall.log
Thank you for using OpenSSO WSS Agent 3.0.
4. Restart the agent container.
Agent uninstall is completed.
{noformat}
h2. Get Version Information of OpenSSO Web Services Security Agent 3.0
{noformat}
1. cd to /myagent/bin
2. check version: ./wssagentadmin --version
------------------------------------------------------------------------
Sun OpenSSO Web Services Security Agent for:
Sun Java(TM) System Application Server 9.1
------------------------------------------------------------------------
Version: 3.0
Build Date: 20090615
{noformat}
h2. Get a Randomly Generated Encryption Key Using wssagentadmin
{noformat}
1. cd to /myagent/bin
2. Generate encryption key: ./wssagentadmin --getEncryptKey
Agent Encryption Key : U74Cpx6qW/u+ryyhL4f/y6wC0DifhWC7
{noformat}
h2. Encrypt a Password Using wssagentadmin
{noformat}
1. cd to /myagent/bin
2. Create a text file /tmp/passwdfile that contains only the clear text password to be encrypted.
3. Encrypt the password: ./wssagentadmin --encrypt WSSAgent_001 /tmp/passwdfile
The encrypted value is: AQIC5wM2LR4Sfcz6b5obkUIFEt5eZQtbU3Tr
The encryption is based on the encryption key specified by am.encryption.pwd property setting in the
staging configuration file /myagent/WSSAgent_001/config/AMConfig.properties
{noformat}
h2. Change Encryption Key of an Installed WSS Agent
{noformat}
After an WSS Agent is installed onto a Glassfish domain, the agent configuration file AMConfig.properties gets placed
in /space/products/glassfishv2/glassfish/addons/opensso. There is also an AMConfig.properties in
/myagent/WSSAgent_001/config. However the latter is used as a staging file only. The effective agent configuration is
the one in /space/products/glassfishv2/glassfish/addons/opensso. The passwords of agent profile user and key store are
encrypted using the encryption key specified by am.encryption.pwd in the AMConfig.properties. In the case that a user
needs to change the encryption key, the following procedure should be followed:
1. Choose a desired encryption key or use wssagentadmin to generate a random one.
2. Set the property am.encryption.pwd to this encryption key in the STAGING configuration file
/myagent/WSSAgent_001/config/AMConfig.properties.
3. Create a text file which contains only the agent profile user password in clear text, say /myagent/agentpasswd
4. cd to /myagent/bin; do: ./wssagentadmin --encrypt WSSAgent_001 /myagent/agentpasswd
5. The above command generates an encrypted password for the agent profile user. Set it to the property
com.iplanet.am.service.secret in the STAGING configuration file /myagent/WSSAgent_001/config/AMConfig.properties.
6. Create a text file which contains only the password for the keystore in clear text, say /myagent/storepasswd
7. cd to /myagent/bin; do: ./wssagentadmin --encrypt WSSAgent_001 /myagent/storepasswd
8. The above command generates an encrypted password for the keystore. Set it to the file specified by the property
com.sun.identity.saml.xmlsig.storepass in the STAGING configuration file /myagent/WSSAgent_001/config/AMConfig.properties.
For example, the setting in the AMConfig.properties is: com.sun.identity.saml.xmlsig.storepass=/myagent/resources/.storepass,
replace the old encrypted password in the /myagent/resources/.storepass with the newly generated encrypted password.
9. Create a text file which contains only the password for the key in the keystore in clear text, say /myagent/keypasswd
10. cd to /myagent/bin; do: ./wssagentadmin --encrypt WSSAgent_001 /myagent/keypasswd
11. The above command generates an encrypted password for the key in the keystore. Set it to the file specified by
the property com.sun.identity.saml.xmlsig.keypass in the STAGING configuration file
/myagent/WSSAgent_001/config/AMConfig.properties. For example, the setting in the AMConfig.properties is:
com.sun.identity.saml.xmlsig.storepass=/myagent/resources/.keypass
replace the old encrypted password in the /myagent/resources/.keypass with the newly generated encrypted password.
12. Copy the updated STAGING configuration file /myagent/WSSAgent_001/config/AMConfig.properties to the EFFECTIVE
agent configuration file /space/products/glassfishv2/glassfish/addons/opensso/AMConfig.properties
13. Restart the glassfish container.
{noformat}
h2. Display Help Information Using wssagentadmin
{noformat}
1. cd to /myagent/bin
2. Display helps: ./wssagentadmin --help
--install: Installs a new Agent instance. This is the default option.
Usage: wssagentadmin --install [--useResponse | --saveResponse
<fileName>]
The available 'install' options are:
--useResponse: Use this option to install in silent mode by specifying all
the responses in a response specified by <fileName>. When this option is used
the installer will run in non-interactive mode where user interaction would
not be required.
--saveResponse: Use this option to save all the supplied responses to a
response file specified by <fileName>.
--custom-install: Installs a new Agent instance.
Usage: wssagentadmin --custom-install [--useResponse | --saveResponse
<fileName>]
The available 'custom-install' options are:
--useResponse: Use this option to install in silent mode by specifying all
the responses in a response specified by <fileName>. When this option is used
the installer will run in non-interactive mode where user interaction would
not be required.
--saveResponse: Use this option to save all the supplied responses to a
response file specified by <fileName>.
--uninstall: Uninstalls an existing Agent instance.
Usage: wssagentadmin --uninstall [--useResponse | --saveResponse
<fileName>]
The available 'uninstall' options are:
--useResponse: Use this option to install in silent mode by specifying all
the responses in a response specified by <fileName>. When this option is used
the installer will run in non-interactive mode where user interaction would
not be required.
--saveResponse: Use this option to save all the supplied responses to a
response file specified by <fileName>.
--version: Displays the version information.
Usage: wssagentadmin --version
--listAgents: Displays details of all the configured agents.
Usage: wssagentadmin --listAgents
--agentInfo: Displays details of the agent corresponding to the specified
agent ID.
Usage: wssagentadmin --agentInfo <agentID>
--agentInfo: Displays details of the agent corresponding to the specified
<agentID>.
Example: wssagentadmin --agentInfo WSSAgent_001
--encrypt: Encrypts a given string.
Usage: wssagentadmin --encrypt <agentInstance> <passwordFile>
The <agentInstance> specifies the particular Agent instance identifier
name for which the given <passwordFile> will be encrypted. This is necessary
since the encryption functionality requires the use of Agent instance
specific encryption key present in its configuration file.
--getEncryptKey: Generates an Agent Encryption key.
Usage: wssagentadmin --getEncryptKey
{noformat}
Starting from 6/15/2009 OpenSSO nightly build, the OpenSSO Web Services Security Agent 3.0 for Glassfish is bundled with an installer. The installer can be used to install and uninstall the WSS Agent. It also has other functionalities, such as version display, encryption key generation, password encryption, etc.
In the following sections, we will describe the steps on how to use these features.
Assume OpenSSO server has been deployed using the nightly build [OpenSSO nightly build download | https://opensso.dev.java.net/public/use/index.html]
The opensso server url is http://myhost.red.iplanet.com:8080/opensso.
The glassfish is installed at /space/products/glassfishv2/glassfish.
h2. Install OpenSSO Web Services Security Agent 3.0 nightly build for glassfish
{noformat}
1. Stop the agent container.
2. Download openssowssproviders.zip from http://download.java.net/general/opensso/nightly/latest/wssagents/openssowssproviders.zip.
3. Unzip it to an install directory say /myagent.
The installer will ask for the name of the agent profile which is used for authenticating the agent and accessing
the WSC/WSP/STSClient profiles. By default, OpenSSO has an agent profile named "agentAuth". Its password is set to
"changeit". This agent profile has the permission to read the profiles of the default WSC/WSP/STSClient (named as
"wsc", "wsp", "SecurityTokenService" respectively) created out of box. This install process will use "agentAuth"
as the agent profile name.
Create a text file /myagent/passwordfile that contains the agent user password "changeit" (quotes not included) in
clear text.
4. cd to /myagent/bin
5. chmod 755 wssagentadmin
6. Start installation: ./wssagentadmin --install
************************************************************************
Welcome to the OpenSSO WSS Agent 3.0 for Sun Java System Application Server 9.1.
************************************************************************
Enter the complete path to the directory which is used by Application Server
to store its configuration Files. This directory uniquely identifies the
Application Server instance that is secured by this Agent.
[ ? : Help, ! : Exit ]
Enter the Application Server Config Directory Path
[/opt/SUNWappserver/domains/domain1/config]: /space/products/glassfishv2/glassfish/domains/domain1/config
Enter the URL where the OpenSSO server is running. Please include the
deployment URI also as shown below:
(http://opensso.sample.com:58080/opensso)
[ ? : Help, < : Back, ! : Exit ]
OpenSSO server URL: http://myhost.red.iplanet.com:8080/opensso
Enter the Agent profile name
[ ? : Help, < : Back, ! : Exit ]
Enter the Agent Profile name: agentAuth
Enter the path to a file that contains the password to be used for identifying
the Agent.
[ ? : Help, < : Back, ! : Exit ]
Enter the path to the password file: /myagent/passwordfile
-----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
Application Server Config Directory :
/space/products/glassfishv2/glassfish/domains/domain1/config
Application Server Instance name : server
OpenSSO server URL : http://myhost.red.iplanet.com:8080/opensso
Agent Profile name : agentAuth
Agent Profile Password file name : /myagent/passwordfile
Verify your settings above and decide from the choices below.
1. Continue with Installation
2. Back to the last interaction
3. Start Over
4. Exit
Please make your selection [1]:
Creating directory layout and configuring WSSAgent file for WSSAgent_001
instance ...DONE.
Reading data from file /tmp/passwdfile and encrypting it ...DONE.
Creating tag swapped AMConfig.properties file for instance WSSAgent_001
...DONE.
Creating a backup for file
/space/products/glassfishv2/glassfish/domains/domain1/config/domain.xml
...DONE.
Adding Agent parameters to
/space/products/glassfishv2/glassfish/domains/domain1/config/domain.xml
file ...DONE.
Creating a backup for file
/space/products/glassfishv2/glassfish/lib/webservices-rt.jar
...DONE.
Creating a backup for file
/space/products/glassfishv2/glassfish/lib/webservices-tools.jar
...DONE.
Creating a backup for file
/space/products/glassfishv2/glassfish/lib/endorsed/webservices-api.jar
...DONE.
DONE.
SUMMARY OF AGENT INSTALLATION
-----------------------------
Agent instance name: WSSAgent_001
Agent Debug directory location: /myagent/WSSAgent_001/logs/debug
Install log file location:
/myagent/installer-logs/audit/install.log
Thank you for using OpenSSO WSS Agent 3.0.
7. Restart the agent container.
Agent install is completed.
{noformat}
h2. Uninstall OpenSSO Web Services Security Agent 3.0
{noformat}
1. Stop the agent container.
2. cd to /myagent/bin
3. Start uninstall: ./wssagentadmin --uninstall
************************************************************************
Welcome to the OpenSSO WSS Agent 3.0 for Sun Java System Application Server
9.1.
************************************************************************
Enter the complete path to the directory which is used by Application Server
to store its configuration Files. This directory uniquely identifies the
Application Server instance that is secured by this Agent.
[ ? : Help, ! : Exit ]
Enter the Application Server Config Directory Path
[/opt/SUNWappserver/domains/domain1/config]: /space/products/glassfishv2/glassfish/domains/domain1/config
Enter the name of the Application Server instance that is secured by this Agent.[ ? : Help, < : Back, ! : Exit ]
Enter the Application Server Instance name [server]: server
-----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
Application Server Config Directory :
/space/products/glassfishv2/glassfish/domains/wsc/config
Application Server Instance name : server
Verify your settings above and decide from the choices below.
1. Continue with Uninstallation
2. Back to the last interaction
3. Start Over
4. Exit
Please make your selection [1]:
DONE.
Removing Agent parameters from
/space/products/glassfishv2/glassfish/domains/domain1/config/domain.xml
file ...DONE.
Deleting the config directory
/myagent/WSSAgent_001/config ...DONE.
Uninstall log file location:
/myagent/installer-logs/audit/uninstall.log
Thank you for using OpenSSO WSS Agent 3.0.
4. Restart the agent container.
Agent uninstall is completed.
{noformat}
h2. Get Version Information of OpenSSO Web Services Security Agent 3.0
{noformat}
1. cd to /myagent/bin
2. check version: ./wssagentadmin --version
------------------------------------------------------------------------
Sun OpenSSO Web Services Security Agent for:
Sun Java(TM) System Application Server 9.1
------------------------------------------------------------------------
Version: 3.0
Build Date: 20090615
{noformat}
h2. Get a Randomly Generated Encryption Key Using wssagentadmin
{noformat}
1. cd to /myagent/bin
2. Generate encryption key: ./wssagentadmin --getEncryptKey
Agent Encryption Key : U74Cpx6qW/u+ryyhL4f/y6wC0DifhWC7
{noformat}
h2. Encrypt a Password Using wssagentadmin
{noformat}
1. cd to /myagent/bin
2. Create a text file /tmp/passwdfile that contains only the clear text password to be encrypted.
3. Encrypt the password: ./wssagentadmin --encrypt WSSAgent_001 /tmp/passwdfile
The encrypted value is: AQIC5wM2LR4Sfcz6b5obkUIFEt5eZQtbU3Tr
The encryption is based on the encryption key specified by am.encryption.pwd property setting in the
staging configuration file /myagent/WSSAgent_001/config/AMConfig.properties
{noformat}
h2. Change Encryption Key of an Installed WSS Agent
{noformat}
After an WSS Agent is installed onto a Glassfish domain, the agent configuration file AMConfig.properties gets placed
in /space/products/glassfishv2/glassfish/addons/opensso. There is also an AMConfig.properties in
/myagent/WSSAgent_001/config. However the latter is used as a staging file only. The effective agent configuration is
the one in /space/products/glassfishv2/glassfish/addons/opensso. The passwords of agent profile user and key store are
encrypted using the encryption key specified by am.encryption.pwd in the AMConfig.properties. In the case that a user
needs to change the encryption key, the following procedure should be followed:
1. Choose a desired encryption key or use wssagentadmin to generate a random one.
2. Set the property am.encryption.pwd to this encryption key in the STAGING configuration file
/myagent/WSSAgent_001/config/AMConfig.properties.
3. Create a text file which contains only the agent profile user password in clear text, say /myagent/agentpasswd
4. cd to /myagent/bin; do: ./wssagentadmin --encrypt WSSAgent_001 /myagent/agentpasswd
5. The above command generates an encrypted password for the agent profile user. Set it to the property
com.iplanet.am.service.secret in the STAGING configuration file /myagent/WSSAgent_001/config/AMConfig.properties.
6. Create a text file which contains only the password for the keystore in clear text, say /myagent/storepasswd
7. cd to /myagent/bin; do: ./wssagentadmin --encrypt WSSAgent_001 /myagent/storepasswd
8. The above command generates an encrypted password for the keystore. Set it to the file specified by the property
com.sun.identity.saml.xmlsig.storepass in the STAGING configuration file /myagent/WSSAgent_001/config/AMConfig.properties.
For example, the setting in the AMConfig.properties is: com.sun.identity.saml.xmlsig.storepass=/myagent/resources/.storepass,
replace the old encrypted password in the /myagent/resources/.storepass with the newly generated encrypted password.
9. Create a text file which contains only the password for the key in the keystore in clear text, say /myagent/keypasswd
10. cd to /myagent/bin; do: ./wssagentadmin --encrypt WSSAgent_001 /myagent/keypasswd
11. The above command generates an encrypted password for the key in the keystore. Set it to the file specified by
the property com.sun.identity.saml.xmlsig.keypass in the STAGING configuration file
/myagent/WSSAgent_001/config/AMConfig.properties. For example, the setting in the AMConfig.properties is:
com.sun.identity.saml.xmlsig.storepass=/myagent/resources/.keypass
replace the old encrypted password in the /myagent/resources/.keypass with the newly generated encrypted password.
12. Copy the updated STAGING configuration file /myagent/WSSAgent_001/config/AMConfig.properties to the EFFECTIVE
agent configuration file /space/products/glassfishv2/glassfish/addons/opensso/AMConfig.properties
13. Restart the glassfish container.
{noformat}
h2. Display Help Information Using wssagentadmin
{noformat}
1. cd to /myagent/bin
2. Display helps: ./wssagentadmin --help
--install: Installs a new Agent instance. This is the default option.
Usage: wssagentadmin --install [--useResponse | --saveResponse
<fileName>]
The available 'install' options are:
--useResponse: Use this option to install in silent mode by specifying all
the responses in a response specified by <fileName>. When this option is used
the installer will run in non-interactive mode where user interaction would
not be required.
--saveResponse: Use this option to save all the supplied responses to a
response file specified by <fileName>.
--custom-install: Installs a new Agent instance.
Usage: wssagentadmin --custom-install [--useResponse | --saveResponse
<fileName>]
The available 'custom-install' options are:
--useResponse: Use this option to install in silent mode by specifying all
the responses in a response specified by <fileName>. When this option is used
the installer will run in non-interactive mode where user interaction would
not be required.
--saveResponse: Use this option to save all the supplied responses to a
response file specified by <fileName>.
--uninstall: Uninstalls an existing Agent instance.
Usage: wssagentadmin --uninstall [--useResponse | --saveResponse
<fileName>]
The available 'uninstall' options are:
--useResponse: Use this option to install in silent mode by specifying all
the responses in a response specified by <fileName>. When this option is used
the installer will run in non-interactive mode where user interaction would
not be required.
--saveResponse: Use this option to save all the supplied responses to a
response file specified by <fileName>.
--version: Displays the version information.
Usage: wssagentadmin --version
--listAgents: Displays details of all the configured agents.
Usage: wssagentadmin --listAgents
--agentInfo: Displays details of the agent corresponding to the specified
agent ID.
Usage: wssagentadmin --agentInfo <agentID>
--agentInfo: Displays details of the agent corresponding to the specified
<agentID>.
Example: wssagentadmin --agentInfo WSSAgent_001
--encrypt: Encrypts a given string.
Usage: wssagentadmin --encrypt <agentInstance> <passwordFile>
The <agentInstance> specifies the particular Agent instance identifier
name for which the given <passwordFile> will be encrypted. This is necessary
since the encryption functionality requires the use of Agent instance
specific encryption key present in its configuration file.
--getEncryptKey: Generates an Agent Encryption key.
Usage: wssagentadmin --getEncryptKey
{noformat}