Sun Java System Access Manager version 7 2005Q4
Sample
 

Main Page > Liberty Sample Page

Liberty Samples


1. Introduction

This sample includes a Service Provider and a Identity Provider. The sample highlights different Liberty protocols such as Account Federation, Single Sign On, Single Logout and Federation Termination.

SP1 is the Service Provider and IDP1 is the Identity Provider.

  1. This document assumes that SP1 is deployed on machine1 and IDP1 is deployed on machine2
  2. For Solaris Sparc/x86 : <BEGIN_DIR> = <INSTALL_DIR>/SUNWam
  3. For Linux : <BEGIN_DIR> = <INSTALL_DIR>/identity
  4. <BEGIN_DIR>/samples/liberty/sample1/sp1/ will be referred to as <sp1_sample_dir>.
  5. <BEGIN_DIR>/samples/liberty/sample1/idp1/ is referred to as <idp1_sample_dir>


2. Instructions

A. Upload the meta data on machine1 for SP1

  1. Update sp1Metadata.xml (available in <sp1_sample_dir>)
    The following assumptions are made in sp1Metadata.xml.
           a. Access Manager is running in HTTP mode.
           b. Hostname for SP1 is www.sp1.com
           c. Hostname for IDP1 is www.idp1.com
           d. Access Manager is running on port 58080
           e. Access Manager services are deployed under URI, amserver
           f. SP1 Access Manager's root suffix is "dc=sp1,dc=com"
              (attribute "DN" for element "OrganizationRequests")
           g. SP1 Certificate Alias is SP1_SECURITY_KEY
           h. IDP1 Certificate Alias is IDP1_SECURITY_KEY
           i. SP1 metaAlias is www.sp1.com
           j. IDP1 metaAlias is www.idp1.com
           
    Update above values in sp1Metadata.xml as per your deployment.
  2. Load sp1Metadata.xmlusing following command.
           <BEGIN_DIR>/bin/amadmin -u amadmin -w password -t sp1Metadata.xml
           

B. Deploy and Configure SP1 (on machine1)

  1. Replace the following tags in AMClient.properties (available in <sp1_sample_dir>/WEB-INF/classes)
           SERVER_PROTO       : protocol (https/http) 
           SERVER_HOST        : fully qualified hostname for your Access Manager
    			   eg: www.sp1.com
           SERVER_PORT        : port number where Access Manager is running
           SERVICE_DEPLOY_URI : Access Manager services' deployment URI
    			   (By Default amserver)
           META_ALIAS         : metaAlias for SP1 (In given sp1Metadata.xml it is
    			   entered as www.sp1.com)
           
  2. Create war file for SP1.
           cd <sp1_sample_dir>
           jar -cvf sp1.war
  3. Deploy the sp1.war

    Case 1: Access Manager is installed on Sun Java System Web Server
    a. Before you can deploy a web application manually, you must make sure that the server_root/bin/https/httpadmin/bin directory is in your path and that the IWS_SERVER_HOME environment variable is set to your server_root directory.
    b. Enter the following command

    	  wdeploy deploy -u uri_path -i instance -v vs_id [-d directory] war_file
    	  where
    	  * uri_path is the URI prefix for the web application.
    	  * instance is the server instance name.
    	  * vs_id is the virtual server ID.
    	  * directory is the directory to which the application is deployed,
    	    or from which the application is deleted. If not specified for
    	    deployment, the application is deployed to the document root
    	    directory.
    	  * war_file is the WAR file name.
              
    For example:
    	  wdeploy deploy -u /sp1 -i www.sp1.com -v https-www.sp1.com
    	     -d <BEGIN_DIR>/web-apps/sp1 sp1.war
    c. Restart web server.

    Case 2: Access Manager is installed on Sun Java System Application Server
    a. Use the asadmin deploy command to deploy the WAR module. The syntax is as follows:

              asadmin deploy --user admin_user [--password admin_password]
              [--passwordfile password_file] --host hostname
              --port adminport [--secure | -s] [--virtualservers virtual_servers]
              [--type aplication|ejb|web|connector] [--contextroot contextroot]
              [--force=true] [--precompilejsp=false] [--verify=false]
              [--name component_name] [--upload=true] [--retrieve local_dirpath]
              [--instance instance_name] filepath
    For example, the following command deploys a web application as an individual module:
              asadmin deploy --user admin --password pswd1234
              --host www.sp1.com --port 4848 --type web --contextroot sp1
              --instance server1 sp1.war
    b. Restart Application Server

    Case 3: Access Manager is installed on BEA Web logic
    a. Set up your development environment so that WebLogic Server classes are in your system CLASSPATH and the JDK is available. You can use the setEnv script located in the config/mydomain directory to set your environment.
    b. Enter the following command:

    	  java weblogic.deploy -port port_number -host host_name 
                 -component application:target deploy password application source
    	  where:
              host_name is the name of the machine hosting WebLogic Server
    	  port_number is the port number where WebLogic Server is listening
    	  for requests
    	  application is the name you want to assign to this Web Application.
    	  target is the name of a server, cluster or virtual host to be
    	  targeted by this Web Application. You can enter multiple targets,
    	  separated by a comma.
    	  password is your system administration password
    	  source is the full pathname of the WAR file you want to deploy, or
    	  the full pathname of a directory containing a Web Application in
    	  exploded directory format.
    For example:
    	  java weblogic.deploy -port 7001 -host www.sp1.com
    	     -component sp1:myserver deploy pswd1234 sp1 sp1.war
    c. Restart WebLogic Server.

    Case 4: Access Manager is installed on IBM Web Sphere
    a. Open admin client

    	  <WEBSPHERE_INSTALL_DIR>/WebSphere/AppServer/bin/adminclient.sh
    b. Right click on "Enterprise Applications" and select "install Enterprise Application"
    c. Select install stand-alone module
    d. Specify path for sp1.war
    e. Specify SP1 as Application Name
    f. Specify /sp1 as Context root for web module
    g. Keep selecting Next until you get Finish and then select Finish
    h. Right click on your node name and select "Regen Webserver Plugin"
    i. Restart web server
    	  /opt/IBMHTTPD/bin/apachectl start
    j. Restart application server
    	  <WEBSPHERE_INSTALL_DIR>/WebSphere/AppServer/bin/startupServer.sh

    Note:
    If you want to have customized version of all the JSPs available in <BEGIN_DIR>/web-apps/services/config/federation/default/, you can create a sub folder under <BEGIN_DIR>/web-apps/services/config/federation/ with the SP1's meta alias name (In given sp1MetaData.xml it is entered as www.sp1.com). Then copy all these JSPs in this newly created sub folder and modify them for the desired look and feel.

C. Upload the meta data on machine2 for IDP1

  1. Update idp1Metadata.xml (available in <idp1_sample_dir>)
    The following assumptions are made in idp1Metadata.xml.
           a. Access Manager is running in http mode.
           b. Hostname for SP1is www.sp1.com
           c. Hostname for IDP1 is www.idp1.com
           d. Access Manager is running on port 58080
           e. Access Manager services are deployed under URI : amserver
           f. IDP1 Access Manager's root suffix is "dc=idp1,dc=com"
              (attribute "DN" for element "OrganizationRequests")
           g. SP1 Certificate Alias is SP1_SECURITY_KEY
           h. IDP1 Certificate Alias is IDP1_SECURITY_KEY
           i. SP1 metaAlias is www.sp1.com
           j. IDP1 metaAlias is www.idp1.com
           
    Update the above values in idp1Metadata.xml per your deployment.
  2. Load idp1Metadata.xml using following command.
           <BEGIN_DIR>/bin/amadmin -u amadmin -w password -t idp1Metadata.xml
           

D. Deploy and Configure IDP1 (on machine2)

  1. Replace the following tags in AMClient.properties (available in <idp1_sample_dir>/WEB-INF/classes)
           SERVER_PROTO       : protocol (https/http) 
           SERVER_HOST        : fully qualified hostname for your Access Manager
    			   eg: www.idp1.com
           SERVER_PORT        : port number where Access Manager is running
           SERVICE_DEPLOY_URI : Access Manager services' deployment URI
    			   (By Default amserver)
           META_ALIAS         : metaAlias for IDP1 (In given idp1Metadata.xml it is
    			   entered as www.idp1.com)
           
  2. Create war file for IDP1.
           cd <idp1_sample_dir>
           jar -cvf idp1.war
  3. Deploy the idp1.war

    Case 1: Access Manager is installed on Sun Java System Web Server
    a. Before you can deploy a web application manually, you must make sure that the server_root/bin/https/httpadmin/bin directory is in your path and that the IWS_SERVER_HOME environment variable is set to your server_root directory.
    b. Enter the following command

    	  wdeploy deploy -u uri_path -i instance -v vs_id [-d directory]
    	  war_file
    	  where
    	  * uri_path is the URI prefix for the web application.
    	  * instance is the server instance name.
    	  * vs_id is the virtual server ID.
    	  * directory is the directory to which the application is deployed,
    	    or from which the application is deleted. If not specified for
    	    deployment, the application is deployed to the document root
    	    directory.
    	  * war_file is the WAR file name.
              
    For example:
    	  wdeploy deploy -u /idp1 -i www.idp1.com -v https-www.idp1.com
    	     -d <BEGIN_DIR>/web-apps/idp1 idp1.war
    c. Restart web server.

    Case 2: Access Manager is installed on Sun Java System Application Server
    a. Use the asadmin deploy command to deploy the WAR module. The syntax is as follows:

              asadmin deploy --user admin_user [--password admin_password]
              [--passwordfile password_file] --host hostname
              --port adminport [--secure | -s] [--virtualservers virtual_servers]
              [--type aplication|ejb|web|connector] [--contextroot contextroot]
              [--force=true] [--precompilejsp=false] [--verify=false]
              [--name component_name] [--upload=true] [--retrieve local_dirpath]
              [--instance instance_name] filepath
    For example, the following command deploys a web application as an individual module:
              asadmin deploy --user admin --password pswd1234
              --host www.idp1.com --port 4848 --type web --contextroot idp1
              --instance server1 idp1.war
    b. Restart Application Server

    Case 3: Access Manager is installed on BEA Web logic
    a. Set up your development environment so that WebLogic Server classes are in your system CLASSPATH and the JDK is available. You can use the setEnv script located in the config/mydomain directory to set your environment.
    b. Enter the following command:

    	  java weblogic.deploy -port port_number -host host_name 
                 -component application:target deploy password application source
    	  where:
              host_name is the name of the machine hosting WebLogic Server
    	  port_number is the port number where WebLogic Server is listening
    	  for requests
    	  application is the name you want to assign to this Web Application.
    	  target is the name of a server, cluster or virtual host to be
    	  targeted by this Web Application. You can enter multiple targets,
    	  separated by a comma.
    	  password is your system administration password
    	  source is the full pathname of the WAR file you want to deploy, or
    	  the full pathname of a directory containing a Web Application in
    	  exploded directory format.
    For example:
    	  java weblogic.deploy -port 7001 -host www.idp1.com
    	     -component idp1:myserver deploy pswd1234 idp1 idp1.war
    c. Restart WebLogic Server.

    Case 4: Access Manager is installed on IBM Web Sphere
    a. Open admin client

    	  <WEBSPHERE_INSTALL_DIR>/WebSphere/AppServer/bin/adminclient.sh
    b. Right click on "Enterprise Applications" and select "install Enterprise Application"
    c. Select install stand-alone module
    d. Specify path for idp1.war
    e. Specify IDP1 as Application Name
    f. Specify /idp1 as Context root for web module
    g. Keep selecting Next until you get Finish and then select Finish
    h. Right click on your node name and select "Regen Webserver Plugin"
    i. Restart web server
    	  /opt/IBMHTTPD/bin/apachectl start
    j. Restart application server
    	  <WEBSPHERE_INSTALL_DIR>/WebSphere/AppServer/bin/startupServer.sh

    Note:
    If you want to have customized version of all the JSPs available in <BEGIN_DIR>/web-apps/services/config/federation/default/, you can create a sub folder under <BEGIN_DIR>/web-apps/services/config/federation/ with the IDP1's meta alias name (In given idp1MetaData.xml it is entered as www.idp1.com). Then copy all these JSPs in this newly created sub folder and modify them for the desired look and feel.

E. Federate user account at SP1 with an account at IDP1

  1. Access the following URL in a web browser
           SERVER_PROTO://SERVER_HOST:SERVER_PORT/sp1/index.jsp
           For example "http://www.sp1.com:58080/sp1/index.jsp".
           
    This index.jsp has following three links:

    a. Federate : will initiate the federation process.
    b. Logout : will initiate the single logout process.
    c. Terminate Federation : will initiate the federation termination process.

    Here index.jsp is a protected page which includes _head.jsp. The _head.jsp will check for valid user session and if session is invalid it will redirect to preLogin service. The preLogin service will try to do Single Sign On, since it is a first time access, Single Sign On will fail and the preLogin service will redirect to the common login page.
  2. On the common login page click on "Local Login" link, you will be redirected to the SP1's login page.
  3. After successful authentication at SP1, you will be redirected to the index.jsp where you choose Federate/Logout/Terminate Federation.
  4. When you choose Federate, you will be taken to te Federate page where you select your preferred Identity Provider to federate with. Select IDP1 as your preferred Identity Provider.
  5. Now you will be redirected to IDP1's login page. Provide authentication credentials for your IDP1 account. If the authentication is successful, you will see Federation Done page.
  6. At this point you have successfully federated your account between SP1 and IDP1.
    Note: If the account is already federated, you are immediately redirected to the IDP1's login page.

F. Single Sign On

  1. After successful federation start a new browser session and try to access SP1 protected page (index.jsp):
           SERVER_PROTO://SERVER_HOST:SERVER_PORT/sp1/index.jsp
           For example "http://www.sp1.com:58080/sp1/index.jsp".
           
  2. Now you will be taken to the IDP1's login page. Provide authentication credentials for your IDP1 account. If authentication is successful you will be redirected to the initially accessed SP1 protected page without being asked for SP1 authentication credentials.

G. Single Logout

  1. On SP1's protected page (index.jsp) click on the "Logout" link.
  2. You will logged out from SP1and IDP1 both and will be shown a Logout Done page.
  3. Alternatively, you can start the logout process from IDP protected page(index.jsp) as well and accomplish the same result.

H. Federation Termination

  1. On SP1's protected page (index.jsp) click on the "Terminate Federation" link.
  2. You will be taken to a federation termination page where you can select a provider to terminate your account federation. Select IDP1.
  3. On successful federation termination you will be taken to Termination Done page.
  4. Alternatively, you can initiate federation termination from IDP side as well and accomplish the same result.

I. Configuring Third Level Domain

This sample application does not require the use of a third level domain. If you want to configure third level domain:

  1. Access Access Manager administration console.
  2. Select Federation tab.
  3. Under Authentication Domain Tab click on sample1Alliance link.
  4. Enter the Reader Service URL and Writer Service URL as per your common domain services installation.
    For example if common domain services are installed on machine3 with hostname is www.machine3.com for default installation:
           Writer Service URL : http://www.machine3.com:80/amcommon/writer
           Reader Service URL : http://www.machine3.com:80/amcommon/transfer
           
  5. This completes third level domain setup.


End of Sample