Sun Java System Access Manager version 6 2005Q1
Sample
 

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/hosts file 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.

SP1 and SP2 are two Service Providers. IDP1 and IDP2 are two Identity Providers.

  1. For Solaris
           <begin_dir> = <IS_Root>/SUNWam
  2. For Windows2000
           <begin_dir> = <IS_Root>/SunONEIS
  3. <begin_dir>/samples/liberty/sample3/ will be referred to as <sample3_dir>.


2. Instructions

A. Create and configure sub organizations

For this sample you will need to create four sub organizations under the root organization. Each hosted provider will be associated with one of these sub organizations. The subOrgRequests.xml available under <sample3_dir> will do the followings.
    a. Create four sub organizations namely sp1, sp2, idp1 and idp2.
    b. Register Core service and LDAP service for each of these sub
       organizations.
    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 ids as sp1User, sp2User, idp1User
       and idp2User for the sub organizations sp1, sp2, idp1 and idp2
       respectively. All the passwords are the same as the user ids (i.e.
       sp1User's password is sp1User).

  1. 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 is running on port 58080
           d. AM services are deployed under the URI: amserver
           e. 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 in subOrgRequests.xml as your deployment requirement.
  2. Load subOrgRequests.xml using 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.xml available under <sample3_dir> creates these hosted providers and configures the meta data for all the providers.

  1. 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. SP2 Certificate Alias is SP2_SECURITY_KEY
           h. IDP1 Certificate Alias is IDP1_SECURITY_KEY
           i. IDP2 Certificate Alias is IDP2_SECURITY_KEY
           j. SP1 metaAlias is www.sp1.com
           k. SP2 metaAlias is www.sp2.com
           l. IDP1 metaAlias is www.idp1.com
           m. IDP2 metaAlias is www.idp2.com
           n. SP1's associated organization is "o=sp1,dc=example,dc=com".
           o. SP2's associated organization is "o=sp2,dc=example,dc=coma".
           p. IDP1's associated organization is "o=idp1,dc=example,dc=com".
           q. IDP2's associated organization is "o=idp2,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)
           
    Update the above values in the metaData.xml as your deployment scenario.

    Note: In the given metaData.xml common domain URL's host name is entered as virtual host name (www.sp1.com), in this case in FSIntroConfig.properties (available in <begin_dir>/web-apps/introduction/WEB-INF/classes) you need 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)
  2. Load the metaData.xml using following command.
           <begin_dir>/bin/amadmin -u amadmin -w <amadmin's password>
              -t <path>/metaData.xml
           

C. Create SP1 virtual server and Deploy SP1

This sample scenario requires four virtual servers. Urlhosts for these virtual servers will be assumed as www.sp1.com, www.sp2.com, www.idp1.com and www.idp2.com.

  1. 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 the SP1Config.properties as per your deployment scenario.
  2. Repate 1 for SP2, IDP1 and IDP2.
  3. Login to web server as administrator.
  4. Click <Manage> button to Manage server (In this case, it is https-<fullhostname>).
  5. Click on Virtual Server Class.
  6. Click on Manage for the "vsclass1"
  7. Click Add Virtual Server
  8. Name the "Name" to sp1VS
  9. Select connections(In this case it is the default one)
  10. Add urlhosts entry to the domain for which the virtual server runs on. For sp1VS use www.sp1.com
  11. Add Documentroot entry to <INSTALL_DIR>/SUNWam/web-apps
  12. Click OK
  13. Repeat 6-10 for SP2, IDP1 and IDP2.
  14. Click Apply and Click Apply Changes. The server will be restarted.
  15. Click Virtual Servers and Click Manage (In this case, it is https-<fullhostname>)
  16. Click Web Applications
  17. On Server machine, create war file for SP1
           cd <sp1_sample_dir/sp1>
           jar -cvf sp1.war
  18. War File On - Choose Server Machine and click Go
  19. War File Path - Enter the full patch that the war file we just created.
  20. Application URI - /sp1
  21. Installation Directory : <INSTALL_DIR>/SUNWam/web-apps
  22. Repeat 15-19 for SP2, IDP1, IDP2
  23. Retsart Web Server.

D. Configure Access Manager for SP1 virtual server:

  1. Login to the Access Manager as amadmin and go to the Service Configuration tab.
  2. Click on Platform service.
  3. Add new server as "server with new domain and port". For example add a value in server list with "http://www.sp1.com:58080|02"
  4. Update the cookie domains list in the platform services with the domain that you have created for the SP1 - ".sp1.com". Add ".sp1.com" to the cookie domains list.
  5. Add fqdnMap entry for SP1 virtual server in /etc/opt/SUNWam/config/AMConfig.properties:
           com.sun.identity.server.fqdnMap[www.sp1.com]=www.sp1.com
           
    The FQDN Map 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.
  6. Repeat step 1-5 to configure the Access Manager for the remaining providers (SP2, IDP1 and IDP2). Use sp2/idp1/idp2 for all the references to sp1 for the respective provider.
  7. Restart the web server and the Access Manager.

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
           
    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 can choose Federate/Logout/Terminate Federation.
  4. 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 IDP1 as the preferred Identity Provider.
  5. Now you will be taken to IDP1's login page where you need to provide authentication credentials (user-id/password) for the IDP1 account (in this case idp1User/idp1User). If the authentication is successful, you will be shown the FederationDone page.
  6. At this point you have successfully federated your account between SP1 and IDP1.

    Note: When an account is already federated, the you will be redirected to the IDP1 Login page first, assuming the common domain service is properly configured. If the common domain service is not configured properly then you will see the commonLogin page where you can click on the IDP1's link with which you have federated your SP1 account.
  7. Repeat step 1-6 to federate your SP2 account (sp2User) with the IDP1 account (idp1User).

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
           
    Note: If the earlier session is still valid in the new browser, then single logout should be done first. See section H for this.
  2. Now 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 at IDP1. If authentication is successful you will be directly taken to the initially accessed SP1 protected page without being asked for SP1 authentication credentials.
  3. 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 at SP2 (Assuming that you have federated your SP2 account with the account at IDP1). Again, if common domain is not configured you will see commonLogin page where you can select a preferred IDP, with which you federated your account. After clicking on the IDP's link you will be able to see the SP2's initially accessed protected page.
  4. Similarly you can demonstrate federation and single sign on with an account at IDP2 by repeating all the steps in section F and section G by selecting IDP2 as the preferred IDP.

G. Single Logout:

  1. On SP1's protected page (index.jsp) click on "Logout" link.
  2. You will be logged out from all the valid sessions (in this case SP1, SP2 and IDP1)s and will be shown a LogoutDone page.
  3. Alternatively, you can start the logout process from the IDP protected page (index.jsp) as well and accomplish the same.

H. Federation Termination:

  1. On the SP1's protected page (index.jsp) click on "Terminate Federation" link.
  2. You will be taken to a page where you can select a provider to terminate the federation. For example select IDP1 for federation termination.
  3. On successful federation termination you will be taken to TerminationDone page.
  4. Alternatively, you can initiate federation termination from the IDP side also and get the same result.

I. Name ID Mapping:

  1. This test requires that there are an existing federation between sp1User and idp1User, and another existing federation between sp2User and idp1User.
  2. 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 (on IDP1's administration console,
           Federation Management->Entity Provider->www.idp1.com
    is "true" which is the default value.
  3. Request and Install an encryption certificate on the SP2 site, 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.
  4. 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).
  5. Now install the above certificate in IDP1's key store.
  6. Then to to IDP'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.
  7. On SP1's protected page (index.jsp) click on "Name ID Mapping" link.
  8. 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 be http://www.sp2.com. "Target Decryption URL" will be the URL for DecryptNameID.jsp which is deployed on SP2; In the context of this sample, it will be "http://www.sp2.com/sp2/DecryptNameID.jsp".
  9. After those two fields are correctly filled in and "send NameIDMappingRequest" button is clicked, the desired name ID will appear in a browser page.


End of Sample