| Main Page >
    Liberty Sample Page
 Liberty Samples
 
 1. Introduction
    This sample includes two Service Providers and two Identity Providers.
    This sample demonstrates the different Liberty protocols such as Account
    Federation, Single Sign On, Single Logout and Federation Termination.
     
    This sample scenario requires only one Access Manager installation.
    Four hosted providers (two Service Providers and two Identity Providers)
    are created on the same Access Manager Installation. Each hosted provider
    requires a virtual server instance. You need to host the same IP address
    (on which the Access Manager is installed) in four different DNS domains.
    This can be simulated by adding entries in the /etc/hostsfile for the
    fully qualified host names of the virtual servers. 
    Since there are multiple Identity Providers, you also need to install a
    common domain service. This service will be installed with the Access
    Manager default installation. You may choose to install it separately on
    a different machine. This sample assumes on the same machine.
     
    
SP1andSP2are two Service Providers.IDP1andIDP2are two Identity Providers. 
We assume
       
       <begin_dir> = <IS_Root>/SUNWam
<begin_dir>/samples/liberty/sample3/will be referred to
       as<sample3_dir>.The instruction is based on Sun Jave System Web Server 6.1sp4, for
       other container like Sun Java System Application Server, WebLogics and
       Websphere, equivalent steps need to be performed accordingly.
     
 
 2. Instructions
    
 A. Create and configure sub realmsFor this sample you will need to create four sub realms under
    the root realm. Each hosted provider will be associated with one
    of these sub realm. ThesubOrgRequests.xmlavailable
    under<sample3_dir>will do it automatically.
    ThesubOrgRequests.xmlcould be loaded in realm mode only. 
    If you are running in legacy mode, you need to login to console and perform 
    following steps manually:
    a. Create four sub organizations namely sp1,sp2,idp1andidp2.
    b. Register Core service and LDAP service for each of these sub organization.
    c. Create service template for the registered services.
    d. Create a sample user for each of these sub organizations. These sample
       users will be created with user id assp1User,sp2User,idp1Userandidp2Userfor the sub organizationssp1,sp2,idp1andidp2respectively. All the passwords are the same as the user id (i.e.sp1User's password issp1User).
 
Update the subOrgRequests.xml(available in<sample3_dir>).
       The following assumptions are made in this XML file.
       a. Access Manager's root suffix is "dc=example,dc=com" (attribute "DN"
          for elements "OrganizationRequests" and "PeopleContainerRequests")
       b. Access Manager (AM) is running in HTTP mode.
       c. AM services are deployed under the URI: amserver
       d. The four virtual servers fully qualified host names are www.sp1.com,
          www.sp2.com, www.idp1.com and www.idp2.com.
       Update the above values insubOrgRequests.xmlas your
       deployment requirement.Load subOrgRequests.xmlusing the following command.
       <begin_dir>/bin/amadmin -u amadmin -w <amadmin's password>
          -t <path>/subOrgRequests.xml 
    
 B. Upload the meta data:
    This sample scenario requires four hosted providers. The metaData.xmlavailable under<sample3_dir>creates these hosted providers and configures
    the meta data for all the providers. 
 
Update the metaData.xml(available in<sample3_dir>).
       The following assumptions are made in this xml file.
       a. Access Manager's root suffix is "dc=example,dc=com" (attribute "DN"
          for elements "OrganizationRequests")
       b. Access Manager(AM) is running in HTTP mode.
       c. AM is running on port 58080
       d. AM services are deployed under URI : amserver
       e. Four virtual servers fully qualified host names are www.sp1.com,
          www.sp2.com, www.idp1.com and www.idp2.com.
       f. SP1 Certificate Alias is SP1_SECURITY_KEY
       g. Update the above values in theSP2Certificate Alias is SP2_SECURITY_KEY
       h.IDP1Certificate Alias is IDP1_SECURITY_KEY
       i. IDP2 Certificate Alias is IDP2_SECURITY_KEY
       j. SP1 metaAlias is www.sp1.com
       k.SP2metaAlias is www.sp2.com
       l.IDP1metaAlias is www.idp1.com
       m. IDP2 metaAlias is www.idp2.com
       n. SP1's associated realm is sp1, associated organization is 
          "o=sp1org,dc=example,dc=com".
       o. SP2's associated realm is sp2, associated organization is 
          "o=sp2org,dc=example,dc=coma".
       p. IDP1's associated realm is idp1, associated organization is 
          "o=idp1org,dc=example,dc=com".
       q. IDP2's associated realm is idp2, associated organization is 
          "o=idp2org,dc=example,dc=com".
       r. Common domain service is installed on
          "http://www.sp1.com:58080/amcommon/" (If it is installed on a
          different machine, default port number will be 80)metaData.xmlas your
       deployment scenario.
 Note: In the given
 metaData.xmlcommon domain URL's host name is entered
       as virtual host name (www.sp1.com), in this case editFSIntroConfig.properties(located inside the
       common domain WAR/WEB-INF/classesdirectory. 
       For SJS web server 6.1, by default it could be found at<ws6_install_dir>/SUNWwbsvr/https-<host_name>/is-web-apps/common/WEB-INF/classesdirectory) 
       to change the cookie domain value to".sp1.com".For example set is as following :
 
       com.sun.identity.federation.services.introduction.cookiedomain=.sp1.com
       Alternatively use the original host name in the common domain URLs so
       that you need not change the cookie domain value (it will be set for
       the original host)Load the metaData.xmlusing following command.
       <begin_dir>/bin/amadmin -u amadmin -w <amadmin's password>
          -t <path>/metaData.xml
       Login to console as admin.click "sp1" under Realms.click "Data Stores" tab.click "amSDK1" link.set o=sp1org,<root_suffix> in the "Access Manager Organization"
          field, and click "Save" button.repeat 3-7 for "sp2", "idp1" and "idp2", use "o=sp2org", "o=idp1org"
          and "o=idp2org" for corresponding "Access Manager Organization" field.
     
    
 C. Create This sample scenario requires four virtual servers.SP1virtual server and Deploy SP1Urlhostsfor these
    virtual servers will be assumed aswww.sp1.com,www.sp2.com,www.idp1.comandwww.idp2.com.
 
Update SP1Config.properties(available in<sp3_sample_dir>/sp1/WEB-INF/classes/)The following assumptions are made in this xml file.
 
       a. Fully qualified host name for the SP1 virtual server is www.sp1.com
       b. Access Manager (AM) is running in HTTP mode.
       c. AM is running on port 58080
       d. AM services are deployed under URI - amserver
       e. SP1 metaAlias is www.sp1.com
       Update the above values in theSP1Config.propertiesas per your
       deployment scenario.Repate 1 for SP2,IDP1andIDP2.Login to web server as administrator.
    Click <Manage>button to Manage server (In this case, it is
       https-<fullhostname>).Click on Virtual Server Class.
    Click on Manage for the "vsclass1"Click Add Virtual Server
    Name the "Name" to sp1VSSelect connections(In this case it is the default one)
    Add urlhosts entry to the domain for which the virtual server runs
       on. For sp1VSusewww.sp1.comClick OK
    Repeat 6-11 for SP2,IDP1andIDP2, create Virtual Serversp2VS,idp1VSandidp2VSforwww.sp2.com,www.idp1.comandwww.idp2.comrespectively.Click Apply and Click Apply Changes. The server will be restarted.
    Click Virtual Server Class "vsclass1" and Click "sp1VS" under Tree View of
         the Server. 
    Click Web Applications
    On Server machine, create war file for SP1
       cd <sp1_sample_dir/sp1>
       jar -cvf sp1.warWar File On - Choose Server Machine and click Go
    War File Path - Enter the full patch that the war file we just
       created.
    Application URI - /sp1Installation Directory - accept default, modify if needed. 
    Click OK. Virtual server created.
    Repeat 14-21, select sp2VS,idp1VSandidp2VSvirtual server, deploy URI/sp2,/idp1and/idp2forSP2,IDP1andIDP2respectivelyClick Apply and Click Apply Changes. The server will be restarted.
    Edit server.xml (located at <ws6_install_dir>/SUNWwbsvr/https-<host_name>/configdirectory for SJS web server), 
      copy service, console(legacy mode only), password and common domain web 
      application from default virtual server (https-<host_name>) tosp1VSvirtual server. For example, for SJS web server 6.1,sp1VSwill looks like this:
    <VS id="sp1VS" state="on" connections="ls1" urlhosts="www.sp1.com" mime="mime1" aclids="acl1">
      <USERDB id="default" database="default"/>
      <WEBAPP uri="/amserver" path="/opt/SUNWwbsvr/https-host.sun.com/is-web-apps/services" enabled="true"/>
      <WEBAPP uri="/ampassword" path="/opt/SUNWwbsvr/https-host.sun.com/is-web-apps/password" enabled="true"/>
      <WEBAPP uri="/amcommon" path="/opt/SUNWwbsvr/https-host.sun.com/is-web-apps/common" enabled="true"/>
      <WEBAPP uri="/sp1" path="/opt/SUNWwbsvr/https-host.sun.com/webapps/sp1VS/sp1" enabled="true"/>
    </VS>
    Repeat step 24 for sp2VS,idp1VSandidp2VSRetsart Web Server.
     
    
 D. Configure Access Manager for SP1virtual server:
 
Login to the Access Manager as amadmin and go to the Configuration tab.
    Click on Platform service under System Properties section.
    Click "New" under "Instance Name". Enter "<protocol>://www.sp1.com:<port>" in Server field, 
          enter "02" in Instance Name.
    Click OKRepeat step 3-5 for <protocol>://www.sp2.com:<port> with 
          03, <protocol>://www.idp1.com:<port> with 04, 
          <protocol>://www.idp2.com:<port> with 05.
    In Cookie Domains field, add ".sp1.com", ".sp2.com", ".idp1.com"
          and ".idp2.com"
    Click Save.  Add fqdnMapentry forSP1virtual server in/etc/opt/SUNWam/config/AMConfig.properties:
       com.sun.identity.server.fqdnMap[www.sp1.com]=www.sp1.com
       TheFQDNMap is a simple map that enables Access Manager Authentication
       service to take corrective action in the case where the users may have
       typed in an incorrect URL such as by specifying partial hostname or
       using an IP address to access protected resources. This property can be
       used for creating a mapping for more than one hostnames. This may be the
       case when the applications hosted on this server are accessible by more
       than one hostnames.Repeat step 9 for  SP2,IDP1andIDP2, usewww.sp2.com,www.idp1.comandwww.idp2.comrespectively.Restart the web server and the Access Manager.
     
    
 E. Federate user account at SP1with an account atIDP1:
 
Access the following url in a web browser
       
       SERVER_PROTO://SERVER_HOST:SERVER_PORT/sp1/index.jsp
       Thisindex.jsphas 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.jspis a protected page which includes_head.jsp.  The_head.jspwill check for valid user session and if session is invalid
       it will redirect topreLoginservice. ThepreLoginservice will try to
       do Single Sign On, since it is a first time access, Single Sign On will
       fail and thepreLoginservice will redirect to the common login page.On the common login page click on "Local Login" link, you will be
       redirected to the SP1's login page.After successful authentication at SP1, you will be redirected to
       theindex.jspwhere you can choose Federate/Logout/Terminate Federation.If you choose to federate, you will be taken to the Federate page
       where you can select your preferred Identity Provider to federate with.
       Select IDP1as the preferred Identity Provider.Now you will be taken to IDP1's login page where you need to
       provide authentication credentials (user-id/password) for theIDP1account (in this caseidp1User/idp1User). If the authentication is
       successful, you will be shown theFederationDonepage.At this point you have successfully federated your account between
       SP1andIDP1.
 Note: When an account is already federated, the you will be redirected
       to the
 IDP1Login page first, assuming the common domain service is
       properly configured. If the common domain service is not configured
       properly then you will see thecommonLoginpage where you can click on
       theIDP1's link with which you have federated yourSP1account.Repeat step 1-6 to federate your SP2account (sp2User) with theIDP1account (idp1User). 
    
 F. Single Sign On:
 
After successful federation start a new browser session and try to
       access SP1protected page (index.jsp):
       SERVER_PROTO://SERVER_HOST:SERVER_PORT/sp1/index.jsp
       For example
	   http://Note: If the earlier session is still valid in the new browser, then
       single logout should be done first. See section H for this.www.sp1.com:58080/sp1/index.jspNow you will be taken to IDP1's login page (Again assuming that
       the common domain is configured properly). You need to provide
       authentication credentials for the user account atIDP1. If
       authentication is successful you will be directly taken to the initially
       accessedSP1protected page without being asked forSP1authentication
       credentials.Now in the same browser try to access SP2's protected page
       (http://www.sp2.com:58080/sp2/index.jsp), you will be allowed to access
       this protected page without being asked for authentication atSP2(Assuming that you have federated yourSP2account with the account atIDP1). Again, if common domain is not configured you will seecommonLoginpage where you can select a preferredIDP, with which you
       federated your account. After clicking on theIDP's link you will be
       able to see theSP2's initially accessed protected page.Similarly you can demonstrate federation and single sign on with an
       account at IDP2by repeating all the steps in section F and section
       G by selectingIDP2as the preferredIDP. 
    
 G. Single Logout:
 
On SP1's protected page (index.jsp) click on "Logout" link.You will be logged out from all the valid sessions (in this case SP1,SP2andIDP1)s and will be shown aLogoutDonepage.Alternatively, you can start the logout process from the IDPprotected
       page (index.jsp) as well and accomplish the same. 
    
 H. Federation Termination:
 
On the SP1's protected page (index.jsp) click on
       "Terminate Federation" link.You will be taken to a page where you can select a provider to
       terminate the federation. For example select IDP1for federation
       termination.On successful federation termination you will be taken to
       TerminationDonepage.Alternatively, you can initiate federation termination from the IDPside also and get the same result. 
    
 I. Name ID Mapping:
 
 For the encryption to work, you need to download JCE 
           provider and set it up in your JDK and web container, if these 
           were not previously done yet:
    
a. Download, for example, bouncy castle JCE provider from 
   "ftp://ftp.bouncycastle.org/pub/release1.28". For JDK 1.5, select 
   bcprov-jdk15-128.jar; for JDK 1.4, select bcprov-jdk14-128.jar.
b. Copy the above jar file to <jdk_root>/jre/lib/ext directory
c. For domestic version of JDK, download JCE Unlimited Strength Jurisdiction 
   Policy Files from Sun site (http://java.sun.com) for your version of JDK. 
   For WebSphere, please go to corresponding IBM site to download.
d. Copy downloaded US_export_policy.jar and local_policy.jar to
   <jdk_root>/jre/lib/security directory.
e. Edit <jdk_root>/jre/lib/security/java.security file, add bouncy 
   castle as one of the provider, for example:
   security.provider.6=org.bouncycastle.jce.provider.BouncyCastleProvider
f. Restart your container.
    This test requires that there are an existing federation between
       sp1Userandidp1User, and another existing federation betweensp2Userandidp1User.To perform this test, some preparation on encryption is needed if
       encryption is turned on, i.e., if "Enable Mapped Name Identifier
       Encryption" attribute for IDP1(onIDP1's administration 
       console, Federation Management->Entity Provider->www.idp1.com)
       is "true" which is the default value.Request and Install an encryption certificate on the SP2site, the
       procedure is the same as installing a certificate for XML signature, see
       the Readme file under .../SUNWam/samples/saml/xmlsig for details. If
       there is a signature certificate already installed, then it can be
       shared by encryption, and this step can be omitted.Then go to SP2's administration console to specify the alias of this
       certificate under "Encryption Key Alias", the key size under
       "Encryption Key Size" (e.g. 256), and the encryption method under
       "Encryption method" (e.g., AES).Now install the above certificate in IDP1's key store.Then go to IDP1's administration console, and go to
       Federation Management->Entity Provider->www.sp2.com
       and specify those three attributes with the same values as above. Now
       the preparation is done, and the actual test can begin.On SP1's protected page (index.jsp) click on "Name ID Mapping"
       link.Two text fields "Target Name Space" and "Target Decryption URL" will
       show up to be filled in. "Target Name Space" will be SP2's provider ID;
       In the case of this sample, it would behttp://www.sp2.com. "Target
       Decryption URL" will be the URL forDecryptNameID.jspwhich is deployed
       onSP2; In the context of this sample, it will be"http://www.sp2.com/sp2/DecryptNameID.jsp". If your server
       is not running on port 80, you need to add your port number afterwww.sp2.comin the URL.After those two fields are correctly filled in and
       "send NameIDMappingRequest"button is clicked, the desired name ID will
       appear in a browser page. 
       Here is what really happens: First, SP1 sends the Name ID Mapping request
       to IDP; Then IDP encrypts the Name ID with SP2's public key, and sends the
       encrypted Name ID to SP1 through Name ID Mapping response; Finally, SP1
       sends the encrypted Name ID to SP2, and then SP2 decrypts the Name ID. |