Sun Java System Access Manager version 6 2005Q1
Sample
 

Main Page > Liberty Sample Page

Liberty Samples


1. Introduction

This sample includes a Service Provider and an Identity Provider. The Service Provider's resources are deployed on SUN Java System Web Server and protected by a policy web agent. Apart from highlighting the different Liberty protocols such as Account Federation, Single Sign On, Single Logout and Federation Termination, this sample also demonstrates the configuration of different authentication levels for different resources.

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

  1. This sample assumes that
    a. SUN Java System Web Server 6.1 is installed on machine1.
    Sun Java System Access Manager Policy Agent 2.0 protects this server
    SP1 is deployed on this server.
    This installation can be on any of the following Access Manager machines as well, but here it will be assumed on a different machine for better understanding.
    b. Access Manager used by the web agent is installed on machine2.
    c. IDP1 is deployed on an Access Manager installed on machine3.
  2. For Solaris
    <begin_dir> = <INSTALL_DIR>/SUNWam
  3. For Windows2000
    <begin_dir> = <INSTALL_DIR>/SunONEIS
  4. <begin_dir>/samples/liberty/sample2/sp1/ will be referred to as <sp1_sample_dir>.
  5. <begin_dir>/samples/liberty/sample2/idp1/ will be referred to as <idp1_sample_dir>.


2. Instructions

A. 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 setup,
           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. 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.
  4. 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.
           
  5. Change AMAgent.properties file entry com.sun.am.policy.am.library.loginURL to point to login URL of the Access Manager installed on machine2.
    For example:
           com.sun.am.policy.am.library.loginURL=http://www.sp1.com:58080/amserver/UI/Login
  6. Add http://www.agentHost.com:80/sp1/index.html to the com.sun.am.policy.agents.notenforcedList property of AMAgent.properties file. In case there is no such entry in the AMAgent.properties, add the following:
           com.sun.am.policy.agents.notenforcedList=http://www.agentHost.com:80/sp1/index.html
    Assumption: The hostname for the web server protected by the web agent is www.agentHost.com and it is running on port 80.
  7. Restart the Web Server.

B. Upload the policy xml file on machine2:

  1. Update sp1Policy.xml (available in <sp1_sample_dir>) The following assumptions are made in sp1Policy.xml:
    a. SP1 Access Manager's root suffix is "dc=sp1,dc=com"
    (attribute "DN" for element "OrganizationRequests" and attribute "createDN" for element "CreatePolicy") b. Host name for the web server protected by the web agent is www.agentHost.com and it is running on port 80.
    Update above values in sp1Policy.xml as per your deployment.
  2. Load sp1Policy.xml using following command.
    <begin_dir>/bin/amadmin -u amadmin -w password -t SP1 Policy.xml
    Two policies will be created, for all the users belonging to the organization, dc=sp1,dc=com - corresponding to two different authentication levels, by loading this XML.

C. Upload the Metadata on machine2 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
           k. SP1's homepage is http://www.agentHost.com:80/sp1/homepage.jsp
           
    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

D. Upload the Metadata on machine3 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 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. 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 above values in idp1Metadata.xml as per your deployment.
  2. Load idp1Metadata.xml using following command.
    <begin_dir>/bin/amadmin -u amadmin -w password -t idp1Metadata.xml

E. Deploy and Configure IDP1 (on machine3):

  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 setup
           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 <idp1_sample_dir>
           jar -cvf idp1.war
  3. 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.
  4. 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.
           
  5. Restart the web server.

F. 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.html
           For example http://www.agentHost.com:80/sp1/index.html
    Note: Here index.html is not a protected page. Hence it will not prompt for authentication.
    Now, click on the Organization Home Page link in index.html and you will be prompted for authentication.
  2. It will check for the valid user session and if session is invalid it will redirect to the preLogin service running at the Access Manager, used by this agent. preLogin service will redirect to common login page.
  3. Click on "Local Login", it will redirect to SP1's Login page.
  4. After successful authentication at SP1, it will redirect to homepage.jsp. This Organization Home Page (homepage.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.
  5. When you choose federate, you will be taken to Federate page where you can select your preferred Identity Provider to federate with. Select IDP1 as your preferred Identity Provider.
  6. Now you will be taken to IDP1 login page. Provide authentication credentials for your IDP1 account. If the authentication is successful, you will get "Federation Done".
  7. At this point you have succesfully federated your account between SP1 and IDP1.
    Note: When the account is already federated, you will be redirected to IDP Login page first.

G. Single Sign On:

  1. After successful federation start a new browser session and try to access SP1 protected page (homepage.jsp). For this access the following URL in a web browser:
           SERVER_PROTO://SERVER_HOST:SERVER_PORT/sp1/homepage.jsp
           For example
                http://www.agentHost.com:80/sp1/homepage.jsp
  2. Now you will be taken to IDP1 login page. Provide authentication credentials for your IDP1 account. If authentication is successful you will be directly taken to the initially accessed SP1 protected page without being asked for SP1 authentication credentials.

H. Single Logout:

  1. On SP1's protected page (homepage.jsp click on the "Logout" link.
  2. You will be logged out from both SP1 and IDP1 and then shown the "LogoutDone" page.
  3. Alternatively, you can start the logout process from IDP protected page (index.jsp) too accomplishing the same result.

I. Federation Termination:

  1. On SP1 protected page (homepage.jsp click on "Terminate federation" link.
  2. You will be taken to the termination page. Here you can select a provider to defederate with. Select IDP1 for federation termination.
  3. On successful defederation you will be taken to TerminationDone page.
  4. Alternatively, you can initiate federation termination from IDP side too.

J. 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 Manager Administration 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.

K. Demonstrating different authentication levels:

  1. For Unix authentication to be a success, create an Unix account with user id (unixID) and password (abcde12) - on the IDP side.
  2. Assuming that your account on SP - SP1Acct is federated with account idp1Acct on IDP, in the user profile of idp1Acct, add unixID to the user alias list attribute using Access Manager Console
           IdentityManagement -> Users -> idp1Acct -> user alias list
  3. Now access homepage.jsp. You will be prompted for authentication. Given that the account is already federated with idp1Acct, log in with idp1Acct credentials and you will be taken to the homepage.jsp.
  4. Try accessing the Financials Page link in the homepage.jsp. You will be prompted for Unix authentication, which is configured to be a higher level of authentication.
  5. Log in with the Unix user id (unixID) and password (abcde12) and you would be taken to the Financials page.

NOTE:

  1. In case, the Web Server is the same as the one used by Access Manager, deploy SP1 under <begin_dir>/web-apps and include the URI mapping in web-apps.xml (available in <begin_dir>/servers/https-<HOST_NAME>/config/).
  2. In case, the Web server is on the same machine as the Access Manager, then the following should be appended to com.sun.am.policy.agents.notenforcedList property of AMAgent.properties file:
           http://www.sp1.com:58080/amserver/config/federation*
           http://www.sp1.com:58080/amserver/IntersiteTransferService*
           http://www.sp1.com:58080/amserver/AssertionConsumerService*
           http://www.sp1.com:58080/amserver/preLogin*
           http://www.sp1.com:58080/amserver/postLogin*
           http://www.sp1.com:58080/amserver/SOAPReceiver*
           http://www.sp1.com:58080/amserver/ReturnTermination*
           http://www.sp1.com:58080/amserver/ProcessLogout*
           http://www.sp1.com:58080/amserver/ReturnLogout*
           http://www.sp1.com:58080/amserver/liberty-logout*
           http://www.sp1.com:58080/amserver/consentHandler*
           http://www.sp1.com:58080/amserver/SingleSignOnService*
           http://www.sp1.com:58080/amserver/federation-terminate*
           http://www.sp1.com:58080/amserver/ProcessTermination*
  3. In case, SP and IDP are installed in the same domain, then change the cookie name on the IDP side by doing the following:

    Change the com.iplanet.am.cookie.domain entry in /etc/opt/SUNWam/config/AMConfig.properties to anything other than iPlanetDirectoryPro. For example com.iplanet.am.cookie.domain=iPlanetPro


End of Sample