CA SiteMinder Agent for IBM WebSphere Agent Guide

152 Pages·2010·1.39 MB·English

CA SiteMinder® Agent for
IBM WebSphere
Agent Guide
r12.0 SP2
This documentation and any related computer software help programs (hereinafter referred to as the "Documentation") are for
your informational purposes only and are 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 used or
disclosed by you except as may be permitted in 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 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 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 THE END USER 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 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 © 2010 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to
their respective companies.
CA Technologies Product References
This document references the following CA Technologies products:
■ CA SiteMinder®

Contact CA Technologies
Contact Technical Support
For your convenience, CA Technologies provides one site where you can access
the information you need for your Home Office, Small Business, and Enterprise
CA Technologies 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 Technologies product
documentation, you can send a message to [email protected].
If you would like to provide feedback about CA Technologies product
documentation, complete our short customer survey, which is available on the
CA Support website at http://ca.com/docs.

Contents

Chapter 1: Introduction 11
Overview .................................................................................... 11
Required Background Information .............................................................. 13
SiteMinder Agent for IBM WebSphere Components .............................................. 14
SiteMinder Trust Association Interceptor (TAI) ............................................... 15
SiteMinder Login Module .................................................................. 18
SiteMinder Java Authorization Contract for Containers (JACC) Provider ........................ 20
Other Deployment Considerations ............................................................. 21
Identity and User Mapping ................................................................. 21
User Session Handling ..................................................................... 22
J2EE Programmatic Security Call Principal Usage ............................................. 22
SiteMinder Agent API ...................................................................... 23
Agent Configuration Options ................................................................... 24
Use Cases .................................................................................... 26
SiteMinder TAI-Only Use Case .............................................................. 27
All Modules Use Case ...................................................................... 28
Recommended Reading List ................................................................... 29
Chapter 2: Preconfigure Policy Objects for the SiteMinder Agent 31
Policy Object Preconfiguration Overview ........................................................ 31
Preconfigure the Policy Objects ................................................................ 33
What to Do After Preconfiguring the Policy Server ............................................... 33
Chapter 3: Installing and Upgrading the Agent 35
Overview .................................................................................... 35
Upgrade from a Previous Release .............................................................. 36
Before You Begin ............................................................................. 36
Software Requirements ................................................................... 36
Define the JAVA_HOME Environment Variable ............................................... 38
Installation Checklist ...................................................................... 38
Installation Location References................................................................ 39
Install the SiteMinder Agent for IBM WebSphere ................................................ 39
Information Required During Installation .................................................... 40
Contents 5
Run the Installation in GUI Mode ........................................................... 40
Run the Installation in Console Mode on UNIX ............................................... 45
Install a Web Agent for Advanced TAI Authentication ............................................ 49
Register a Trusted Host Using the Registration Tool .............................................. 49
Register a Trusted Host on Windows ........................................................ 50
Register a Trusted Host on UNIX ............................................................ 51
smreghost Command Arguments ........................................................... 52
Reinstall the SiteMinder Agent ................................................................. 55
Uninstall the SiteMinder Agent ................................................................. 55
Uninstall from Windows ................................................................... 56
Uninstall from UNIX ....................................................................... 56
What to Do After Installing the SiteMinder Agent ................................................ 57
Chapter 4: Configuring the SiteMinder Agent, SiteMinder-Side 59
smagent.properties File ....................................................................... 59
Edit smagent.properties ................................................................... 60
Fine-Tune the Agent Configuration Setup ....................................................... 61
Use One Agent Configuration Object and Multiple Agent Configuration Files ................... 65
Use Module-Specific Agent Configuration Objects ............................................ 65
Use a Shared Agent Configuration File and Configuration Object for All Agent Modules .......... 66
Configure the TAI, SiteMinder-Side ............................................................. 67
Configure the TAI to Only Handle Requests from SiteMinder Session Holders ................... 67
Configure the TAI to Challenge Requests for Credentials ...................................... 70
TAI-Specific Agent Configuration Parameter Summary ........................................ 74
What to Do Next if You Are Setting Up a TAI-Only Configuration ............................... 76
Configure the Login Module, SiteMinder-Side ................................................... 76
Configure the Login Module to Handle Java Client Requests ................................... 76
Configure the Login Module to Handle System Login Requests ................................ 78
Login Module-Specific Agent Configuration Parameter Summary .............................. 81
Configure the SiteMinder JACC Provider, SiteMinder-Side ........................................ 82
Configure Policies for the SiteMinder JACC Provider .......................................... 82
JACC-Specific Agent Configuration Parameters ............................................... 83
What to Do After Completing SiteMinder-Side Configuration ..................................... 84
Chapter 5: Configuring the SiteMinder Agent, WebSphere-Side 85
Configure WebSphere Administration, Applications and infrastructure Settings .................... 85
Configure LDAP as a WebSphere User Account Repository (User Registry) ...................... 86
Enable Administrative Security ............................................................. 87
6 Agent Guide
(Optional) Configure the Class Loader for the SiteMinder Agent Logger ............................ 88
Configure the SiteMinder TAI in WebSphere .................................................... 89
Configure the Login Module in WebSphere ...................................................... 90
Add the SiteMinder Login Module as a WebSphere DEFAULT Login Module .................... 91
Add the SiteMinder Login Module as a WebSphere RMI_INBOUND Login Module ............... 92
Configure the SiteMinder JACC Provider in WebSphere ........................................... 93
Propagate JACC Data Constraint Policy Information to the SiteMinder JACC Provider ................ 95
What to Do After Completing WebSphere-Side Configuration ..................................... 96
Chapter 6: Verifying SiteMinder Agent Installation and
Configuration 99
SiteMinder Agent Verification Overview ........................................................ 99
Set Up the Snoop Servlet Example (TAI-Only) ................................................... 100
Set Up the Snoop Servlet Example (All Modules) ................................................ 101
Access the Snoop Servlet in a Web Browser .................................................... 103
Chapter 7: Configuring Policies for the SiteMinder Agent 105
Configure SiteMinder Policies to Support J2EE Roles ............................................ 105
Configure the SmJaccRoles Realm ......................................................... 106
Configure Role-Mapping Rules ............................................................ 106
Configure Role-Mapping Policies .......................................................... 107
Resource Mapping ........................................................................... 107
Web Application Resources ............................................................... 107
Configure HTTP Transport Guarantees for Web Application Resources ........................ 108
Map EJB Resources ....................................................................... 110
Configure Rules for the JACC Provider ......................................................... 111
Configure Authentication and Authorization Responses ......................................... 112
Configure SiteMinder Policies to Support User Mapping (Optional) ............................... 112
Configure Authorization Policies for the SiteMinder Agent ....................................... 114
Chapter 8: Obtaining SiteMinder Agent Data Programmatically 115
Common HashMap Response Structure ........................................................ 115
Obtain Authentication Responses and Other Data from the SiteMinder Principal .................. 116
Obtain Authorization Responses for Web Requests from HTTP Request Attributes ................. 118
Chapter 9: Session Handling 119
Session Synchronization Between WebSphere and the SiteMinder Agent ......................... 119
Contents 7
Timeout Handling ............................................................................ 119
Single Log Off Handling ....................................................................... 120
Chapter 10: Logging 121
Log Files .................................................................................... 121
SiteMinder Agent Log File ................................................................. 122
Default SiteMinder Agent Log File ......................................................... 122
Record Messages to the Default SiteMinder Agent Log File ...................................... 123
Append Messages to an Existing Log File ....................................................... 123
Display SiteMinder Agent Log Messages in a Console ............................................ 123
Set Log Levels ............................................................................... 123
Dynamically Update the SiteMinder Agent Log Files ............................................. 125
Roll Over the Log File ......................................................................... 125
Appendix A: SiteMinder Agent Installation and Configuration
Files 127
SiteMinder Agent Files ....................................................................... 127
Modify Configuration Files .................................................................... 128
Guidelines for Modifying Configuration Files ................................................ 129
Agent Configuration Parameters .......................................................... 130
Trusted Host Configuration ............................................................... 136
Enable and Disable SiteMinder Agent Modules ................................................. 136
Appendix B: Troubleshooting 137
General Troubleshooting Guidelines ........................................................... 138
WebSphere Application Server Does Not Start .................................................. 138
Message While Loading JVM .................................................................. 142
Host Registration Fails During Installation ...................................................... 143
WebSphere Starts With No Indication That SiteMinder Agent Module Loads ...................... 144
SiteMinder Agent Initialization Fails ........................................................... 144
SiteMinder TAI Forms Authentication Scheme Failures .......................................... 146
Identity Obtained by TAI Not Propagated to WebSphere ........................................ 147
SiteMinder Agent Initializes but WebSphere Challenges Security ................................. 148
User Not Challenged for Credentials ........................................................... 149
SiteMinder TAI in No Challenge Mode Not Intercepting Requests ................................ 150
500 Error Accessing Any Servlet/EJB ........................................................... 151
User Challenged for Credentials Before WebSphere Session Expires .............................. 151
8 Agent Guide
User Mapping Not Working for Login Module-Protected Resources .............................. 152
Resetting the Level of the IIS Web Agent ....................................................... 152

Contents 9