Previous Topic: Legacy Federation IntroductionNext Topic: Deploy Legacy Federation Using a Manual Configuration


Deploy Legacy Federation Using the Sample Application

This section contains the following topics:

Legacy Federation Sample Application Overview

Legacy Sample Application Deployment

Sample Application Components

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

Legacy Federation Sample Application Overview

To become familiar with CA 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 CA SiteMinder® policy objects that the sample application creates. Also, examine the CA 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.

Legacy Sample Application Deployment

The sample websites in the CA 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.

Figure shoing how legacy sample application can be deployed

Sample Application Components

The legacy sample application contains the following components:

FederationSample.conf

The FederationSample.conf file contains configuration settings that define the IdP and SP-side policy objects.

SetupFederationSample.pl Perl script

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.

Web pages to test single sign-on and single logout

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.

Prerequisites to Deploy the Sample Application

Before you run the sample application, satisfy the following requirements.

Deployment requirements (CA SiteMinder® 12.52 components recommended):

On the Policy Server system:

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 CA SiteMinder® must function properly to run the sample application successfully.

How To Run the Sample Application

After you complete the necessary prerequisites, set up your environment to run the sample application.

On the Policy Server system

  1. Set your command line path.
  2. From the Administrative UI, configure a web agent and name it agent.
  3. Modify the FederationSample.conf file for your environment.
  4. Run the SetupFederationSample.pl Perl script to run the sample application.

On the Web Agent system

  1. Copy the idpsample and spsample directories to the Web Agent system.
  2. Add a virtual directory for the idpsample and spsample directories on the Web Agent system.
  3. Edit the host file on the Web Agent system and any other system from where you plan to access the application from a browser.

After your setup is complete on all systems, test single sign-on and single logout.

Set the Path Variable on the Policy Server System

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:

  1. Open a command window.
  2. Enter the following command:

    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.

Configure a Web Agent in the Administrative UI

Create a Web Agent and name it agent.

Follow these steps:

  1. Log in to the Administrative UI.
  2. Navigate to Infrastructure, Agents.
  3. Create a web agent object.
  4. Enter agent in the Name field.
  5. Click Submit.
Modify the FederationSample.conf File

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

  1. Go to policy_server_home/samples/federation.
  2. Open the FederationSample.conf file.
  3. Modify the file settings.
  4. Save the file.
FederationSample.conf Settings

Configure all the settings in the FederationSample.conf file.

The settings are as follows:

USER_DIRECTORY

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.

USER_ATTRIBUTE

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:

AGENT_NAME

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.

WEB_SERVER_DOC_ROOT

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.

WEB_SERVER_PORT

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.

PARTNER_WEB_SERVER_PORT

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.

Modify the SetupFederationSample.pl Script (Optional)

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

  1. Open the script in an editor.
  2. Comment out the CheckPreRequisites line, as shown here:
    if ($CURRENT_COMP == $COMP_FSS)
    {
    #   CheckPreRequisites();
    }
    
  3. Save the script.
SetupFederationSample.pl Script Options (fss)

The SetupFederationSample.pl script uses the following command options:

-admin

Specifies the user name of the CA SiteMinder® Administrator.

-password

Specifies the password of the CA SiteMinder® Administrator in clear text.

-remove

Removes all objects that the sample application creates.

-idp

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 CA SiteMinder®-to-CA SiteMinder® communication.

Options: FSS, SMFE

-sp

Creates only Service Provider policy objects in the policy store. You cannot use this option and the -idp option together.

Options: FSS, SMFE

-partner

(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.

Run the Sample Application on the Policy Server System

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:

  1. Complete all prerequisites.
  2. Modify the FederationSample.conf file.
  3. (Optional) Modify the SetupFederationSample.pl script.

To run the sample application

  1. Open a command window.
  2. Navigate to policy_server_home/siteminder/samples/federation.
  3. Run the SetupFederationSample.pl script using the Perl interpreter that is shipped with CA SiteMinder®. This script is in the directory policy_server_home/CLI/bin.
    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.

  4. Enter yes when you are prompted to continue with the installation. Do not enter the letter "y."

    You can review the list of script command options.

Using Multiple Policy Servers for the Sample Application

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:

You can review the list of script command options.

Set up the Web Agent System

Set up the Web Agent system to use the sample application.

Follow these steps:

  1. On the Policy Server system, navigate to the web server root directory that you specified in the FederationSample.conf file. Refer to the WEB_SERVER_DOC_ROOT setting.
  2. Copy the idpsample and spsample directory web_agent_home/affwebservices on the Web Agent system.
  3. Add a virtual directory mapping for the idpsample and spsample directories. Map to the following physical directories:

    web_agent_home/affwebservices/idpsample

    web_agent_home/affwebservices/spsample

  4. Add mappings for www.idp.demo and www.sp.demo to the hosts file for the Web Agent system.
    Windows

    The host file is typically in WINDOWS\system32\drivers\etc\hosts.

    UNIX

    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.

Using Multiple Web Agents for the Sample Application

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.

Test Single Sign-on with the Sample Application

After you run the sample application, test single sign-on.

To test federated single sign-on

  1. Open up a browser.
  2. Enter the URL for the web page that has links to trigger single sign-on.

    The following illustration is the IdP.demo home page:

    Graphic showing an Idp Demo Page

    The following illustration is the SP.demo home page:

    Graphic showing a Demo site

  3. Click on one of the single sign-on links.

    A login challenge like the following dialog is presented:

    Graphic showing a logon prompt page

  4. Using the login of an existing user in your user store, enter the user credentials. For example, if user1 is a user in the user store, enter the credentials for this user.

    If single sign-on is successful, the following welcome page appears:

    Graphic showing the Welcome Page for a demo site

Test Single Logout with the Sample Application

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:

Graphic showing a logout page

Review Application-Generated SiteMinder Objects

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:

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.