Overview:
=========

  The purpose of the opensso quickstart demonstrate integration with
  OpenSSO (Single Sign On)

  There are three services in this quickstart. (In this example, we
  are deploying OpenSSO into a separate Tomcat).

  1. The first one shows how the security properties can be specified
     on the service.

  2. The second service shows that one can specify a custom callback
     handler if this is desired.

  3. The third service will simply invoke a Stateless EJB and
     demonstrates that the user security information is propagated and
     can access the EJB. Note that this will only work if the
     appserver has deployment support for EJBs.

  All of the services print the Subject instance information to show
  the security Principals.
  
Running this quickstart:
========================
  
Please refer to 'ant help-quickstarts' for prerequisites about the
quickstarts and a more detailed descripton of the different ways to
run the quickstarts.

 * Note: You can either deploy the OpenSSO in Tomcat or SOA-P. Don't need to
         deploy them into these two containers at same time. We list them all here just 
         for your reference.

 * Note: We are testing against OpenSSOv1 Build 4.5 (http://download.java.net/general/opensso/stable/openssov1-build4.5/)


Install and configure OpenSSO in Tomcat:
======================================= 

  1. Download the Tomcat version 6 or greater from the apache
     site. For example: 
     http://archive.apache.org/dist/tomcat/tomcat-6/v6.0.14/bin/apache-tomcat-6.0.14.tar.gz

  2. Untar it to a directory for example: /opt/tomcat6.0.14

  3. Open up tomcat /opt/tomcat6.0.14/bin/catalina.sh (catalina.bat
     for windows) Add max size to the JAVA_OPTS.

	   Before Editing:
	      JAVA_OPTS="$JAVA_OPTS "-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager"

	   After Editing:
	      JAVA_OPTS="$JAVA_OPTS "-Xmx1G" "-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager"

  4. Copy the opensso.war to /opt/tomcat6.0.14/webapps/

  5. If you want to deploy the soa-p and tomcat in the same machine,
     for simplicity, you can update tomcat port in
     $tomcat/conf/server.xml as below:

      <Connector port="8090" protocol="HTTP/1.1"....
      <Connector port="8099" protocol="AJP/1.3" redirectPort="8443" />

  6. Start tomcat by running /opt/tomcat6.0.14/bin/startup.sh
     (startup.bat for windows)

  7. Open http://tomcatHost.example.com:8090/opensso in a browser.

  8. Click on "Create Default Configuration". This causes OpenSSO to
     configure itself.

  9. Enter 'adminpass' for the "Default User[amAdmin]" and 'ldappass'
     for "Default Agent [amldapuser]"

 10. Visit http://tomcatHost.example.com:8090/opensso again. Log in
     using the proper credentials. User Name is amAdmin and Password
     is the password you chose to go with amAdmin.
 
  * Note that the default configuration will be written to an
    "/opensso" directory in the home directory of the user account
    used to start tomcat
  
  * For more details, refer to this blog entry:
    http://blogs.sun.com/JohnD/entry/how_to_install_tomcat_6


Install and Configure OpenSSO in SOA-P
=======================================

  1. In the opensso-ear directory, run 'ant'.
  
  2. Copy the opensso-1.0.ear from $opensso-ear/build to $soa-p/jboss-as/server/$config(such as default)/deploy

  3. Start the soa-p from $soa-p/jboss-as/bin/run.sh

  4. Open http://localhost:8080/opensso in a browser.

  5. Click on "Create Default Configuration". This causes OpenSSO to
     configure itself.

  6. Enter 'adminpass' for the "Default User[amAdmin]" and 'ldappass'
     for "Default Agent [amldapuser]"
	 
  7. Visit http://localhost:8080/opensso again. Log in
     using the proper credentials. User Name is amAdmin and Password
     is the password you chose to go with amAdmin.

  * Note: due to an opensso.war deployment issue (https://jira.jboss.org/jira/browse/SOA-731),
          we have provided a workaround to fix it. That is why we deploy the opensso-1.0.ear, instead
          of opensso.war by default.

  * Note: The opensso-1.0.ear is meant for demonstration purposes only, such
          as running this quickstart, but we do not recommend the workaround
		  for production. 

Configure the AMConfig.properties.
=================================

  1. In the quickstart's opensso-sdk, if you are running the
     quickstart on Linux or Unix, execute "chmod a+x scripts/*.sh"

  2. In the quickstart's opensso-sdk, run "scripts/setup.sh", it will
     be like (please provide your own value for these parameters):

  *	Debug directory (make sure this directory exists): /var/local/tmp 
	Password of the server application: opensso1 
	Protocol of the server: http
  *	Host name of the server: putian.nay.redhat.com
  *	Port of the server: 8090
	Server's deployment URI: opensso
	Naming URL (hit enter to accept default value, http://putian.nay.redhat.com:8090/opensso/namingservice)

  3. Copy the 'opensso-sdk/resources/AMConfig.properties' to
     $JBossESB/server/conf/props

  * Note that the items marked with "*" above are specific to your
    server configuration. We are assuming that users are using Tomcat's 8090
	port. If you are deploying opensso.ear in SOA-P, then simply update the 
	Port of the server as: 8080

  * For more details, refer to this blog entry:
    http://jeffyuchang.blogspot.com/2008/07/deploying-opensso-in-jbossas.html

To Run '.esb' archive mode with jbossesb-server:
===========================

  1. Make sure you have installed & started the Tomcat and configured
     the AMConfig.properties as above properly.
  2. Start the server.
  3. Type 'ant deploy'.
  4. Type 'ant deploy-ejb'  (This step requires that the server EJB3 deployment.)
  5. Type 'ant runtest'.

  * Note that When running with jbossesb-server the last action will
    fail as this requires an EJB to be deployed.  Since the
    jbossesb-server does not have ejb-deployer the last message
    printed will be:

	[STDOUT] Could not lookup SimpleSLSB/remote. Please make sure that the target server supports EJBs


Other steps to try with this quickstart
=======================================

  * Changing the opensso username and password:

  * The OpenSSO username and password are specified in build.xml. Try
    changing the username and/or password to see how an unsuccessful
    login attempt is handled.

