Sun Java System Identity Server 2004Q2
Sample
 

Main Page > Liberty Sample Page

Liberty Samples1 Readme File

Sample1 includes a Service Provider and an Identity Provider. The samples 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.

Note:

  1. This document assumes thatSP1 is deployed on machine1 and IDP1 is deployed on machine2.
  2. For Solaris
    <begin_dir> = <IS_Root>/SUNWam
  3. For Windows2000
    <begin_dir> = <IS_Root>/SunONEIS
  4. <begin_dir>/samples/liberty/sample1/ will be referred to as <sample1_dir>.
  5. <begin_dir>/samples/liberty/sample1/sp1/ will be referred to as <sp1_sample_dir>.
  6. <begin_dir>/samples/liberty/sample1/idp1/ will be referred to as <idp1_sample_dir>.

 

A. Upload the meta data on  machine1 for SP1

  1. Update sp1MetaData.xml (available in <sample1_dir>). The following assumptions are made in sp1MetaData.xml.
    1. Identity Server(IS) is running in HTTP mode.
    2. Hostname for SP1 is www.sp1.com
    3. Hostname for IDP1 is www.idp1.com
    4. IS is running on port SERVER_PORT
    5. IS services are deployed under URI - amserver
    6. SP1 Identity Server's root suffix is "dc=sp1,dc=com" (attribute "DN" for element "OrganizationRequests")
    7. SP1 Certificate Alias is SP1_SECURITY_KEY
    8. IDP1 Certificate Alias is IDP1_SECURITY_KEY
    9. SP1 metaAlias is www.sp1.com
    10. IDP1 metaAlias is www.idp1.com
    Update above values in sp1MetaData.xml as per your deployment.
  2. Load sp1MetaData.xml using following command.
    <begin_dir>/bin/amadmin -u amadmin -w password -t sp1MetaData.xml

 

B. Deploy and ConfigureSP1 (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 IS setup, eg: www.sp1.com
    • SERVER_PORT - port number where IS is running
    • SERVICE_DEPLOY_URI : IS services' deployment URI (By Default amserver)
    • META_ALIAS - metaAlias forSP1 (In given sp1MetaData.xml it is entered as www.sp1.com)
  2. Create war file forSP1
    cd <sp1_sample_dir>
    jar -cvf sp1.war .
  3. Deploy the sp1.war
    • Case 1. IS is installed on Sun Java System Web Server:
      1. 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.
      2. 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
      3. Restart web server.
    • Case 2. IS is installed on Sun Java System Application Server:
      1. 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
      2. Restart Application Server
    • Case 3. IS is installed on BEA Web logic:
      1. 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.
      2. 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
      3. Restart WebLogic Server.
    • Case 4. IS is installed on IBM Web Sphere:
      1. Open admin client
        <install-dir>/WebSphere/AppServer/bin/adminclient.sh
      2. Right click on "Enterprise Applications" and select "install Enterprise Application"
      3. Select install stand-alone module
      4. Specify path for sp1.war
      5. Specify SP1 as Application Name
      6. Specify /sp1 as Context root for web module
      7. Keep selecting Next until you get Finish and then select Finish
      8. Right click on your node name and select "Regen Webserver Plugin"
      9. Restart web server
        /opt/IBMHTTPD/bin/apachectl start
      10. Restart application server
        <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 <sample1_dir>)

    The following assumptions are made in idp1MetaData.xml.

    1. Identity Server (IS) is running in HTTP mode.
    2. Hostname for SP1 is www.sp1.com
    3. Hostname for IDP1 is www.idp1.com
    4. IS is running on port SERVER_PORT
    5. IS services are deployed under URI: amserver
    6. IDP1 Identity Server's root suffix is "dc=idp1,dc=com" (attribute "DN" for element "OrganizationRequests")
    7. SP1 Certificate Alias is SP1_SECURITY_KEY
    8. IDP1 Certificate Alias is IDP1_SECURITY_KEY
    9. SP1 metaAlias is www.sp1.com
    10. 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 IS setup, e.g. www.idp1.com
    • SERVER_PORT - port number where IS is running
    • SERVICE_DEPLOY_URI - IS 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. IS is installed on Sun Java System Web Server:
      1. Before you can deploy a web application manually, you must make sure that the server_root/bin/HTTPS/HTTPsadmin/bin directory is in your path and that the IWS_SERVER_HOME environment variable is set to your server_root directory.
      2. 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
      3. Restart Webserver.
    • Case 2. IS is installed on Sun Java System Application Server:
      1. 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 idp1 --instance server1 idp1.war
      2. Restart Application Server.
    • Case 3. IS is installed on BEA Web logic:
      1. 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.
      2. 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
      3. Restart WebLogic Server.
    • Case 4. IS is installed on IBM Web Sphere:
      1. Open admin client
        <install-dir>/WebSphere/AppServer/bin/adminclient.sh
      2. Right click on "Enterprise Applications" and select "install Enterprise Application"
      3. Select install stand-alone module
      4. Specify path for idp1.war
      5. Specify idp1 as Application Name
      6. Specify /idp1 as Context root for web module
      7. Keep selecting Next until you get Finish and then select Finish
      8. Right click on your node name and select "Regen Webserver Plugin"
      9. Restart web server
        /opt/IBMHTTPD/bin/apachectl start
      10. Restart application server
        <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 atSP1 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:
    1. Federate : will initiate the federation process.
    2. Logout : will initiate the single logout process.
    3. 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 Singn 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 can choose Federate/Logout/Terminate Federation.
  4. When you choose Federate, you will be taken to te Federate page where you can 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 FederationDone page.
  6. At this point you have successfully federated your account between SP1 and IDP1.

Note: If the account is already federated, you will be redirected directly 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 taken directly to the initially accessedSP1 protected page without being asked forSP1 authentication credentials.

 

G. Single Logout:

  1. On SP1's protected page (index.jsp) click on the "Logout" link.
  2. You will logged out fromSP1 and IDP1 both and will be shown a LogoutDone 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 TerminationDone page.
  4. Alternatively, you can initiate federation termination from IDP side as well and accomplish the same result.

 

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 Identity Server admin console.
  2. Click on Federation tab.
  3. Then select Authentication Domain in the drop down menu and click on SHOW button.

  4. Select sample1Alliance in the left panel.

  5. In the right panel enter the Reader Service URL and Writer Service URL as per your common domain services installation.

    For example if common doamin 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
  6. This completes third level domain setup.