CA SiteMinder® SAML Affiliate Agent Guide 6.x QMR 6 This documentation, which includes embedded help systems and electronically distributed materials, (hereinafter referred to as the “Documentation”) is for your informational purposes only and is subject to change or withdrawal by CA at any time. This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. This Documentation is confidential and proprietary information of CA and may not be disclosed by you or used for any purpose other than as may be permitted in (i) a separate agreement between you and CA governing your use of the CA software to which the Documentation relates; or (ii) a separate confidentiality agreement between you and CA. Notwithstanding the foregoing, if you are a licensed user of the software product(s) addressed in the Documentation, you may print or otherwise make available a reasonable number of copies of the Documentation for internal use by you and your employees in connection with that software, provided that all CA copyright notices and legends are affixed to each reproduced copy. The right to print or otherwise make available copies of the Documentation is limited to the period during which the applicable license for such software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed. TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION “AS IS” WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE. The use of any software product referenced in the Documentation is governed by the applicable license agreement and such license agreement is not modified in any way by the terms of this notice. The manufacturer of this Documentation is CA. Provided with “Restricted Rights.” Use, duplication or disclosure by the United States Government is subject to the restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)(3), as applicable, or their successors. Copyright © 2011 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies. CA Product References This document references the following CA products: ■ SiteMinder® ■ TransactionMinder® ■ Identity Manager Contact CA Contact CA Support For your convenience, CA provides one site where you can access the information you need for your Home Office, Small Business, and Enterprise CA products. At http://ca.com/support, you can access the following: ■ Online and telephone contact information for technical assistance and customer services ■ Information about user communities and forums ■ Product and documentation downloads ■ CA Support policies and guidelines ■ Other helpful resources appropriate for your product Provide Feedback If you have comments or questions about CA product documentation, you can send a message to [email protected]. If you would like to provide feedback about CA product documentation, complete our short customer survey, which is available on the CA Support website at http://ca.com/docs. Contents Chapter 1: SAML Affiliate Agent Overview 11 Introducing the SAML Affiliate Agent ................................................................ 11 Federation Security Services Terminology ........................................................ 13 Components of the SAML Affiliate Agent ......................................................... 14 How the SAML Affiliate Agent is Invoked ......................................................... 15 Communication Across the Federated Network ................................................... 15 How a SAML Affiliate Agent Handles Unidentified Users ............................................ 19 Features of the SAML Affiliate Agent ................................................................ 19 SAML Assertions.............................................................................. 19 Notifications of Activity at the Consumer ......................................................... 20 Shared Sessions for Seamless Communication .................................................... 20 Persistence API and the KeyProvider API ......................................................... 20 SAML Affiliate Agent Installation and Configuration .................................................... 21 Chapter 2: Prepare the Installation 23 Installation Overview ............................................................................. 23 Set up the Producer Site ........................................................................... 24 Set Up the Consumer Site .......................................................................... 25 Check the Web Server Setup at the Consumer .................................................... 25 Confirm Sun Java Software for the SAML Affiliate Agent ............................................ 26 Set Up the SAML Affiliate Agent................................................................. 26 Chapter 3: Install a SAML Affiliate Agent 27 Introduction to SAML Affiliate Agent Installation ...................................................... 27 Before You Begin ................................................................................. 27 Select a Producer-side Web Server for Back-channel Connections .................................... 28 Close Windows Applications Before Installing ..................................................... 28 Choose an Installation Mode ....................................................................... 28 Install the SAML Affiliate Agent in GUI Mode ......................................................... 29 Run the GUI Installation ....................................................................... 29 What To Do Next ............................................................................. 32 Install the SAML Affiliate Agent in Console Mode (UNIX Only) ........................................... 32 Installation Notes ............................................................................. 33 Run the Installation in Console Mode ............................................................ 34 What to Do After Installing the SAML Affiliate Agent ............................................... 36 Run the SAML Affiliate Agent Unattended Installation .................................................. 36 Contents 5 Prepare an Unattended Installation ............................................................. 37 Run an Unattended Installation ................................................................. 37 What To Do After Running the Unattended Installation ............................................. 39 Configure the SAML Affiliate Agent for Your Web Server................................................ 39 How to Configure an IIS Web Server for the SAML Affiliate Agent .................................... 39 Configure a Sun Java System Web Server for the SAML Affiliate Agent ................................ 43 Configure an Apache Web Server for the SAML Affiliate Agent ....................................... 44 Check that the Affiliate Server Has Started ........................................................... 47 Check the Affiliate Server on Windows Systems ................................................... 47 Check the Affiliate Server on UNIX Systems ....................................................... 47 Perform the Initial Agent Configuration .............................................................. 48 Edit the AffiliateConfig.xml File ................................................................. 48 Check for the Affiliate Server Log File ............................................................ 49 Reconfigure the SAML Affiliate Agent ............................................................ 49 Reinstall the SAML Affiliate Agent ................................................................... 50 Uninstall the SAML Affiliate Agent .................................................................. 51 Uninstall the SAML Affiliate Agent From Windows Systems ......................................... 51 Uninstall the SAML Affiliate Agent From UNIX Systems ............................................. 52 Chapter 4: Configure a SAML Affiliate Agent 55 Configure the Affiliate Server ....................................................................... 55 Guidelines for Modifying the Affiliateserverconf.properties File...................................... 55 Affiliate Server Communication with the Web Server Plug-in ........................................ 55 Specify the Number of Threads for Requests ...................................................... 56 Configure Logging ............................................................................ 56 Determine SSL Cache Time ......................................................................... 58 Designate Message Factories ....................................................................... 59 Close the Artifact Back Channel After Assertion Retrieval ............................................... 59 Restart the Affiliate Server ......................................................................... 59 Restart the Affiliate Server on Windows Systems .................................................. 60 Restart the Affiliate Server on UNIX Systems ...................................................... 60 Configuring the Affiliate Web Server Plug-in .......................................................... 60 Guidelines for Modifying the AffiliateConfig.xml File ............................................... 61 Requirement for AffiliateConfig.xml on Solaris Platforms ........................................... 61 Modify the SAML Affiliate Agent Configuration........................................................ 62 Modify Individual Server Configurations .......................................................... 62 Run the Configuration Wizard .................................................................. 63 Chapter 5: Configure Global Settings 67 Global Configuration Settings ...................................................................... 67 Processing URL-Encoded Targets .................................................................... 67 6 SAML Affiliate Agent Guide Enable the Agent to Work with Multiple AuthTrans Functions ........................................... 68 HTTP and HTTPS Port Number Configuration ......................................................... 68 Ensuring HTTP Request and Response Port Numbers Match ......................................... 68 HTTPS Ports for SSL Connections ................................................................ 69 Configure HTTP Header Operation .................................................................. 70 Set HTTP Header Syntax for Legacy Variables ..................................................... 70 Allow HTTP Header Caching .................................................................... 71 Encode and Wrap HTTP Headers ................................................................ 72 Log Error Messages ............................................................................... 72 Record Messages in a Log File .................................................................. 73 Specify Log Levels............................................................................. 73 Append Messages to Log Files .................................................................. 74 How to Display Log Messages in a Console Window (Windows Only) ................................. 75 Return Users to the Affiliate after Obtaining a SAML Artifact ............................................ 76 Configure PKI for the SSL Connection to the Producer .................................................. 76 Set the Location of the Key Store ................................................................ 76 Modify the Key Store Password ................................................................. 77 Define the Key Model for Encrypting Cookies ......................................................... 77 Specify the Key Model ......................................................................... 77 Modify the Shared Secret with Encryptkey ....................................................... 80 Handle Security Issues in Request URLs .............................................................. 80 Specify Ignored File Extensions ................................................................. 80 Designate Bad URL Characters .................................................................. 82 Designate Bad Query Characters ................................................................ 83 Protect Web Sites Against Cross-Site Scripting .................................................... 83 Preserve Assertion Data ........................................................................... 84 Locate a Custom Message File ...................................................................... 85 Track User Activity ................................................................................ 85 Log the Transaction ID for an IIS Web Server ...................................................... 85 Log the Transaction ID for a Sun ONE Web Server ................................................. 86 Log the Transaction ID for an Apache Web Server ................................................. 87 Chapter 6: Configure Portal Settings 89 Portal Settings ................................................................................... 89 Specify the Number of SSL Connections for Communication............................................. 89 Specify the Portal Name ........................................................................... 90 Redirect Users without Valid Affiliate Cookies to the Producer .......................................... 90 Configure the Affiliate to Retrieve a SAML Assertion ................................................... 90 Specify the Session Provider Service ................................................................. 91 Specify the Notification Service ..................................................................... 92 Enable the Agent to Work with Multiple Producers .................................................... 93 Contents 7 Chapter 7: Configure Affiliate Settings 95 Affiliate Settings .................................................................................. 95 Enable and Disable the SAML Affiliate Agent .......................................................... 95 Identify the Affiliate and Affiliate Resources .......................................................... 96 Name the Affiliate ............................................................................ 96 Set the Affiliate Password ...................................................................... 96 Designate Affiliate Resources ................................................................... 97 Modify the Consumer Cookie Domain .......................................................... 100 Identify the Portal ............................................................................... 100 Name the Portal ............................................................................. 100 Set the Company Source ID ................................................................... 100 Manage User Access to Consumers................................................................. 101 Permit Unknown Users Access to the Consumer .................................................. 102 Refuse Anonymous User Access to the Consumer ................................................ 102 Deny a User Access to an Consumer Resource ................................................... 102 Communication Across a SiteMinder Federated Network .............................................. 103 Determine How the Consumer Authenticates to the Producer ...................................... 103 Designate the Assertion Issuer and Audience .................................................... 104 Allow Post Actions ........................................................................... 105 Configure SiteMinder Sessions for Federated Single Sign-on ........................................... 106 Session Server Overview ...................................................................... 108 Default Session Overview ..................................................................... 108 Active Portal Session Overview ................................................................ 109 Shared Sessions ............................................................................. 110 Response Attributes and Default HTTP Headers Overview ......................................... 113 Log Users Out from a Session .................................................................. 113 Configure the Notification Service .................................................................. 114 Define the MatchingRule for the Notification Service ................................................. 115 Use a StrictPrefix ............................................................................ 116 Use a Substring Prefix ........................................................................ 116 Chapter 8: Response Headers for Customizing Web Applications 117 Response Attributes to Personalize Content ......................................................... 117 Configure Affiliate Response Attributes ......................................................... 118 Use SAML Affiliate Agent Default HTTP Headers ...................................................... 119 Chapter 9: Upgrade to SAML Affiliate Agent v6.x QMR 6 121 Upgrade a 5.x or 6.0 SAML Affiliate Agent to 6.x QMR 6 ............................................... 121 Step 1: Plan a Recovery Strategy ............................................................... 123 Step 2: Uninstall the 5.x/6.0 SAML Affiliate Agent................................................. 123 8 SAML Affiliate Agent Guide Step 3: Upgrade to the 6.x QMR 6 SAML Affiliate Agent ........................................... 123 Step 4: Modify the Configuration of the Upgraded Agent .......................................... 126 Upgrade a 4.51/4.61 Affiliate Agent to a 6.x SAML Affiliate Agent ....................................... 127 Plan a Recovery Strategy...................................................................... 128 Perform an Upgrade at the Producer Site........................................................ 128 Upgrade the 4.51/4.61 Affiliate at the Consumer Site ............................................. 133 Step 5: Add an Affiliate to an Affiliate Domain.................................................... 136 Chapter 10: Extend a SAML Affiliate Agent 139 SAML Affiliate Agent Extensions Overview .......................................................... 139 Persistence API.................................................................................. 139 Sequence of Events .......................................................................... 140 Lifetime of Entitlement Data .................................................................. 140 Entitlement Payload ......................................................................... 140 Persistence Library Path ...................................................................... 141 Persistence API Functions ..................................................................... 141 AssertionExpired() ........................................................................... 141 InitPersistenceLib() .......................................................................... 142 PersistAssertion() ............................................................................ 142 Key Provider API ................................................................................ 143 Key Provider API Functions .................................................................... 144 GetNextKey() ............................................................................... 145 InitKeyProvider() ............................................................................ 145 Chapter 11: SAML Affiliate Agent Troubleshooting 147 Configuration Changes Are Not Taking Effect ........................................................ 147 SAML Affiliate Agent Not Starting .................................................................. 147 The httpd.conf File Shows a Log Level of "warn"...................................................... 148 IIS 6.0 Wildcard Mappings Required to Protect Resources ............................................. 148 Appendix A: Properties File for Unattended Installations 149 General Information ............................................................................. 149 Web Server Descriptions ......................................................................... 150 URL Information................................................................................. 151 Passwords and Shared Secrets ..................................................................... 152 Appendix B: Parameter Descriptions for Agent Configuration 155 Alphabetical List of Elements and Attributes ......................................................... 155 Set the Shared Secret and Affiliate Password ........................................................ 158 Contents 9 Appendix C: Add Certificate Authorities to the Affiliate Key Store 161 Use the AM.keystore Database .................................................................... 161 Information Stored in the AM.keystore Database ................................................. 162 Formats Supported by AM.keystore ............................................................ 162 Modify the AM.keystore Database ................................................................. 163 Import Root Certificate Authorities for Basic over SSL Authentication ................................ 163 Appendix D: Modifications to Sun Java System Files During Agent Installation 165 Modifications Made to Sun Java System/Windows Platforms ........................................... 165 Code Added to the magnus.conf File (Sun Java System/Windows Platform) ........................... 166 Code Added to the obj.conf File (Sun Java System/Windows Platform) ............................... 166 Modifications Made to Sun Java System/UNIX Platforms .............................................. 166 Code Added to the magnus.conf File (Sun Java System/UNIX Platform) .............................. 167 Code Added to the obj.conf File (Sun Java System/UNIX Platform) .................................. 167 Appendix E: Federation Web Services Messages 169 Sample Affiliate Agent Request Messages ........................................................... 169 SAML Request for Assertion Retrieval ........................................................... 169 Notification Request Message ................................................................. 170 Session Logout Request Message .............................................................. 170 Session Validate Request Message ............................................................. 170 Sample Response Messages ....................................................................... 171 SAML Response with an Embedded Assertion .................................................... 171 Notification Response Message ................................................................ 174 Session Logout Response Message ............................................................. 174 Session Validate Response Message ............................................................ 175 Appendix F: 4.x Affiliate.conf Parameter Mappings 177 Map 4.x Affiliate Parameters to 6.x Parameters ...................................................... 177 Appendix G: Environment Variables Modified by the Agent Installation 181 Added or Modified Environment Variables .......................................................... 181 Index 183 10 SAML Affiliate Agent Guide