This section contains the following topics:
Legacy Federation Sample Application Overview
Legacy Sample Application Deployment
Prerequisites to Deploy the Sample Application
How To Run the Sample Application
Test Single Sign-on with the Sample Application
Test Single Logout with the Sample Application
Review Application-Generated SiteMinder Objects
To become familiar with SiteMinder legacy federation, deploy the legacy federation sample application. The sample application automates all the federation setup tasks to accomplish SAML 2.0 single sign-on and single logout. After you run the sample application, look at the SiteMinder policy objects that the sample application creates. Also, examine the SiteMinder logs containing assertions. Finally, use the sample application objects as a basis for configuring your own federation environment.
Note: The legacy federation sample application only creates SAML 2.0 objects.
The sample websites in the SiteMinder federated network are an Identity Provider named idp.demo, and a Service Provider named sp.demo. A business partnership is established between idp.demo and sp.demo.
You can deploy the sample application in many ways. We recommend one of two ways:
The following illustration shows two deployments of the sample application.
The legacy sample application contains the following components:
The FederationSample.conf file contains configuration settings that define the IdP and SP-side policy objects.
The SetupFederationSample.pl Perl script executes the federation sample application. This script creates the objects for the IdP and SP sites. The script also creates the necessary web pages to initiate single sign-on and single logout between the IdP and the SP. The script relies on the information in the FederationSample.conf file to operate.
Use the Perl interpreter included with the sample application to run the application.
The sample application installs two directories that contain template pages for testing SAML 2.0 single sign-on and single logout transactions. The directories, idpsample and the spsample, are installed in the directory siteminder_home/siteminder/samples/federation/content.
These directories are also copied to the default document root directory of the web server.
The IdP web pages are in the idpsample directory. These pages include:
Index.jsp is the first web page the user accesses at the IdP for IdP-initiated single sign-on. This page provides the link to the protected target resource at the sp.demo partner site. This page also provides a single logout link.
Note: The single logout link is displayed only if FSS is the IdP and an SMSESSION cookie is in the request headers.
SLOConfirm.jsp displays a message that the user has successfully logged out from idp.demo and sp.demo domains.
The SP web pages are in the spsample directory. These pages include:
Index.jsp is the first web page the user accesses at the SP for SP-initiated single sign-on. This page provides a link to the protected target resource. This page also provides single logout link.
Note: The single logout link is displayed only if FSS is the IdP and an SMSESSION cookie is in the request headers.
Target.jsp, a protected page at the sp.demo partner site, is located in the /spsample/protected directory. The SAML 2.0 authentication scheme protects this page. A user sees this page when single sign-on between the IdP and SP succeeds.
SLOConfirm.jsp displays a message that the user has successfully logged out from the idp.demo and sp.demo domains.
Before you run the sample application, satisfy the following requirements.
Deployment requirements (SiteMinder r12.5 components recommended):
The web server where you install the Web Agent does not require an SSL port.
If you install the Policy Server, Web Agent, and Web Agent Option Pack on one system, we recommend using ServletExec as the application server. To install the Web Agent Option Pack and deploy Federation Web services on an application server, see the Web Agent Option Pack Guide.
On the Policy Server system:
For instructions on configuring a session store, see the Policy Server Administration Guide.
On the web agent system:
Note: If your deployment uses only one system, install all components on that one system. If your deployment has more than one Policy Server and more than one Web Agent, complete the prerequisites on all relevant systems.
Verify that the Policy Server and Web Agent are configured properly and that you can protect a resource.
Important! Core SiteMinder must function properly to run the sample application successfully.
After you complete the necessary prerequisites, set up your environment to run the sample application.
On the Policy Server system
On the Web Agent system
After your setup is complete on all systems, test single sign-on and single logout.
On the system where the Policy Server resides, set the path variable. You can set the Path as a command line path, which affects only the local command prompt.
Follow these steps:
set path=%NETE_PS_ROOT%\cli\bin;%NETE_PS_ROOT%\cli\lib;%path%
Important! Verify that the Perl binary bundled with the Policy Server is the first or only such binary in the PATH. Invoke the bundled Perl binary, not another Perl script.
Note: You can also set the Path in the system environment variable.
Create a Web Agent and name it agent.
Follow these steps:
The FederationSample.conf file holds the settings for the local environment, such as the user directory.
The application uses the FederationSample.conf file to create Identity Provider and Service Provider policy objects.
On the Policy Server, complete the following steps
Configure all the settings in the FederationSample.conf file.
The settings are as follows:
Specifies the name of an existing user directory object specified in the Administrative UI. Enter the name of the user directory.
This directory must contain at least one user entry. If no value is specified for this setting, the sample application script reads the user directory information from the policy store. The script assumes that only one user directory is listed. If more than one user directory is listed, the sample application script asks the user to enter the user directory name in this file. The default value does not exist.
Indicates that the value of this attribute becomes the Name Identifier value in the SAML assertion. If no value is specified for this setting, the sample application script chooses a value. The chosen value is based on the user directory type.
Example of attribute values can include:
If no value is specified, the following defaults are used:
Defines the name of the DefaultAgentName setting for the Web Agent you installed. This setting is specified in the Agent Configuration Object in the Administrative UI.
If you do not specify a value for the DefaultAgentName, the sample application script reads the DefaultAgentName from the policy store. The script assumes that only one Agent configuration is in the policy store. If more than one Agent configuration object exists, the sample application prompts the user to enter the DefaultAgentName value in this file.
Specifies the full path to the document root directory of the web server. The default value is C:\Inetpub\wwwroot, the root directory for an IIS web server. The document root directory is specific to your web server.
If you deploy all components on the same system, change the value of this setting to web_agent_home/affwebservices.
The Web Agent and Web Agent Option Pack can be on a different system from the Policy Server. For this deployment, copy the idpsample and spsample directories from the location specified in this setting to the web_agent_home/affwebservices directory on the Web Agent system.
Specifies the listening port of the web server. The default port is 80.
In a deployment with two web agents, one at the IdP site and the other at the SP site, enter the port number for the web server at the site you are configuring.
Specifies the listening port of the web server on the opposite side of the federation connection. For example, if your site is the Identity Provider, then this site is the Service Provider web server port. The default port is 80.
In a deployment with two web agents, one at the IdP site and the other at the SP site, enter the port number for the web server at the partner site you are configuring.
The SetupFederationSample.pl script executes the sample application. This script resides in the directory policy_server_home/samples/federation.
The SetupFederationSample.pl script deploys the sample application. The script accomplishes these tasks:
Important! If you install the Policy Server and the Web Agent Option Pack on different machines, comment out the call to CheckPreRequisites() in the SetupFederationSample.pl file.
To comment out the CheckPreRequisites() call
if ($CURRENT_COMP == $COMP_FSS)
{
# CheckPreRequisites();
}
The SetupFederationSample.pl script uses the following command options:
Specifies the user name of the SiteMinder Administrator.
Specifies the password of the SiteMinder Administrator in clear text.
Removes all objects that the sample application creates.
Creates only the Identity Provider objects in the policy store. You cannot use this option and the -sp option together. If you do not specify a value for this option or the -sp option, the sample application assumes a default of SiteMinder-to-SiteMinder communication.
Options: FSS, SMFE
Creates only Service Provider policy objects in the policy store. You cannot use this option and the -idp option together.
Options: FSS, SMFE
(optional) Indicates which application is installed at the partner site. The default is FSS.
Options: FSS, SMFE
Important! All the command line options are case-sensitive.
Deploy the sample application on the Policy Server system.
You must have read/write permissions to the document root directory of the web server to run the sample application script.
Note: Run the SetupFederationSample.pl script once. If you run it again, the script deletes the sample policy objects that the previous execution of the script created.
Before you run the sample application:
To run the sample application
perl SetupFederationSample.pl -admin siteminder_administrator -password administrator_password
Example:
perl SetupFederationSample.pl -admin siteminder -password mypassword
Important! All the command line options are case-sensitive.
You can review the list of script command options.
To establish a physically distinct Identity Provider and a Service Provider, you can set up a four-system environment.
The Identity Provider site uses a Policy Server and a Web Agent with the Web Agent Option Pack. The Service Provider site uses a second Policy Server and a Web Agent with the Web Agent Option. The Policy Servers and Web Agents with Option Packs are on separate systems.
If you set up a four-system environment, run the SetupFederationSample.pl script on both Policy Server systems. Use one of the following commands:
perl SetupFederationSample.pl -admin siteminder_administrator -password administrator_password -idp FSS
perl SetupFederationSample.pl -admin siteminder_administrator -password administrator_password -sp FSS
You can review the list of script command options.
Set up the Web Agent system to use the sample application.
Follow these steps:
web_agent_home/affwebservices/idpsample
web_agent_home/affwebservices/spsample
The host file is typically in WINDOWS\system32\drivers\etc\hosts.
The host file is commonly in /etc/hosts.
Note: You can access the sample application through a browser on any system; however, the system must have the correct host mappings for www.idp.demo and www.sp.demo.
To establish a physically distinct Identity Provider and a Service Provider, you can set up a four-system environment.
The Identity Provider site uses a Policy Server and a Web Agent with the Web Agent Option Pack. The Service Provider site uses a second Policy Server and a Web Agent with the Web Agent Option. The Policy Servers and Web Agents with Option Packs are on separate systems.
If you set up a four-system environment, modify the host file of each Web Agent system. The Web Agent must be able to recognize the other system with which it is communicating.
After you run the sample application, test single sign-on.
To test federated single sign-on
http://www.idp.demo:server_port/idpsample/index.jsp
http://www.sp.demo:server_port/spsample/index.jsp
The following illustration is the IdP.demo home page:
The following illustration is the SP.demo home page:
A login challenge like the following dialog is presented:
If single sign-on is successful, the following welcome page appears:
After you have successfully tested single sign-on, you can test single logout from the SP.demo welcome page.
To test single logout
On the SP Welcome page, click the link labeled Single Logout using HTTP Redirect binding.
If single logout is successful, the following page appears:
The sample application automatically creates policy objects that enable the federated single sign-on and logout processes. After you successfully sign-on, log in to the Administrative UI and look at the various Policy Server objects that the sample application sets up.
Objects to look at include:
The sample application creates this Service Provider object.
The sample application creates this SAML Authentication Scheme at the Service Provider.
To see the SAML assertion, look at the FWSTrace.log, located in the directory web_agent_home/log.
Note: Enable trace logging in the LoggerConfig.properties file to create a trace log. The LoggerConfig.properties file is located in web_agent_home/affwebservices/WEB-INF/classes.
|
Copyright © 2012 CA Technologies.
All rights reserved.
|
|