Federation Security Services Guide › Deploy Federation Using the Sample Application › How To Run the Sample Application › Modify the FederationSample.conf File › FederationSample.conf Settings

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 in the FSS Administrative UI. 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, provided 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 ID value in the SAML assertion. If no value is specified for this setting, the sample application script chooses a value based on the user directory type. Example of attribute values can include:

• LDAP: uid or mail
• ODBC: name or email

If no value is specified, the following defaults are used:

• For LDAP: uid
• For ODBC: name
• For ActiveDirectory: cn

AGENT_NAME

Defines the name of the DefaultAgentName configuration setting for the Web Agent. This setting is specified in the Agent Configuration Object of the Policy Serve User Interface. If no value is specified for this setting, the sample application script reads the DefaultAgentName from the policy store, provided only one Agent configuration object found 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. For example, if you are using a Sun Java System web server, the path would be server_root/docs .

WEB_SERVER_PORT

Specifies the listening port of the web server. The default port is 80.

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 IdP, then this site is the SP web server port. The default port is 80.

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:

• Reads the configuration information from the FederationSample.conf file.
• Creates policy objects in the policy store to establish the SAML 2.0 single sign-on and single logout profiles.
• Copies web pages to the web server document root
• Adds a private key/certificate pair to the certificate data store.
• Modifies the hosts file of the system to map a loopback IP address, 127.0.0.1 to www.sp.demo and www.idp.demo.

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 SiteMinder Administrator.

-password

Specifies the password of the 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 SiteMinder-to-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 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:

• On the IdP Policy Server, enter:

  perl SetupFederationSample.pl -admin siteminder_administrator
  -password administrator_password -idp FSS
  

• On the SP Policy Server, enter:

  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

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.

• At the Identity Provider Web Agent, modify the host file of this system to include the IP address of the SP system, www.sp.demo.
• At the Service Provider Web Agent, modify the host file of this system to include the IP address of the Identity Provider system, www.idp.demo.

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.
   • For IdP-initiated single sign-on, access the index.jsp page at:

     http://www.idp.demo:server_port/idpsample/index.jsp

   • For SP-initiated single sign-on, access the index.jsp page at:

     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:

   

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

   A login challenge like the following dialog is presented:

   

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:

   

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: